prelude — Common functions

The prelude is where the most common functions are found. This module is typically imported by any Mars module. It is not imported by default, but if mars is run without any command-line arguments, this module will be loaded.

Higher-order helper functions

id(x :: a) :: a = x

The identity function; returns x.

const(k :: a) :: ba

Returns a function which returns k, regardless of its argument.

apply0(f :: () → r) :: r = f()

Calls f with no arguments.

apply1(f :: ar, x :: a) :: r = f(x)

Calls f with x as an argument.

apply2(f :: (a, b) → r, x :: a, y :: b) :: r = f(x, y)

Calls f with x and y as arguments.

curry2(f :: (a, b) → r) :: abr

Converts f into a curried function – the resulting function takes one argument and returns a function that takes the second argument and calls f with both.

curry3(f :: (a, b, c) → r) :: abcr

Converts f into a curried function – the resulting function takes one argument and returns a function that takes the second argument and so on, and calls f with all of the arguments.

curry4(f :: (a, b, c, d) → r) :: abcdr

Converts f into a curried function – the resulting function takes one argument and returns a function that takes the second argument and so on, and calls f with all of the arguments.

compose(f :: bc, g :: ab) :: ac

Creates a function which takes one argument and passes it to g, then passes the result of that to f.

flip(f :: (a, b) → c) :: (b, a) → c

Creates a function which passes its two arguments to f in the reverse order.

Logic functions

false :: Int = 0

The integer 0, representing false.

true :: Int = 1

The integer 1, representing true.

and(x :: Int, y :: Int) :: Int

The Boolean AND of x and y. If x is nonzero, returns y; otherwise, returns 0.

or(x :: Int, y :: Int) :: Int

The Boolean OR of x and y. If x is zero, returns y; otherwise, returns x.

not(x :: Int) :: Int

The Boolean NOT of x. If x is zero, returns 1; otherwise, returns 0.

Comparison functions

ne(x :: a, y :: a) :: Int

1 if x is not equal to y (according to eq), 0 otherwise.

lt(x :: Int, y :: Int) :: Int

1 if x is less than y, 0 otherwise.

le(x :: Int, y :: Int) :: Int

1 if x is less than or equal to y, 0 otherwise.

gt(x :: Int, y :: Int) :: Int

1 if x is greater than y, 0 otherwise.

ge(x :: Int, y :: Int) :: Int

1 if x is greater than or equal to y, 0 otherwise.

Arithmetic

neg(x :: Int) :: Int

Returns the negation of x (0 - x).

abs(x :: Int) :: Int

Returns the absolute value of x (a positive number with the same magnitude).

min(x :: Int, y :: Int) :: Int

The lesser value of x and y.

max(x :: Int, y :: Int) :: Int

The greater value of x and y.

Tuple types and operations

Note

Mars doesn’t have a general tuple type. It just defines specific types for tuples of arity two, three and four.

type Pair(a, b)
Pair(a, b)

A pair of any two values.

fst(pair :: Pair(a, b)) :: a

The first value of a given pair.

snd(pair :: Pair(a, b)) :: b

The second value of a given pair.

type Triple(a, b, c)
Triple(a, b, c)

A sequence of any three values.

type Quadruple(a, b, c, d)
Quadruple(a, b, c, d)

A sequence of any four values.

Linked List type and operations

type List(a)
Cons(head :: a, tail :: List(a))
Nil

A linked list of values, all of the same type. This type is incompatible with the Array type, but it is possible to convert between the two using list_to_array and array_to_list.

empty(list :: List(a)) :: Int

Test if list is empty. 1 if it is empty, 0 otherwise.

The first item in list. Aborts if list is empty.

tail(list :: List(a)) :: List(a)

The list corresponding to all but first item in list. Aborts if list is empty.

ref(list :: List(a), index :: Int) :: a

The element of list with index index. The first element has index 0. It is an error if index is equal to or greater than the length of the list, or negative.

length(list :: List(a)) :: Int

The number of elements in list.

map(function :: ab, list :: List(a)) :: List(b)

Applies function to each item in list, producing a new list containing each of the results. For example, map(f, array_to_list([a, b, c])) computes array_to_list([f(a), f(b), f(c)]).

filter(predicate :: aInt, list :: List(a)) :: List(a)

Produces a new list containing only the items in list for which function returns a nonzero result.

foldl(function :: (a, b) → a, initial :: a, list :: List(b)) :: a

Applies function to initial and the head of list, then to the result of that and the second element of list, and so on, returning the result of the final application. For example, foldl(f, z, array_to_list([a, b, c])) computes f(f(f(z, a), b), c).

foldl1(function :: (a, a) → a, list :: List(a)) :: a

foldl without an initial value. Applies function to the first and second elements of list, then to the result of that and the third element of list, and so on, returning the result of the final application. For example, foldl1(f, array_to_list([a, b, c, d])) computes f(f(f(a, b), c), d).

foldr(function :: (a, b) → b, initial :: b, list :: List(a)) :: b

Applies function to the last element of list and initial, then to the second-last element of list and the result of that, and so on, returning the result of the final application. For example foldr(f, z, array_to_list([a, b, c])) computes f(a, f(b, f(c, z))).

foldr1(f :: (a, a) → a, l :: List(a)) :: a

foldr without an initial value. Applies function to the second-last and last elements of list, then to the third-last element and the result of that, and so on, returning the result of the final application. For example, foldr1(f, array_to_list([a, b, c, d])) computes f(a, f(b, f(c, d))).

sum(list :: List(Int)) :: Int

Computes the sum of all integers in list.

minimum(list :: List(Int)) :: Int

Computes the minimum of all integers in list.

maximum(list :: List(Int)) :: Int

Computes the minimum of all integers in list.

reverse(list :: List(a)) :: List(a)

