Built-in Functions and Types

Mars features a small number of primitive functions and types, 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) :: Int

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 :: Int, y :: Int) :: Int

-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 :: Int, y :: Int) :: Int

Returns x + y.

sub(x :: Int, y :: Int) :: Int

Returns x - y.

mul(x :: Int, y :: Int) :: Int

Returns x × y.

div(x :: Int, y :: Int) :: Int

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

mod(x :: Int, y :: Int) :: Int

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.

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 :: Int, 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 negative.

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

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

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

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

array_length(array :: Array(a)) :: Int

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.

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.

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

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

I/O

put_char(char :: Int) :: Int

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

get_char() :: Int

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(Int)) :: Array(Int)

Returns the value of an environment variable named by the string name. It is an error if any element of name is 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(Int)

Returns a string representation of value, which represents the value in Mars syntax if possible. Note that as strings are indistinguishable from arrays of integers, 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(Int)) :: 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.