Verified Commit 3e1a5743 authored by Camil Staps's avatar Camil Staps 🚀

Documentation

parent 3e5127d8
system module StdBool system module StdBool
/**
* Class instances and basic functions for the Bool type.
*/
// **************************************************************************************** // ****************************************************************************************
// Concurrent Clean Standard Library Module Version 2.0 // Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen // Copyright 1998 University of Nijmegen
...@@ -16,7 +20,30 @@ instance fromBool {#Char} ...@@ -16,7 +20,30 @@ instance fromBool {#Char}
// Additional Logical Operators: // Additional Logical Operators:
not :: !Bool -> Bool // Not arg1 /**
(||) infixr 2 :: !Bool Bool -> Bool // Conditional or of arg1 and arg2 * Logical negation.
(&&) infixr 3 :: !Bool Bool -> Bool // Conditional and of arg1 and arg2 *
* @param The boolean to negate
* @result True if the parameter was False; False if True
*/
not :: !Bool -> Bool
/**
* Logical disjunction. The second parameter is not strict and will not be
* evaluated if the first parameter is True.
*
* @param First boolean
* @param Second boolean
* @result True iff at least one of the parameters is True
*/
(||) infixr 2 :: !Bool Bool -> Bool
/**
* Logical conjunction. The second parameter is not strict and will not be
* evaluated if the first parameter is False.
*
* @param First boolean
* @param Second boolean
* @result True iff both parameters are True
*/
(&&) infixr 3 :: !Bool Bool -> Bool
system module StdChar system module StdChar
/**
* Class instances and basic functions for the Char type.
*/
// **************************************************************************************** // ****************************************************************************************
// Concurrent Clean Standard Library Module Version 2.0 // Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen // Copyright 1998 University of Nijmegen
...@@ -24,20 +28,116 @@ instance fromChar {#Char} ...@@ -24,20 +28,116 @@ instance fromChar {#Char}
// Additional conversions: // Additional conversions:
digitToInt :: !Char -> Int // Convert Digit into Int /**
toUpper :: !Char -> Char // Convert Char into an uppercase Char * Converts a character from ['0'..'9'] to an integer.
toLower :: !Char -> Char // Convert Char into a lowercase Char *
* @param The character
* @result 0-9 if the character was from ['0'..'9'], otherwise another Int
*/
digitToInt :: !Char -> Int
/**
* Converts a character to uppercase.
*
* @param The character
* @result The same character, with bit 5 cleared
*/
toUpper :: !Char -> Char
/**
* Converts a character to lowercase.
*
* @param The character
* @result The same character, with bit 5 set
*/
toLower :: !Char -> Char
// Tests on Characters: // Tests on Characters:
isUpper :: !Char -> Bool // True if arg1 is an uppercase character /**
isLower :: !Char -> Bool // True if arg1 is a lowercase character * Check for uppercase
isAlpha :: !Char -> Bool // True if arg1 is a letter *
isAlphanum :: !Char -> Bool // True if arg1 is an alphanumerical character * @param The character
isDigit :: !Char -> Bool // True if arg1 is a digit * @result True iff the parameter is from ['A'..'Z']
isOctDigit :: !Char -> Bool // True if arg1 is a digit */
isHexDigit :: !Char -> Bool // True if arg1 is a digit isUpper :: !Char -> Bool
isSpace :: !Char -> Bool // True if arg1 is a space, tab etc
isControl :: !Char -> Bool // True if arg1 is a control character /**
isPrint :: !Char -> Bool // True if arg1 is a printable character * Check for lowercase
isAscii :: !Char -> Bool // True if arg1 is a 7 bit ASCII character *
* @param The character
* @result True iff the parameter is from ['a'..'z']
*/
isLower :: !Char -> Bool
/**
* Check for an alphabetic character
*
* @param The character
* @result True iff the parameter is from ['a'..'z'] ++ ['A'..'Z']
*/
isAlpha :: !Char -> Bool
/**
* Check for an alphabetic or numerical character
*
* @param The character
* @result True iff the parameter is from ['a'..'z'] ++ ['A'..'Z'] ++ ['0'..'9']
*/
isAlphanum :: !Char -> Bool
/**
* Check for a numerical character
*
* @param The character
* @result True iff the parameter is from ['0'..'9']
*/
isDigit :: !Char -> Bool
/**
* Check for an octal digit
*
* @param The character
* @result True iff the parameter is from ['0'..'7']
*/
isOctDigit :: !Char -> Bool
/**
* Check for a hexadecimal digit
*
* @param The character
* @result True iff the parameter is from ['0'..'9'] ++ ['a'..'f'] ++ ['A'..'F']
*/
isHexDigit :: !Char -> Bool
/**
* Check for whitespace
*
* @param The character
* @result True iff the parameter is one of ' ', '\t', '\n', '\r', '\f', '\v'
*/
isSpace :: !Char -> Bool
/**
* Check for an ASCII control character
*
* @param The character
* @result True iff the parameter is from ['\x00'..'\x1f'] ++ ['\x7f']
*/
isControl :: !Char -> Bool
/**
* Check for a printable ASCII character
*
* @param The character
* @result True iff the parameter is from [' '..'~']
*/
isPrint :: !Char -> Bool
/**
* Check for a 7-bit ASCII character
*
* @param The character
* @result True iff the integer value of the parameter is less than 128
*/
isAscii :: !Char -> Bool
definition module StdCharList definition module StdCharList
/**
* Basic functions for manipulating lists of characters.
*/
// **************************************************************************************** // ****************************************************************************************
// Concurrent Clean Standard Library Module Version 2.0 // Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen // Copyright 1998 University of Nijmegen
// **************************************************************************************** // ****************************************************************************************
cjustify :: !.Int ![.Char] -> .[Char] // Center [Char] in field with width arg1 /**
ljustify :: !.Int ![.Char] -> .[Char] // Left justify [Char] in field with width arg1 * Center-align a text with spaces, s.t. the right margin is 0 or 1 spaces
rjustify :: !.Int ![.Char] -> [Char] // Right justify [Char] in field with width arg1 * longer than the left margin.
*
* @param The minimum length of the result
* @param The text to center
* @result A list of max(|param 2|, param 1), with param 2 surrounded by spaces
*/
cjustify :: !.Int ![.Char] -> .[Char]
/**
* Left-align a text with spaces
*
* @param The minimum length of the result
* @param The text to align
* @result A list of max(|param 2|, param 1), with spaces appended to param 2
*/
ljustify :: !.Int ![.Char] -> .[Char]
/**
* Right-align a text with spaces
*
* @param The minimum length of the result
* @param The text to align
* @result A list of max(|param 2|, param 1), with spaces prepended to param 2
*/
rjustify :: !.Int ![.Char] -> [Char]
/**
* Concatenate a list of texts, interspersing it with newlines
*
* @param The texts
* @result All texts concatenated, with newlines in between
*/
flatlines :: ![[u:Char]] -> [u:Char]
flatlines :: ![[u:Char]] -> [u:Char] // Concatenate by adding newlines /**
mklines :: ![Char] -> [[Char]] // Split in lines removing newlines * Split a text on newlines
*
* @param The text
* @result A list of texts without newlines
*/
mklines :: ![Char] -> [[Char]]
spaces :: !.Int -> .[Char] // Make [Char] containing n space characters /**
* A list of a number of ' ' characters
*
* @param The number of characters
* @result A list of param 1 spaces
*/
spaces :: !.Int -> .[Char]
definition module StdDebug definition module StdDebug
/**
* Functions that write intermediate results to stderr for debugging purposes.
*/
// ******************************************************** // ********************************************************
// Concurrent Clean Standard Library Module Version 2.0 // Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen // Copyright 1998 University of Nijmegen
...@@ -12,16 +16,48 @@ from StdString import instance toString {#Char},instance toString Int ...@@ -12,16 +16,48 @@ from StdString import instance toString {#Char},instance toString Int
// The following functions should only be used for debugging, // The following functions should only be used for debugging,
// because these functions have side effects // because these functions have side effects
trace :: !msg .a -> .a | toString msg // write toString msg to stderr /**
// before evaluating a * Write a message to stderr before returning a value.
special msg={#Char}; msg=Int *
trace_n :: !msg .a -> .a | toString msg // write toString msg and newline to stderr * @param The message to write to stderr
// before evaluating a * @param The value to return
special msg={#Char}; msg=Int * @result Param 2
*/
trace_t :: !msg -> Bool | toString msg // write toString msg to stderr trace :: !msg .a -> .a | toString msg special msg={#Char}; msg=Int
// result is True
special msg={#Char}; msg=Int /**
trace_tn :: !msg -> Bool | toString msg // write toString msg and newline to stderr * Write a message and a newline to stderr before returning a value.
// result is True *
special msg={#Char}; msg=Int * @param The message to write to stderr
* @param The value to return
* @result Param 2
*/
trace_n :: !msg .a -> .a | toString msg special msg={#Char}; msg=Int
/**
* Write a message to stderr and return True. This is useful in guards, for
* example:
*
* ```
* square x
* | trace_t x = x * x
* ```
*
* @param The message to write to stderr
* @result True
*/
trace_t :: !msg -> Bool | toString msg special msg={#Char}; msg=Int
/**
* Write a message and a newline to stderr and return True. This is useful in
* guards, for example:
*
* ```
* square x
* | trace_tn x = x * x
* ```
*
* @param The message to write to stderr
* @result True
*/
trace_tn :: !msg -> Bool | toString msg special msg={#Char}; msg=Int
definition module StdEnv definition module StdEnv
/**
* Clean's official Standard Environment library.
*/
// **************************************************************************************** // ****************************************************************************************
// Concurrent Clean Standard Library Module Version 2.0 // Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen // Copyright 1998 University of Nijmegen
......
...@@ -5,19 +5,83 @@ definition module StdFunc ...@@ -5,19 +5,83 @@ definition module StdFunc
// Copyright 1998 University of Nijmegen // Copyright 1998 University of Nijmegen
// **************************************************************************************** // ****************************************************************************************
id :: !.a -> .a // identity function /**
const :: !.a .b -> .a // constant function * The identity function.
*
* @param A value
* @result The same value
*/
id :: !.a -> .a
//flip :: !.(.a -> .(.b -> .c)) .b .a -> .c // Flip arguments /**
* The constant function.
*
* @param A value
* @param Another value
* @result The first value
*/
const :: !.a .b -> .a
/**
* Flip the arguments of a function. This is useful in function compositions.
*
* @type !.(.a -> .(.b -> .c)) .b .a -> .c
* @param A function
* @param The second argument to the function
* @param The first argument to the function
* @result The function, applied to its arguments
*/
flip f a b :== f b a flip f a b :== f b a
(o) infixr 9 // :: u:(.a -> .b) u:(.c -> .a) -> u:(.c -> .b) // Function composition /**
* Function composition.
*
* @type u:(.a -> .b) u:(.c -> .a) -> u:(.c -> .b)
* @param A function f
* @param A function g
* @result The function f o g, that is, f applied after g
*/
(o) infixr 9
(o) f g :== \ x -> f (g x) (o) f g :== \ x -> f (g x)
twice :: !(.a -> .a) .a -> .a // f (f x) /**
while :: !(a -> .Bool) (a -> a) a -> a // while (p x) f (f x) * Apply a function twice.
until :: !(a -> .Bool) (a -> a) a -> a // f (f x) until (p x) *
iter :: !Int (.a -> .a) .a -> .a // f (f..(f x)..) * @param A function f
* @param A value x
* @result f (f x)
*/
twice :: !(.a -> .a) .a -> .a
/**
* Apply a function as long as a property holds.
*
* @param A property p
* @param A function f
* @param An initial value x
* @result x if not p x, otherwise while p f (f x)
*/
while :: !(a -> .Bool) (a -> a) a -> a
/**
* Apply a function until a property holds.
*
* @param A property p
* @param A function f
* @param An initial value x
* @result x if p x, otherwise until p f (f x)
*/
until :: !(a -> .Bool) (a -> a) a -> a
/**
* Apply a function a number of times.
*
* @param The number of iterations n
* @param The function
* @param The initial value
* @result The result of applying the function n times to the initial value
*/
iter :: !Int (.a -> .a) .a -> .a
// Some handy functions for transforming unique states: // Some handy functions for transforming unique states:
......
system module StdInt system module StdInt
/**
* Class instances and basic functions for the Int type.
*/
// **************************************************************************************** // ****************************************************************************************
// Concurrent Clean Standard Library Module Version 2.0 // Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen // Copyright 1998 University of Nijmegen
...@@ -48,11 +52,64 @@ instance lcm Int // Least common multiple ...@@ -48,11 +52,64 @@ instance lcm Int // Least common multiple
// Operators on Bits: // Operators on Bits:
(bitor) infixl 6 :: !Int !Int -> Int // Bitwise Or of arg1 and arg2 /**
(bitand) infixl 6 :: !Int !Int -> Int // Bitwise And of arg1 and arg2 * Bitwise disjunction.
(bitxor) infixl 6 :: !Int !Int -> Int // Exclusive-Or arg1 with mask arg2 *
(<<) infix 7 :: !Int !Int -> Int // Shift arg1 to the left arg2 bit places * @param The first integer
(>>) infix 7 :: !Int !Int -> Int // Shift arg1 to the right arg2 bit places * @param The second integer
bitnot :: !Int -> Int // One's complement of arg1 * @result An integer with exactly those bits set that at least one of the parameters has set
*/
(bitor) infixl 6 :: !Int !Int -> Int
/**
* Bitwise conjunction.
*
* @param The first integer
* @param The second integer
* @result An integer with exactly those bits set that both of the parameters have set
*/
(bitand) infixl 6 :: !Int !Int -> Int
/**
* Bitwise exclusive disjunction.
*
* @param The first integer
* @param The second integer
* @result An integer with exactly those bits set that exactly one of the parameters has set
*/
(bitxor) infixl 6 :: !Int !Int -> Int
/**
* Shift an integer to the left.
*
* @param The integer to shift
* @param The number of places to shift
* @result The result of the bitshift
*/
(<<) infix 7 :: !Int !Int -> Int
/**
* Shift an integer to the right.
*
* @param The integer to shift
* @param The number of places to shift
* @result The result of the bitshift
*/
(>>) infix 7 :: !Int !Int -> Int
/**
* Bitwise logical negation.
*
* @param An integer
* @param The one's complement of the parameter
*/
bitnot :: !Int -> Int
/**
* Compile-time macro to check for the integer length of the system.
*
* @param The value if the platform is 64-bit
* @param The value if the platform is 32-bit
* @result Either of the parameters, depending on the platform
*/
IF_INT_64_OR_32 int64 int32 :== int32; IF_INT_64_OR_32 int64 int32 :== int32;
system module StdMisc system module StdMisc
/**
* Miscellaneous functions.
*/
// **************************************************************************************** // ****************************************************************************************
// Concurrent Clean Standard Library Module Version 2.0 // Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen // Copyright 1998 University of Nijmegen
// **************************************************************************************** // ****************************************************************************************
abort :: !{#Char} -> .a // stop reduction and print argument /**
undef :: .a // fatal error, stop reduction. * Print a message and abort the program.
*
* @param The message to print
* @result There is no result; the program will terminate
*/
abort :: !{#Char} -> .a
/**
* The undefined value.
*
* @result An attempt to evaluate the result will yield a runtime error.
*/
undef :: .a
system module StdReal system module StdReal
/**
* Class instances and basic functions for the Real type.
*/
// **************************************************************************************** // ****************************************************************************************
// Concurrent Clean Standard Library Module Version 2.0 // Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen // Copyright 1998 University of Nijmegen
...@@ -56,4 +60,10 @@ instance atanh Real // Arc Hyperbolic Tangent, partial function, only defined i ...@@ -56,4 +60,10 @@ instance atanh Real // Arc Hyperbolic Tangent, partial function, only defined i
// Additional conversion: // Additional conversion:
entier :: !Real -> Int // Convert Real into Int by taking entier /**
* Imprecise conversion from Real to Int.
*
* @param A Real
* @result The largest integer smaller than the parameter
*/
entier :: !Real -> Int
system module StdString system module StdString
/**
* Class instances and basic functions for the String type.
*/
// **************************************************************************************** // ****************************************************************************************
// Concurrent Clean Standard Library Module Version 2.0 // Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen // Copyright 1998 University of Nijmegen
...@@ -26,6 +30,21 @@ instance % {#Char} ...@@ -26,6 +30,21 @@ instance % {#Char}
instance +++ {#Char} // string concatenation instance +++ {#Char} // string concatenation
(+++.) infixr 5 :: !{#Char} !{#Char} -> .{#Char} // string concatenation with unique result /**
* Concatenate two strings with a unique result. This is similar to +++, except
(:=) infixl 9 :: !{#Char} !(!Int,!Char) -> {#Char} // update i-th element with char * that the result type is unique.
*
* @param A string
* @param A string
* @result The concatenation of the two strings
*/
(+++.) infixr 5 :: !{#Char} !{#Char} -> .{#Char}
/**
* Update a character in a string.
*
* @param The string
* @param A tuple of the index and the new character
* @result The new string, with the new character on the specified position
*/
(:=) infixl 9 :: !{#Char} !(!Int,!Char) -> {#Char}
definition module StdTuple definition module StdTuple
/**
* Class instances and basic functions for tuples.
*/
// **************************************************************************************** // ****************************************************************************************
// Concurrent Clean Standard Library Module Version 2.0 // Concurrent Clean Standard Library Module Version 2.0
// Copyright 1998 University of Nijmegen // Copyright 1998 University of Nijmegen
...@@ -7,16 +11,49 @@ definition module StdTuple ...@@ -7,16 +11,49 @@ definition module StdTuple
import StdClass import StdClass
// fst :: !(!.a,.b) -> .a // t1 of (t1,t2)