Returns the elements of list in reverse order.

append(list1 :: List(a), list2 :: List(a)) :: List(a)

Returns the elements of list1 concatenated onto the front of list2. Note that this operation is linear in the length of list1, but constant in the length of list2 (it makes a copy of list1 but not list2).

index(list :: List(a), item :: a) :: Int

Returns the index of the first element of list which compares equal (according to eq) to item, or -1 if no element compares equal. The first element has index 0.

elem(item :: a, list :: List(a)) :: Int

Returns 1 if any element of list compares equal (according to eq) to item; 0 otherwise.

zip(list1 :: List(a), list2 :: List(b)) :: List(Pair(a, b))

Combine pairwise elements of list1 and list2 into a single list of pairs. For example, zip(array_to_list([a, b, c]), array_to_list([x, y, z])) produces array_to_list([Pair(a, x), Pair(b, y), Pair(c, z)]). If the two lists are not the same length, the resulting list is as long as the shorter list, with the remaining elements of the longer list discarded.

unzip(list :: List(Pair(a, b))) :: Pair(List(a), List(b))

Separate a list of pairs into a pair of lists with corresponding elements of list. The first output list contains the fst of each element of list, and the second output list contains the snd of each element. For example, unzip(array_to_list([Pair(a, x), Pair(b, y), Pair(c, z)])) produces Pair(array_to_list([a, b, c]), array_to_list([x, y, z])).

range(start :: Int, end :: Int) :: List(Int)

Returns a list of integers from start, inclusive, to end, exclusive.

list_to_array(list :: List(a)) :: Array(a)

Convert list to an Array of the same elements.

array_to_list(array :: Array(a)) :: List(a)

Convert array to a List of the same elements.

Array operations

array_map(function :: ab, array :: Array(a)) :: Array(b)

Applies function to each item in array, producing a new array containing each of the results. For example, array_map(f, [a, b, c]) computes [f(a), f(b), f(c)].

array_filter(function :: aInt, array :: Array(a)) :: Array(a)

Produces a new array containing only the items in array for which function returns a nonzero result.

array_foldl(function :: (a, b) → a, initial :: a, array :: Array(b)) :: a

Applies function to initial and the first element of array, then to the result of that and the second element of array, and so on, returning the result of the final application. For example, array_foldl(f, z, [a, b, c]) computes f(f(f(z, a), b), c).

array_foldl1(function :: (a, a) → a, array :: Array(a)) :: a

array_foldl without an initial value. Applies function to the first and second elements of array, then to the result of that and the third element of array, and so on, returning the result of the final application. For example, array_foldl1(f, [a, b, c, d]) computes f(f(f(a, b), c), d).

array_foldr(function :: (a, b) → b, initial :: b, array :: Array(a)) :: b

Applies function to the last element of array and initial, then to the second-last element of array and the result of that, and so on, returning the result of the final application. For example array_foldr(f, z, [a, b, c]) computes f(a, f(b, f(c, z))).

array_foldr1(function :: (a, a) → a, array :: Array(a)) :: a

array_foldr without an initial value. Applies function to the second-last and last elements of array, then to the third-last element and the result of that, and so on, returning the result of the final application. For example, array_foldr1(f, [a, b, c, d]) computes f(a, f(b, f(c, d))).

array_substr(array :: Array(a), start :: Int, length :: Int) :: Array(a)

Returns an array consisting of all elements of array from start, inclusive, to start + length, exclusive. Out-of-range indices are dropped silently, so the resulting array may be shorter than length.

array_index(array :: Array(a), item :: a) :: Int

Returns the index of the first element of array which compares equal to item, or -1 if no element compares equal. The first element has index 0.

array_elem(item :: a, array :: Array(a)) :: Int

Returns 1 if item is an element of array; 0 otherwise.

array_zip(array1 :: Array(a), array2 :: Array(b)) :: Array(Pair(a, b))

Combine pairwise elements of array1 and array2 into a single array of pairs. For example, zip([a, b, c], [x, y, z]) produces [Pair(a, x), Pair(b, y), Pair(c, z)]. If the two arrays are not the same length, the resulting array is as long as the shorter array, with the remaining elements of the longer array discarded.

array_unzip(array :: Array(Pair(a, b))) :: Pair(Array(a), Array(b))

Separate an array of pairs into a pair of arrays with corresponding elements of array. The first output array contains the fst of each element of array, and the second output array contains the snd of each element. For example, unzip([Pair(a, x), Pair(b, y), Pair(c, z)]) produces Pair([a, b, c], [x, y, z]).

array_range(start :: Int, end :: Int) :: Array(Int)

Returns an array of integers from start, inclusive, to end, exclusive.

Maybe type

type Maybe(a)
Just(value :: a)
Nothing

A container for a single value, which may or may not exist. As Mars has no “null” value, any value which might be non-existant should have type Maybe(a), and non-existant values should be represented as Nothing.

I/O

eof :: Int = -1

Represents the “end of file” condition in the output of the built-in function get_char. Note that eof is not actually a character; it is a special value indicating that no more bytes can be read from a file.

Writes string to standard output, where string is a list of byte integers. This calls put_char on each element of string. It is an error if any element is outside the range [0, 255]. Does not print a newline. See also: print_string.

Writes string to standard output. This calls put_char on each element of string. It is an error if any element is outside the range [0, 255]. Does not print a newline.

Writes a string representation of value to standard output. This is equivalent to print_string(show(value)). See also: print_string, show.

get_line_list() :: List(Int)

Reads a line (sequence of bytes terminated by '\n') from standard input, returning a list of byte values. The list does not contain the '\n' character. See also: get_line.

get_line() :: Array(Int)

Reads a line (sequence of bytes terminated by '\n') from standard input, returning a string. The string does not contain the '\n' character.