Standard library functions
The Chi language has many general purpose functions available. They are organized by type and kind of use.
Integer functions
The following standard library functions on integers exist:
-
intabs(int val)Return the absolute value of
val. -
intsign(int val)Return
-1if val less than zero,1if val more than zero, and0otherwise. -
intmax(int a, b, ...)Return the biggest value of the parameters.
-
intmin(int a, b, ...)Return the smallest value of the parameters.
Real number functions
The following standard library functions on real numbers exist:
-
realabs(real val)Return the absolute value of
val. -
intsign(real val)Return
-1if val less than zero,1if val more than zero, and0otherwise. -
realmax(real a, b, ...)Return the biggest value of the parameters. Integer parameters are silently promoted to real.
-
realmin(real a, b, ...)Return the smallest value of the parameters. Integer parameters are silently promoted to real.
Conversion from real number to integer can be performed in three different ways.
-
intceil(real val)Return smallest integer bigger or equal to
val. -
intfloor(real val)Return biggest integer less or equal to
val. -
intround(real val)Round to nearest integer value (up if distance is
0.5).
The following power and logarithmic functions exist.
-
realsqrt(real val)Return the square root of
val(argument must be non-negative). -
realcbrt(real val)Return the cube root of
val(val^(1/3)). -
realexp(real x)Compute
e^x. -
realln(real x)Compute the natural logarithm of
x. -
reallog(real x)Compute the base-10 logarithm of
x.
Finally, there are trigonometric functions available.
-
realcos(real a)Cosine function of angle
a(in radians). -
realsin(real angle)Sine function of angle
a(in radians). -
realtan(real angle)Tangent function of angle
a(in radians). -
realacos(real val)Arc cosine function of value
val. -
realasin(real val)Arc sine function of value
val. -
realatan(real val)Arc tangent function of value
val. -
realcosh(real val)Hyperbolic cosine function of value
val. -
realsinh(real val)Hyperbolic sine function of value
val. -
realtanh(real val)Hyperbolic tangent function of value
val. -
realacosh(real val)Inverse hyperbolic cosine function of value
val. -
realasinh(real val)Inverse hyperbolic sine function of value
val. -
realatanh(real val)Inverse hyperbolic tangent function of value
val.
String functions
The following string functions exist in the standard library.
-
intsize(string s)Get the number of characters in string
s. -
stringmax(string a, b, ...)Return the biggest string of the parameters.
-
stringmin(string a, b, ...)Return the smallest string of the parameters.
List functions
Getting an element out of list can be done in two ways.
-
tuple(T value, list T ys)pop(list T xs)Get the first element of non-empty list
xs(with arbitrary element typeT), and return a tuple with the first element and the list without the first element. -
list Tdel(list T xs, int index)Remove element
xs[index]from listxs(with arbitrary typeT). The index position must exist in the list. Returns a list without the removed element.
For getting information about the number of elements in a list, the following functions are available.
-
boolempty(list T xs)Is list
xsempty (for any element typeT)? Returnstruewhenxscontains no elements, andfalsewhen it has at least one element. -
intsize(list T xs)Get the number of elements in list
xs(for any element typeT).
List functions mainly useful for using with a for statement (explained in For loop statement) follow next.
-
list tuple(int index, T value)enumerate(list T xs)Construct a copy of the list
xswith arbitrary element typeT, with each element replaced by a tuple containing the index of the element as well as the element itself. For example,enumerate(["a", "b"])results in the list[(0, "a"), (1, "b")]. -
list intrange(int end)Construct a list with integer values running from
0to (but not including)end. For examplerange(3)produces list[0, 1, 2]. -
list intrange(int start, end)Construct a list with integer values running from
startto (but not including)end. For example,range(3, 7)produces list[3, 4, 5, 6]. -
list intrange(int start, end, step)Construct a list with integer values running from
startto (but not including)end, while incrementing the value with step sizestep. For examplerange(3, 8, 2)produceslist [3, 5, 7]. Negative step sizes are also allowed to construct lists with decrementing values, butstarthas to be larger thanendin that case.
For occasionally getting the biggest or smallest element of a list, the min and max functions are available. These functions take a lot of time, if smallest or biggest values are needed often, it may be better to use a sorted list.
-
Tmin(list T xs)Return the smallest element value of type
T(Tmust be type int, real, or string) from non-empty listxs. -
Tmax(list T xs)Return the biggest element value of type
T(Tmust be type int, real, or string) from non-empty listxs. -
listTsort(list T xs, func bool pred(T a, b))Sort list
xssuch that the predicate functionpredholds for every pair of elements in the list, and return the sorted list.The predicate function
predmust implement a total ordering on the values. See also the sorted lists discussion in the tutorial. -
listTinsert(list T xs, T x, func bool pred(T a, b))Given an already sorted list
xswith respect to predicate functionpred(with arbitrary element typeT), insert element valuexinto the list such that the predicate functionpredagain holds for every pair of elements in the list. Return the list with the insertedelement.The predicate function
predmust implement a total ordering on the values. See also the sorted lists discussion in the tutorial.
Set functions
Similar to lists, there are two functions for getting an element from a set.
-
tuple(T val, set T yr)pop(set T xr)Get an element of non-empty set
xr(with arbitrary element typeT), and return a tuple with the retrieved element and the set without the retrieved element. Note that the order of elements in a set has no meaning, and may change at any moment. -
list tuple(int index, T val)enumerate(set T xr)Construct a list of tuples with position
indexand element valuevalfrom the setxrwith arbitrary element typeT. Note that theindexhas no meaning in the set.
Removing a single element from a set can be done with the function below.
-
set Tdel(set T xr, T value)Remove from set
xr(with arbitrary element typeT) elementvalueif it exists in the set. Returns a set without the (possibly) removed element.
For getting information about the number of elements in a set, the following functions are available.
-
boolempty(set T xr)Is set
xrempty (for any element typeT)? Returnstruewhenxrcontains no elements, andfalsewhen it has at least one element. -
intsize(set T xr)Get the number of elements in set
xr(for any element typeT).
For occasionally getting the biggest or smallest element of a set, the min and max functions are available. These functions take a lot of time, if smallest or biggest values are needed often, it may be better to make a sorted list.
-
Tmin(set T xr)Return the smallest element value of type
T(Tmust be typeint,real, orstring) from non-empty setxr. -
Tmax(set T xr)Return the biggest element value of type
T(Tmust be typeint,real, orstring) from non-empty setxr.
Dictionary functions
Getting a value or a sequence of values from a dictionary can be done with the following functions.
-
tuple(K key, V val, dict(K:V) e)pop(dict(K:V) d)Get a key-value pair from non-empty dictionary
d(with arbitrary key typeKand arbitrary value typeV), and return a tuple with the retrieved key, the retrieved value, and the dictionary without the retrieved element. -
list tuple(int index, K key, V val)enumerate(dict(K:V) d)Construct a list of tuples with position
index, keykeyand valuevalfrom dictionaryd(with arbitrary key typeKand arbitrary value typeV). Note that theindexhas no meaning in the dictionary. In combination with a for statement (explained in For loop statement), it is also possible to iterate over the dictionary directly. -
list Kdictkeys(dict(K:V) d)Return the keys of dictionary
d(with any key typeKand value typeV) as a list with element typeK. Since a dictionary has no order, the order of the elements in the resulting list is also undefined. -
list Vdictvalues(dict(K:V) d)Return the values of dictionary
d(with any key typeKand value typeV) as a list with element typeV. Since a dictionary has no order, the order of the elements in the resulting list is also undefined.
Removing a single element from a dictionary can be done with the function below.
-
dict(K:V)del(dict(K:V) d, K key)Remove element
keyfrom dictionaryd(with arbitrary element key typeKand arbitrary value typeV) if it exists in the dictionary. Returns a dictionary without the (possibly) removed element.
The number of keys in a dictionary can be queried with the following functions.
-
boolempty(dict(K:V) d)Is dictionary
dempty? (with any key typeKand value typeV) Returnstruewhendcontains no elements, andfalsewhen it has at least one key element. -
intsize(dict(K:V) d)Get the number of key elements in dictionary
d(with any key typeKand value typeV).
For occasionally getting the biggest or smallest key value of a dictionary, the min and max functions are available. These functions take a lot of time, if smallest or biggest keys are needed often, it may be better to use a sorted list.
-
Kmin(dict(K:V) d)Return the smallest key of type
K(Kmust be typeint,real, orstring) from non-empty dictionaryd. -
Kmax(dict(K:V) d)Return the biggest key of type
K(Kmust be typeint,real, orstring) from non-empty dictionaryd.
Timer functions
-
boolready(timer t)Return whether timer
thas expired (or was never set). Returnstrueif the timer has reached0or was never set, andfalseif it is still running.
File functions
-
booleof(file handle)For files that are read, this function tests whether the end of the file (EOF) has been reached. That is, it tests whether you have read the last value in the
file.If the call returns
true, there are no more values to read. If it returnsfalse, another value is still available. For an example of how to useeofandeol, see Advanced reading from a file. -
booleol(file handle)For files that are read, this function tests whether the end of a line (EOL) has been reached. That is, it tests whether you have read the last value at the current line.
If the call returns
true, there are no more values to read at this line. If it returnsfalse, another value can be read. For an example of how to useeofandeol, see Advanced reading from a file.Note that 'the same line' is applied only to the leading white space. It does not say anything about the number lines that a value itself uses. For example, you could spread a list or set with numbers over multiple lines.
-
intnewlines(file handle)For files that are read, this function returns how many lines down the next value can be found. It returns a negative number if the end of the file has been reached.
For example, executing:
int i; file f = open("data.txt", "r"); i = read(f, int); writeln("read %d, eol count is %d", i, newlines(f)); i = read(f, int); writeln("read %d, eol count is %d", i, newlines(f)); i = read(f, int); writeln("read %d, eol count is %d", i, newlines(f)); close(f);where "data.txt" contains:
123 345 789produces:
read 123, eol count is 0 read 345, eol count is 1 read 789, eol count is -1After reading
123, the next integer is at the same line, which is0lines down. After reading345, the next value is at the next line, which is1line down. After reading the final value, a negative line count is returned to indicate lack of a next value.Note that 'number of lines down' is applied only to the leading white space. It does not say anything about the number lines that a value itself uses, a set of list could use several lines.
-
fileopen(string filename, string mode)Open the file with name
filenameusing access modemode. When the access mode is"r", the file should exist and is opened for reading. When the access mode is"w", the file is either created or its previous contents is erased. There is no way to append output to an existing file.Notice that filename is a normal Chi string, which means that the
\character needs to be escaped to\\. (That is, use a string like"mydir\\myfile.txt"to open the file with the namemyfile.txtin directory (map)mydir.Alternatively, you may want to use the forward slash
/instead as path component separator.
Process instance functions
-
boolfinished(inst p)Return whether the process stored by process instance
phas finished. Returnstruewhen the process has finished, andfalseif it has not ended yet.