.. Mars Documentation
   Copyright (C) 2008 Matt Giuca
   3/9/2008

.. This program is free software: you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

.. This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

.. You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.

.. _lib-builtins:

Built-in Functions
==================

.. sectionauthor:: Matt Giuca <matt.giuca@gmail.com>
.. moduleauthor::  Matt Giuca <matt.giuca@gmail.com>

*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
--------------------

.. function:: 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).

.. function:: 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
   :mod:`prelude` functions :func:`lt`, :func:`le`, :func:`gt` and :func:`ge`.

Arithmetic
----------

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

   Returns *x* + *y*.

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

   Returns *x* - *y*.

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

   Returns *x* × *y*.

.. function:: 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.

.. function:: 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.

.. function:: 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
   <http://en.wikipedia.org/wiki/Modulo_operation>`_. It is an error if *y* is
   0.

.. function:: floor(x :: Num) :: Num

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

.. function:: 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 :mod:`impure` module contains other operations which perform
   destructive modification to arrays.

.. function:: 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.

.. function:: 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*.

.. function:: 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.

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

   The number of elements in *array*.

.. function:: 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.

.. function:: 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.

.. function:: 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
---

.. function:: 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.

.. function:: get_char() :: io Num

   Reads a single byte from standard input, returning its value. Returns
   :const:`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.

.. function:: 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
-------------

.. function:: 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 :ref:`ref-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.

.. 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.