Built-in Functions

Mars features a small number of primitive functions, which cannot be written in the language itself (since they perform basic arithmetic or I/O operations). These constructs are always available.

Comparison functions

eq(x :: a, y :: a) :: Num

Compare any two values of the same type for equality. This performs “deep” or “structural” equality, such that two values are only considered equal if all of their parts are equal, recursively. Returns 1 if x is equal to y, 0 otherwise. It is an error if the values are function objects (these cannot be compared for structural equality).

cmp(x :: Num, y :: Num) :: Num

-1 if x is less than y, 0 if they are equal, 1 if x is greater than y. This function is a lower-level primitive used to construct the prelude functions lt, le, gt and ge.

Arithmetic

add(x :: Num, y :: Num) :: Num

Returns x + y.

sub(x :: Num, y :: Num) :: Num

Returns x - y.

mul(x :: Num, y :: Num) :: Num

Returns x × y.

fdiv(x :: Num, y :: Num) :: Num

Returns x ÷ y, rounded to the nearest representable floating-point number. It is an error if y is 0.

div(x :: Num, y :: Num) :: Num

Returns x ÷ y, rounded to the nearest integer towards negative infinity. It is an error if y is 0.

mod(x :: Num, y :: Num) :: Num

Returns x mod y, the modulus of floored division, such that div(x,y) * y + mod(x,y) equals x. The result has the same sign as y, the divisor (this is a “modulo” as opposed to “remainder”). For more information, see Wikipedia: Modulo operation. It is an error if y is 0.

floor(x :: Num) :: Num

Returns the largest integer that is less than or equal to x. This rounds x towards negative infinity.

sqrt(x :: Num) :: Num

Returns the square root of x. It is an error if x is negative.

Array operations

Note

All of the array operations are pure, meaning they do not modify the given array object. Instead, they return a new array with the applicable updates. The impure module contains other operations which perform destructive modification to arrays.

array(length :: Num, default :: a) :: Array(a)

Returns a new array of length length with all elements having the value default. It is an error if length is non-integral, negative, or larger than the maximum size of an array.

array_ref(array :: Array(a), index :: Num) :: a

The element of array with index index. The first element has index 0. It is an error if index is non-integral or array has no element at index.

array_replace(array :: Array(a), index :: Num, value :: a) :: Array(a)

Returns a new array which is array with element index replaced with value. It is an error if index is non-integral or array has no element at index.

Performs in-place destructive update if the compiler can determine that array will be eligible for garbage collection after this call.

array_length(array :: Array(a)) :: Num

The number of elements in array.

array_add(array :: Array(a), value :: a) :: Array(a)

Returns a new array which is array with value appended onto the end.

Performs in-place destructive update if the compiler can determine that array will be eligible for garbage collection after this call.

array_concat(array1 :: Array(a), array2 :: Array(a)) :: Array(a)

Returns a new array which is array1 with the elements of array2 appended onto the end.

Performs in-place destructive update of array1 if the compiler can determine that array1 will be eligible for garbage collection after this call.

array_remove(array :: Array(a), index :: Num) :: Array(a)

Returns a new array which is array with element index removed. It is an error if index is non-integral or array has no element at index.

Performs in-place destructive update if the compiler can determine that array will be eligible for garbage collection after this call.

I/O

put_char(char :: Num) :: io Num

Writes char as a byte to standard output. It is an error if char is non-integral or outside the range [0, 255]. Returns 0.

get_char() :: io Num

Reads a single byte from standard input, returning its value. Returns eof (-1) if the end of the file has been reached. An error is raised if the byte could not be read for some other reason.

get_env(name :: Array(Num)) :: io Array(Num)

Returns the value of an environment variable named by the string name. It is an error if any element of name is non-integral or outside the range [1, 255] (note that '\0' is not allowed). If the environment variable is not found, returns the empty string ("").

Miscellaneous

show(value :: a) :: Array(Num)

Returns a string representation of value, which represents the value in Mars syntax if possible. The string representation for each type is specified in Values (note that this specification leaves some things to the implementation). As strings are indistinguishable from arrays of numbers, strings are displayed with array notation. Functions are not shown in Mars notation, but in an implementation-defined manner which may or may not include useful information about the function.

error(message :: Array(Num)) :: a

Raises an error with a user-defined error message, message. It is an error if any element of message is outside the range [0, 255]. Null bytes in message are ignored.

Errors in Mars cannot be caught, so any call to this function is fatal.

Table Of Contents

Previous topic

Mars Library Reference

Next topic

prelude — Common functions

This Page