%% -*- ispell-dictionary: "american" -*-

\chapter{Library of Predefined Functions}\label{annex:library}


\Antescofo includes a set of predefined functions. They are described
mostly in the section~\ref{sec:expression}. For the reader convenience,
we give here a list of these functions. 

\newcommand{\vValue}{\emph{value}\xspace}
\newcommand{\vListable}{\emph{listable}\xspace}

The sequence of name after the function defines the type of the
arguments accepted by a function. For example, ``\code{numeric}'' is
used when an argument must satisfy the predicate \code{@is_numeric},
that is, \code{@is_int} or \code{@is_float}.
%% 
In addition we use the terms \vValue when the function accepts any
kind of arguments.



\paragraph*{Listable Functions.}
\index{function!listable}
\index{listable}

When a function $f$ is marked as \vListable, the function is extended to
accepts \code{tab} arguments in addition to scalar arguments. 
%% 
Usually, the result of the application of $f$ on a tab is the tab
resulting on the point-wise application of $f$ to the scalar elements of
the tab. But for predicate, the result is the predicate that returns
true if the scalar version returns true on all the elements of the tabs.

For example, \code{@abs} is a listable function on numerics: so it can
be applied to a tab of numerics. The results is the tab of the absolute
value of the elements of the tab argument. The function \code{@approx}
is a listable predicate and \texttt{@approx(\emph{u}, \emph{v})} returns
true if \texttt{@approx(\emph{u}[\emph{i}], \emph{v}[\emph{i}])} returns
true for all elements \texttt{\emph{i}} of the tabs \texttt{\emph{u}} and
\texttt{\emph{v}}. 


\paragraph*{Side-Effect.} 
\index{function!pure}
\index{function!side-effect}

\newcommand{\vImpure}{\emph{impure}\xspace}

The majority of functions are ``pure function'', that is, they do not
modify their argument and build a new value for the result. In some
case, the function work by a side-effect. Such function are marked as
\vImpure. We also qualify as \vImpure functions that do not produce a
side-effect but that may returns different values when called with the
same arguments (for example, the functions that return a random
number). 



\bigskip

\newcommand\fitem[1]{\medskip\item[]\hspace*{-9mm}\code{@#1}\index{#1@\protect\atvar{#1}}\,}


\begin{itemize}

      %% // odei_map_function(env) : calcule la map inverse

      %%% -------------------------------------------------------
      %%% arithmetic

      \fitem{+}(\vValue, \vValue), \vListable: prefix form of the infix
      \code{+} binary operator: \code{@+(x, y)} $\equiv$ \code{x+y}. The
      functional form of the operator is useful as an argument of
      a high-order function as in \code{@reduce(@+, v)} which sums up
      all the elements of the tab \code{v}.
      
      The addition of an \code{int} and a \code{float} returns a
      float. 

      The addition of two \code{string} corresponds to the concatenation
      of the arguments. The addition of a string and any other value
      convert this value into its string representation before the
      concatenation. 

      \fitem{-}(numeric, numeric), \vListable: prefix form of the infix
      \code{-} arithmetic operator. Coercions between numeric apply when
      needed. 

      \fitem{*}(numeric, numeric), \vListable: prefix form of the infix
      \code{*} arithmetic operator.  Coercions between numeric apply when
      needed. 

      \fitem{/}(numeric, numeric), \vListable: prefix form of the infix
      \code{/} arithmetic operator.  Coercions between numeric apply when
      needed. 

      \fitem{\%}(numeric, numeric), \vListable: prefix form of the infix
      \code{\%} binary operator.  Coercions between numeric apply when
      needed. 

      %%% -------------------------------------------------------
      %%% relationel 

      \fitem{<}(\vValue, \vValue), \vListable: prefix form of the infix
      \code{<} relational operator. This is a total order: value of
      different type can be compared and the order between unrelated
      type is \emph{ad hoc}. Note however that coercion between numeric
      applies if needed.

      \fitem{>=}(\vValue, \vValue), \vListable: prefix form of the infix
      \code{>=} relational operator.  Same remarks as for \atvar{<}.

      \fitem{==}(\vValue, \vValue), \vListable: prefix form of the infix
      \code{==} relational operator. Same remarks as for \atvar{<}. So,
      beware that \code{1 == 1.0} evaluates to \code{true}. 

      \fitem{!=}(\vValue, \vValue), \vListable: prefix form of the infix
      \code{!=} relational operator. Same remarks as for \atvar{<}.
      needed.

      \fitem{<=}(\vValue, \vValue), \vListable: prefix form of the infix
      \code{<=} relational operator. Same remarks as for \atvar{<}. 

      \fitem{<}(\vValue, \vValue), \vListable: prefix form of the infix
      \code{<} relational operator. Same remarks as for \atvar{<}.


      %%% -------------------------------------------------------
      %%% logic

      \fitem{\&\&}(\vValue, \vValue), \vListable: functional form of the
      infix \code{\&\&} logical conjunction. Contrary to the operator,
      the functional form is \emph{not lazy},
      cf. sect.~\ref{sec:lazy_logical_operator}
      p.~\pageref{sec:lazy_logical_operator}: so \code{@&&(a, b)}
      evaluates \code{b} irrespectively of the value of \code{a}

      \fitem{||}(\vValue, \vValue), \vListable: prefix form of the infix
      \code{||} logical disjunction. Same remarks as for \acode{&&}. 


      
      %%% -------------------------------------------------------

      \fitem{abs}(numeric), \vListable: absolute value 

      %%% -------------------------------------------------------

      \fitem{acos}(numeric), \vListable: arc cosine

      %%% -------------------------------------------------------

      \fitem{add_pair}(map, key:\vValue, \vValue) or (imap, key:numeric,
      numeric): add a new entry to a dictionary or a breakpoint in a
      interpolated map.


      %%% -------------------------------------------------------

      \fitem{aggregate}(n1:nim, n2:nim, \dots) aggregates the arguments
      into a vectorial nim. The number of components of the result is
      the sum of the number of components of each arguments. This
      function admits a variable number of argument and cannot be
      curryfied. See \acode{projection}. 


      %%% -------------------------------------------------------
      
      \fitem{align_breakpoints}(nim) returns a nim with linear
      interpolation type whose (homogeneous) breakpoints are the
      breakpoints of all components of the arguments. See
      p.~\pageref{fct:sample} and function \acode{sample} and
      \acode{linearize}.

      %%% -------------------------------------------------------

      \fitem{approx}(x:numeric, y:numeric), \vListable. The function call
      can also be written with the special syntax \code{(x ~ y)} (the
      parenthesis are mandatory).

      This predicate returns true if
      \begin{lstlisting}
            abs((x - y)/max(x, y)) <  $APPROX_RATIO
      \end{lstlisting} %$
      The variable \varAPPROX is initalized to \code{0.1} so
      \code{(x ~ y)} means \code{x} and \code{y} differ by less than
      10\%. By changing the value of the variable \varAPPROX, one changes
      the level of approximation for the following calls to
      \code{@approx}. 
      %%
      Notice that using this function to check if a number is near zero is a
      bad idea: \code{(x ~ 0)} returns always $1$ if $x$ is null. 

      If one argument is a tab, the other argument $u$ is extended to tab
      if it is scalar (all elements of the extension is equal to $u$) and
      the predicate returns true if it hold point-wise for all element of
      the tabs. For example \code{(tab[1, 2] ~ 1.02)} returns \code{false}
      because we don't have \code{(2 ~ 1.02)}.



      %%% -------------------------------------------------------

      \fitem{arch_darwin}(): this predicate returns true if the
      underlying host is Mac OSX and false elsewhere.

      \fitem{arch_linux}(): this predicate returns true if the
      underlying host is a Linux system and false elsewhere.

      \fitem{arch_windows}(): this predicate returns true if the
      underlying host is Windows and false elsewhere.

      

      %%% -------------------------------------------------------

      \fitem{asin}(numeric), \vListable: arc sine

      %%% -------------------------------------------------------

      \fitem{atan}(numeric), \vListable: arc tangente


      %%% -------------------------------------------------------

      \fitem{between}(a:numeric, x:numeric, b:numeric), \vListable. %%
      This function admits two special syntax and can be written
      \code{(x in a .. b)} (the parenthesis are mandatory).
      \label{fct:between}

      This predicate is true if \code{a < x < b}. If one argument is
      a tab, each scalar argument $u$ is extended into a tab whose all
      elements are equal to $u$ and the predicate returns true if it hold
      point-wise for all element of the tabs. For example:
      \begin{lstlisting}
            ([1, 2] in 0 .. 3)
      \end{lstlisting}
      returns true because \code{0 < 1 < 3} and \code{1 < 2 < 3}. 



      %%% -------------------------------------------------------

      \fitem{bounded_integrate_inv}

      %%% -------------------------------------------------------

      \fitem{bounded_integrate}


      %%% -------------------------------------------------------

      \fitem{car}{t:tab}: returns the first element of tab \code{t} if
      \code{t} is not empty, else an empty tab. 


      %%% -------------------------------------------------------

      \fitem{cdr}{t:tab}: if \code{t} is not empty, it returns a copy of
      \code{t} but deprived of its first element, else it returns an empty
      tab. 


      %%% -------------------------------------------------------

      \fitem{ceil}(numeric), \vListable: This function returns the
      smallest integral value greater than or equal to its argument.


      %%% -------------------------------------------------------

      \fitem{clear}(tab \emph{or} map), \vImpure: clear all elements in
      the tab (resp. map) argument, resulting in a vector (resp. a
      dictionary) of size zero.


      %%% -------------------------------------------------------

      \fitem{concat}(tab, tab): returns a new tab made by the
      concatenation of the two tab arguments.


      %%% -------------------------------------------------------

      \fitem{cons}(v, t:tab): returns a new tab which is like \code{t} but
      has \code{v} prepended.  


      %%% -------------------------------------------------------

      \fitem{copy}(\vValue): returns a fresh copy of the argument.


      %%% -------------------------------------------------------

      \fitem{cosh}(numeric), \vListable: computes the hyperbolic cosine of
      its argument. 


      %%% -------------------------------------------------------

      \fitem{cos}, \vListable:  computes the cosine of its argument. 


      %%% -------------------------------------------------------

      \fitem{count}(tab \emph{or} map \emph{or} string, \vValue): computes the
      number of times the second argument appears in the first
      argument. For a map, the second argument refers to a value stored in
      the dictionary. See also  \acode{find}, \acode{member} and \acode{occurs}.



      %%% -------------------------------------------------------

      \fitem{dim}{(t:tab \emph{or} n:nim)}: if the argument is a tab
      \code{t}, it returns the dimension \code{t}, i.e. the maximal number
      of nested tabs. If the argument is a nim \code{n}, it returns the
      number of elements in the tab returned by the application of the
      nim. In either case, the returned value is an integer strictly
      greater than 0. If the argument is not a tab nor a nim, the
      dimension is~0.



      %%% -------------------------------------------------------

      \fitem{domain}(m:map) returns a tab containing all the keys present
      in the map \code{m}.


      %%% -------------------------------------------------------

      \fitem{drop}(t:tab, n:numeric) gives tab \code{t} with its first
      \code{n} elements dropped if \code{n} is positive, and tab
      \code{t} with its last \code{n} elements dropped if \code{n} is
      negative. See also functions \acode{cdr}, \acode{slice} and
      \acode{take}. 

      %%% -------------------------------------------------------

      \fitem{drop}(t:tab, x:tab) returns the tab formed by the elements
      of \code{t} whose indices are not in \code{x}. See also functions
      \acode{cdr}, \acode{slice} and \acode{take}.


      %%% -------------------------------------------------------

      \fitem{dump}(\emph{file}:string, \emph{variable}$_1$,
      ... \emph{variable}$_p$) is a special form (the \emph{variable}$_i$
      arguments are restricted to be variables). Calling this special form
      store the values of the variables in the file whose path is
      \emph{file}.

      The stored value can be restored using the function
      \atvar{loadvar}.

      The dump file can be produced during one program execution and can
      be read in another program execution. This mechanism can be used to
      manage \emph{presets}\index{preset}.
      %% 
      See also functions \atvar{savevalue} and
      \atvar{loadvalue}.


      Note that this special form expands into the ordinary function
      \atvar{dumpvar}. The same comments apply.  This function is a
      special form, so it cannot be curryfied.

      The dump file produced by \atvar{dump} is in a human readable
      format and corresponds to a fragment of the \Antescofo grammar.

      

      %%% -------------------------------------------------------

      \fitem{dumpvar}(\emph{file}:string, \emph{id}$_1$:string,
      \emph{v}$_1$, ..., \emph{id}$_p$:string, \emph{v}$_p$) save in
      \emph{file} the value \emph{v}$_i$) under the name \emph{id}$_i$).
      Then \emph{file} can be used by the function \atvar{loadvar} to
      define and set or to reset the variable  \emph{id}$_i$. The format
      used in \emph{file} is a text format corresponding to the
      \Antescofo grammar. See also
      functions \atvar{savevalue} and \atvar{loadvalue}.

      The number of argument is variable, so this function cannot be
      curryfied.

      Dumping the values of the variables is done in a separate thread,
      so the ``main'' computation is not perturbed. However, it means
      that the file is created asynchronously with the function call and
      when the function returns, the file may not be completed.



      %%% -------------------------------------------------------

      \fitem{empty}(\vValue): returns true for an empty tab or an empty
      dictionary and false elsewhere. 


      %%% -------------------------------------------------------

      \fitem{exp}(x:numeric), \vListable: the base-$e$ exponential of
      \code{x}. 


      %%% -------------------------------------------------------

      \fitem{explode}(s:string): returns a tab containing the characters
      of the \code{s} (represented as string with only one element). For
      example:
      \begin{lstlisting}
            @explode("")  ->[]
            @explode("abc")  ->["a", "b", "c"]
            @reduce(@+, @explode("abc")) ->"abc"
            @scan(@+, @explode("abc")) ->["a", "ab", "abc"]
      \end{lstlisting}


      %%% -------------------------------------------------------

      \fitem{find}{(t:tab \emph{or} m:map \emph{or} s:string, f:function)}
      returns the index of the first element of \code{t}, \code{m} or
      \code{s} that satisfies the predicate \code{f}. The predicate
      \code{f} is a binary function taking the index or the key as the
      first argument and the associated value for the second argument.
      %% 
      See also \acode{count}, \acode{member} and \acode{occurs}. The undef
      value (for maps) or the integer \code{-1} (for tab and string) is
      returned if there is no pair satisfying the predicate. 



      %%% -------------------------------------------------------

      \fitem{filter_max_t}(nim, n:numeric) replaces the image $y$ of
      each breakpoint by the max taken on a sequence made of the
      \code{n} previous and the \code{n} next images in addition to
      $y$.  See p.~\pageref{fct:filterMaxT}. 


      %%% -------------------------------------------------------

      \fitem{filter_median_t}(nim, n:numeric) replaces the image $y$ of
      each breakpoint by the median taken on a sequence made of the
      \code{n} previous and the \code{n} next images in addition to
      $y$. See p.~\pageref{fct:filterMedianT}. 

      %%% -------------------------------------------------------

      \fitem{filter_min_t}(nim, n:numeric) replaces the image $y$ of
      each breakpoint by the min taken on a sequence made of the
      \code{n} previous and the \code{n} next images in addition to
      $y$.  See p.~\pageref{fct:filterMinT}. 

      %%% -------------------------------------------------------

      \fitem{flatten}{(t)} build a new tab where the nesting structure of
      \code{t} has been flattened. For example, 
      \begin{lstlisting}
            @flatten([[1, 2], [3], [[], [4, 5]]]) ->[1, 2, 3, 4, 5]
      \end{lstlisting}




      %%% -------------------------------------------------------

      \fitem{flatten}{(t:tab, l:numeric)} returns a new tab where \code{l}
      levels of nesting has been flattened. If \code{l == 0}, the function
      is the identity. If \code{l} is strictly negative, it is equivalent
      to \code{@flatten} without the level argument.
      \begin{lstlisting}
            @flatten([1, [2, [3, 3], 2], [[[4, 4, 4]]]], 0)
            ->[1, [2, [3, 3], 2], [[[4, 4, 4]]]]
            @flatten([1, [2, [3, 3], 2], [[[4, 4, 4]]]], 1)
            ->[1, 2, [3, 3], 2, [[4, 4, 4]]]
            @flatten([1, [2, [3, 3], 2], [[[4, 4, 4]]]], 2)
            ->[1, 2, 3, 3, 2, [4, 4, 4]]
            @flatten([1, [2, [3, 3], 2], [[[4, 4, 4]]]], 3)
            ->[1, 2, 3, 3, 2, 4, 4, 4]
            @flatten([1, [2, [3, 3], 2], [[[4, 4, 4]]]], 4)
            ->[1, 2, 3, 3, 2, 4, 4, 4]
            @flatten([1, [2, [3, 3], 2], [[[4, 4, 4]]]], -1)
            ->[1, 2, 3, 3, 2, 4, 4, 4]
      \end{lstlisting}



      %%% -------------------------------------------------------

      \fitem{floor}(x:numeric), \vListable:  returns the largest integral
      value less than or equal to \code{x}.



      %%% -------------------------------------------------------

      \fitem{gnuplot}(data:tab): \label{gnuplot:forme1} %%
      The function \acode{gnuplot} plots the elements in the \code{data}
      tab as a time series. If \code{data} is a tab of numeric values, a
      simple curve is plotted: an element $e$ of index $i$ gives a point
      of coordinate ($i$, $e$).
      %% 
      If \code{data} is a tab of tab (of $p$ numeric values), $p$ curves
      are plotted on the same window. 
      %% 
      Each \atvar{gnuplot} invocation lead to a new window. 
      %% 
      Function \atvar{gnuplot} returns \code{true} if the plot succeeded,
      and \code{false} elsewhere.

      To work, the \texttt{gnuplot} program must be installed on the
      system Cf. \url{http://www.gnuplot.info} and must be visible from
      the \antescofo object. They are three ways to make this command
      visible: 
      \begin{enumerate}
      \item set the global variable \var{gnuplot_path} to the absolute
            path of the \texttt{gnuplot} executable (in the form of a
            string);

      \item alternatively, set the environment variable \code{GNUPLOT} of
            the shell used to launch the \Antescofo standalone or the
            Max/PD host of the \Antescofo object, to the absolute path of
            the \texttt{gnuplot} executable;

      \item alternatively make visible the \texttt{gnuplot} executable
            visible from the shell used by the user shell to launch the
            \Antescofo standalone or the Max/PD host of the \Antescofo
            object (\emph{e.g.} through the \code{PATH} variable).
      \end{enumerate}
      The search of a \texttt{gnuplot} executable is done in this order.
      %% 
      The command is launched on a shell with the option
      \texttt{-persistent} and the absolute path of the gnuplot command
      file. 
      %% 
      The data are tabulated in a file \code{/tmp/tmp.antescofo.data.}$n$
      (where $n$ is an integer) in a format suitable for \code{gnuplot}.
      The gnuplot commands used to plot the data are in the file
      \code{/tmp/tmp.antescofo.gnuplot.}$n$\,.
      %% 
      These two files persists between two \Antescofo session and can then
      be used to plot with other option.

      The \atvar{gnuplot} function is overloaded and accepts a variety of
      arguments described below. The \atvar{gnuplot} function is used
      internally by the special forms \atvar{plot} and \atvar{rplot}
      described page~\pageref{sec:plot}. 



      %%% -------------------------------------------------------

      \fitem{gnuplot}(title:string, data:tab): \label{gnuplot:forme2} 
      %% 
      same as the previous form, but the first argument is used as the
      label of the plotted curve. If \code{data} is a tab of tab,
      (\emph{e.g.} the history of a tab valued variable), then the label
      of each curve takes the form \code{title[}$i$\code{]}.



      %%% -------------------------------------------------------

      \fitem{gnuplot}(time:tab, data:tab): \label{gnuplot:forme3} 
      %% 
      plots the points $($\code{time[}$i$\code{],data[}$i$\code{]}$)$.
      %% 
      As for the previous form, \code{data} can be a tab of tab (of
      numeric values). The \code{time} tab corresponds to the $x$
      coordinate of the plot and must be a tab of numeric values.



      %%% -------------------------------------------------------

      \fitem{gnuplot}(title:string, time:tab, data:tab): %%
      \label{gnuplot:forme4} %% 
      Same as the previous entry but the first argument is used as the
      label of the curve(s).


      %%% -------------------------------------------------------

      \fitem{gnuplot}(title1:string, time1:tab, data1:tab, title2: string,
      time2:tab, data2:tab, ...): %
      \label{gnuplot:forme5} %%
      In this variant, several curves are plotted in the same window. One
      curve is specified by 2 or 3 consecutive arguments. Three arguments
      are used if the first considered argument is a string: in this case,
      this argument is the label of the curve. The following argument is
      used as the $x$ coordinates and the next one as the $y$ coordinates
      of the plotted point.
      
      In this variant, the \code{data}$i$ arguments must be tab of numeric
      values (they cannot be tab of tab). 




      %%% -------------------------------------------------------

      \fitem{gshift_map}(a:map, f:function): returns a new map \code{b}
      such that \code{@b(f(x)) = a(x)} where \code{f} can be a map, an
      interpolated map or an intentional function.


      %%% -------------------------------------------------------

      \fitem{history_length}(\emph{variable}) : This is a special
      form. It returns the maximal length of the history of a
      variable, \emph{i.e.} the number of update that are recorded. 
      See. sect.~\ref{sec:mapvariable} page~\pageref{sec:mapvariable}
      and the  \code{@map_history_XXX} \code{@tab_history_XXX}
      functions.  



      %%% -------------------------------------------------------

      \fitem{insert}(t:tab, i:numeric, v:val), \vImpure: inserts ``in
      place'' the value \code{v} into the tab \code{t} after the index
      \code{i} (tab's elements are indexed starting with \code{0}). If
      \code{i} is negative, the insertion take place in front of the
      tab. If \code{i} $\leq$ \code{@size(t)} the insertion takes place at
      the end of the tab.

      Notice that the form \code{@insert "file"} is also used to include
      a file at parsing time.


      %%% -------------------------------------------------------

      \fitem{insert}(m:map, k:val, v:val), \vImpure: inserts ``in place''
      a new entry \code{k} with value \code{v} in the map \code{m}. See
      \acode{add_pair}.  Notice that the form \code{@insert "file"} is
      also used to include a file at parsing time.



      %%% -------------------------------------------------------

      \fitem{integrate} \emph{not yet documented}


      %%% -------------------------------------------------------

      \fitem{iota}(n:numeric): return \code{[ $x | $x in n]}, that is, a
      tab listing the integers from \code{0} to \code{n} excluded.


      %%% -------------------------------------------------------

      \fitem{is_bool}(\vValue): the predicate returns true if its argument
      is a boolean value. 


      %%% -------------------------------------------------------

      \fitem{is_defined}(map, \vValue):  the predicate returns true if
      the second argument is a key present in the first argument. Do not
      mismatch with the negation of the predicate \acode{is_undef}. 


      %%% -------------------------------------------------------

      \fitem{is_exec}(\vValue): the predicate returns true if the
      argument represents an \emph{exec}, that is, the instance of a
      compound action (especially the result of a process call). The
      predicate returns true even if the compound action has finished
      its computation. However, the \emph{exec} itself used in a boolean
      condition evaluates to true if the compound action is still
      running and false elsewhere.



      %%% -------------------------------------------------------

      \fitem{is_fct}(\vValue):  the predicate returns true if its
      argument is an intentional function.


      %%% -------------------------------------------------------

      \fitem{is_float}(\vValue):  the predicate returns true if its
      argument is a decimal number.


      %%% -------------------------------------------------------

      \fitem{is_function}(\vValue):  the predicate returns true if its
      argument is a map, an interpolated map or an intentional function.


      %%% -------------------------------------------------------

      \fitem{is_integer_indexed}(\vValue): the predicate returns true if its
      argument is a map whose domain is a set of integers.


      %%% -------------------------------------------------------

      \fitem{is_interpolatedmap}(\vValue):  the predicate returns true if its
      argument is an interpolated map.


      %%% -------------------------------------------------------

      \fitem{is_int}(\vValue):  the predicate returns true if its
      argument is an integer.



      %%% -------------------------------------------------------

      \fitem{is_list}(\vValue):  the predicate returns true if its
      argument is a map whose domain is the integers $\{0, \dots, n\}$ for
      some $n$. 


      %%% -------------------------------------------------------

      \fitem{is_map}(\vValue): the predicate returns true if its
      argument is a map.


      %%% -------------------------------------------------------

      \fitem{is_numeric}(\vValue):  the predicate returns true if its
      argument is an integer or a decimal.

     %%% -------------------------------------------------------

      \fitem{is_obj}(\vValue):  the predicate returns true if its
      argument is an object (implemented by a running process). 

     %%% -------------------------------------------------------

      \fitem{is_obj}\textcolor{fctcolor}{\_xxx}(\vValue) %%
      where \textcolor{fctcolor}{xxx} is the name (without the prefix
      \code{obj::}) of an object defined through \acode{obj_def}. This
      predicate is automatically generated with an object definition and
      check that a value represents an instance of \code{obj::xxx}.


      %%% -------------------------------------------------------

      \fitem{is_prefix}(s1:string, s2:string): the predicate returns true
      if \code{s1} is a prefix of \code{s2}. See the overloaded versions
      below and also the functions \acode{is_suffix} and
      \acode{is_subsequence}.


      %%% -------------------------------------------------------

      \fitem{is_prefix}(s1:string, s2:string, cmp:fct): the predicate
      returns true if \code{s1} is a prefix of \code{s2} where the
      characters are compared with the function \code{cmp}. The characters
      are passed to the function \code{cmp} as strings of length one. 


      %%% -------------------------------------------------------

      \fitem{is_prefix}(t1:tab, t2:tab): the predicate returns true if
      \code{t1} is a prefix of \code{t2}, that is, if the elements of
      \code{t1} are the final elements of \code{t2}.


      %%% -------------------------------------------------------

      \fitem{is_prefix}(t1:tab, t2:tab, cmp:fct): same as the previous
      version but the function \code{cmp} is used to test the equality
      between the elements, instead of the usual comparison between
      values.  For example:
      \begin{lstlisting}
            @fun_def cmp($x, $y) { $x > $y }
            @is_prefix([11, 22], [5, 6, 7], @cmp) ->true
      \end{lstlisting}
      \code{true} is returned because \code{@cmp(11, 6)} and
      \code{@cmp(22, 7)} hold.




      %%% -------------------------------------------------------

      \fitem{is_string}(\vValue): the predicate returns true if its
      argument is a string.




      %%% -------------------------------------------------------

      \fitem{is_subsequence}(s1:string, s2:string): the function returns
      the index of the first occurrence of string \code{s1} in string
      \code{s2}. A negative value is returned if \code{s1} does not occurs
      in \code{s2}. See the overloaded versions below and also the
      functions \acode{is_prefix} and \acode{is_suffix}.


      %%% -------------------------------------------------------

      \fitem{is_subsequence}(s1:string, s2:string, cmp:fct): same as above
      but the argument \code{cmp} is used to compare the characters of the
      strings (represented as strings of only one element).


      %%% -------------------------------------------------------

      \fitem{is_subsequence}(t1:tab, t2:tab): the predicate returns the
      index of the first occurrence of the elements of \code{t1} as a 
      sub-sequence of the elements of \code{t2}. A negative value is
      returned if \code{t2} does not appear as a subsequence of tab
      \code{t2}. For example
      \begin{lstlisting}
            @is_subsequence([], [1, 2, 3])         ->0
            @is_subsequence([1, 2, 3], [1, 2, 3])  ->0
            @is_subsequence([1], [1, 2, 3])        ->0
            @is_subsequence([2], [1, 2, 3])        ->1
            @is_subsequence([3], [1, 2, 3])        ->2
            @is_subsequence([1, 2], [0, 1, 2, 3])  ->1
      \end{lstlisting}


      %%% -------------------------------------------------------

      \fitem{is_subsequence}(t1:tab, t2:tab, cmp:fct): same as the version
      above but the function \code{cmp} is used to compare the
      elements of the tabs. 



      %%% -------------------------------------------------------

      \fitem{is_suffix}(s1:string, s2:string): the predicate returns true
      if \code{s1} is a suffix of \code{s2}. See the overloaded versions
      below and also the functions \acode{is_prefix} and
      \acode{is_subsequence}.


      %%% -------------------------------------------------------

      \fitem{is_suffix}(s1:string, s2:string, cmp:fct): the predicate
      returns true if \code{s1} is a suffix of \code{s2} where the
      characters are compared with the function \code{cmp}. The characters
      are passed to the function \code{cmp} as strings of length one. 


      %%% -------------------------------------------------------

      \fitem{is_suffix}(t1:tab, t2:tab): the predicate returns true
      if \code{t1} is a suffix of \code{t2}, that is, if the elements of
      \code{t1} are the final elements of \code{t2}. 


      %%% -------------------------------------------------------

      \fitem{is_suffix}(t1:tab, t2:tab, cmp:fct): same as the previous
      version but the function \code{cmp} is used to test the equality
      between the elements, instead of the usual comparison between
      values.  For example:
      \begin{lstlisting}
            @fun_def cmp($x, $y) { $x < $y }
            @is_suffix([1, 2], [5, 6, 7], @cmp) ->true
      \end{lstlisting}
      \code{true} is returned because \code{@cmp(1, 6)} and %
      \code{@cmp(2, 7)} hold. 


      %%% -------------------------------------------------------

      \fitem{is_symbol}(\vValue):  the predicate returns true if its
      argument is a symbol. 


      %%% -------------------------------------------------------

      \fitem{is_undef}(\vValue):  the predicate returns true if its
      argument is the undefined value. Do not mismatch with the negation
      of the predicate \acode{is_defined}. 


      %%% -------------------------------------------------------

      \fitem{is_vector}(\vValue):  the predicate returns true if its
      argument is a list and its range is a set of numeric. 


      %%% -------------------------------------------------------

      \fitem{lace}{(t:tab, n:numeric)} returns a new tab whose elements
      are interlaced sequences of the elements of the \code{t}
      subcollections, up to size \code{n}. The receiver is unchanged.
      \begin{lstlisting}
            @lace([[1, 2, 3], 6, ["foo", "bar"]], 9) == [1, 6, "foo", 2, 6, "bar", 3, 6, "foo"]
      \end{lstlisting}

      %%% -------------------------------------------------------

      \fitem{last}{(t:tab)} returns the last element of a tab, or
      undef. 


      %%% -------------------------------------------------------

      \fitem{linearize}(nim, tol:numeric) build a new nim that
      approximates the argument.The new nim uses only linear
      interpolation and homogeneous breakpoints. 
      An adaptive sampling step achieve an approximation within
      \code{tol} (\emph{i.e.} for any point in the domain, the images of
      the nim argument and the nim result are withing \code{tol}.  See
      p.~\pageref{fct:sample} and function \acode{sample} and
      \acode{align_breakpoints}. 

      %%% -------------------------------------------------------

      \fitem{listify}(map): returns the range of its argument as a list,
      \emph{i.e.} the returned map is obtained by replacing the keys in
      the arguments by consecutive integers starting from \code{0}.


      %%% -------------------------------------------------------


      \fitem{loadvalue}(\emph{file}:string) : read a file produced by a
      call to the function \atvar{savevalue} and returns the value that was
      saved. If something goes wrong, an undefined value is returned.
      See also function \atvar{dump}, \atvar{dumpvar} and \atvar{loadvar}.

      Because the variables are supposed to have their saved values right
      after the call to \atvar{loadvar}, we deliberately use a synchronous
      scheme where the function returns after having completed all the
      initializations.
      %% 
      A call to this function may take a noticeable time depending on the
      size of the values to store in the dump file. While this time is
      usually negligible, loading a tab of $10\,000$ integers represents a
      file of size about $60$\,Kb and takes between $2$\,ms and $3$\,ms.
      %% 
      This computational cost may have a negative impact on the audio
      processing in heavy cases. However, the intended use of
      \atvar{loadvalue} and \atvar{loadvar} functions is to restore a
      ``preset'' at isolated places like the beginning of the score or
      between musical sequences, a usage where this cost should have no
      impact.
      %% 
      Notice that saving a value or variables is done
      \emph{asynchronously} and does not disturb the ``main''
      computation. See the remarks of function \atvar{dump}. 



      %%% -------------------------------------------------------

      \fitem{loadvar}(\emph{file}:string) : \label{fct:loadvar} %
      read a file produced by a call to \atvar{dump} (or
      \atvar{dumpvar}) and set the value of the corresponding variables.

	The basic use of \atvar{loadvar} is to recover values of global variables that have been previously saved with a \atvar{dump} command.
	If the loaded variable is not defined at the calling point, a new global variable is implicitly defined by \atvar{loadvar}. If the variable with the same name exist at the calling point, either global or local, this variable will be set with the saved value.

      To be more precise, when \atvar{dump} is called, the name of the
      variables in the arguments list are stored as well as the
      corresponding values in \emph{file}. The variables in the argument
      list can be global or local variable.

      When \atvar{loadvar} is called, it is called in some scope
      $sc$. Each identifier in the dump file is searched in the current scope
      $sc$. If not found, the englobing scope is looked up, and the
      process is iterated until a variable is found or until reaching
      the global scope. If no variable with the same identifier is found,
      a global variable with this identifier is created. The value
      associated to the identifier is used to set the selected
      variable.

      Beware that \atvar{loadvar} does not trigger the \code{whenever}s. 

      
      \emph{Nota Bene:} because \atvar{loadvar} can be called in a context
      which differs from the context of the call of \atvar{dump}, there is
      no reason that the 'same' variables will be set.

      Here is an example:
      \begin{lstlisting}
            @global $a, $b, $c
            $a := 1
            $b := 2
            $c := 3
            $ret := @dump("/tmp/dump1", $a, $b, $c)
            $a := 0
            $b := 0
            $c := 0
            Group G1
            {
              @local $b
              $b := 22
              Group G2
              {
                @local $c
                $c := 33
                $ret := @loadvar("/tmp/dump1")
                print $a $b $c  ; print 1 2 3
              }
              print $a $b $c
              ; print 1 2 0
              ; because the variable $c set by @loadvar is in G1
            }
            print $a $b $c ; print 1 0 0
            
            $ret := @loadvar("/tmp/dump1")
            print $a $b $c ; print 1 2 3
      \end{lstlisting}

      

      %%% -------------------------------------------------------

      \fitem{log10}(numeric), \vListable: computes the value of the
      logarithm of its argument to base 10.


      %%% -------------------------------------------------------

      \fitem{log2}(numeric), \vListable:  computes the value of the
      logarithm of its argument to base 2.


      %%% -------------------------------------------------------

      \fitem{log}(numeric), \vListable:  computes the value of the
      natural logarithm of its argument.


      %%% -------------------------------------------------------

      \fitem{make_duration_map}() \emph{or} (start:numeric) \emph{or}
      (start:numeric, stop:numeric): \\ %%
      \code{@make_duration_map(a, b)} returns a map where the duration (in beat)
      of the $i$th event of the score, is associated to $i$ (the keys of
      the map are the ranks of the events). 
      %% 
      Called with no arguments, the events considered are all
      the events in the score. With \code{start}, only the events whose
      position is greater than \code{start} are considered. If a
      \code{stop} is specified, all events must have a position between
      \code{start} and \code{stop}.

      %%% -------------------------------------------------------


      \fitem{make_label_pos}() \emph{or} (start:numeric) \emph{or}
      (start:numeric, stop:numeric): %%
      this function returns a map whose keys are the labels of the
      events and the value, the position (in beats) of the
      events. Events with no label do not appear in the map. 
      %%
      Called with no arguments, the events considered are all
      the events in the score. With \code{start}, only the events whose
      position is greater than \code{start} are considered. If a
      \code{stop} is specified, all events must have a position between
      \code{start} and \code{stop}.

      %%% -------------------------------------------------------

      \fitem{make_label_bpm}() \emph{or} (start:numeric) \emph{or}
      (start:numeric, stop:numeric): %%
      returns a map associating the event labels to the BPM at this
      point in the score.  Events with no label do not appear in the map. 
      %% 
      Called with no arguments, the events considered are all
      the events in the score. With \code{start}, only the events whose
      position is greater than \code{start} are considered. If a
      \code{stop} is specified, all events must have a position between
      \code{start} and \code{stop}.

      %%% -------------------------------------------------------

      \fitem{make_label_duration}() \emph{or} (start:numeric) \emph{or}
      (start:numeric, stop:numeric): %%
      returns a map associating to the event of a label, the duration of
      this event.  Events with no label do not appear in the map. 
      %%
      Called with no arguments, the events considered are all
      the events in the score. With \code{start}, only the events whose
      position is greater than \code{start} are considered. If a
      \code{stop} is specified, all events must have a position between
      \code{start} and \code{stop}.

      %%% -------------------------------------------------------

      \fitem{make_label_pitches}() \emph{or} (start:numeric) \emph{or}
      (start:numeric, stop:numeric): %%
      returns a map associating a vector of pitches to the label of an
      event. A \code{NOTE} corresponds to a tab of size 1, a
      \code{CHORDS} with $n$ pitches to a tab of size $n$, \emph{etc.}.
      Events with no label do not appear in the map.
      %% 
      Called with no arguments, the events considered are all
      the events in the score. With \code{start}, only the events whose
      position is greater than \code{start} are considered. If a
      \code{stop} is specified, all events must have a position between
      \code{start} and \code{stop}.

      %%% -------------------------------------------------------

      \fitem{make_score_map}() \emph{or} (start:numeric) \emph{or}
      (start:numeric, stop:numeric): %%
      \code{@make_score_map(a, b)} returns a map where the keys are the
      rank $i$ of the musical events and thevalue, the position (in
      beat) of the $i$th event.
      %% 
      Called with no arguments, the events considered are all
      the events in the score. With \code{start}, only the events whose
      position is greater than \code{start} are considered. If a
      \code{stop} is specified, all events must have a position between
      \code{start} and \code{stop}.


      %%% -------------------------------------------------------

      \fitem{map}(f:function, t:tab) returns a tab such that element $i$
      is the result of applying \code{f} to element \texttt{t[$i$]}. Note
      that
      \begin{lstlisting}
            @map(f, &$t$&) &$\equiv$& [f($x) | $x in &$t$&]
      \end{lstlisting}


      %%% -------------------------------------------------------

      \fitem{map_compose}(a:map, b:map): returns a map \code{c} such that
      \code{c(x) = b(a(x))}.


      %%% -------------------------------------------------------

      \fitem{map_concat}(a:map, b:map): returns a map \code{c} which
      contains the (key, value) pairs of \code{a} and a pair $(n, e)$ for
      each pair $(k, v)$ in \code{b} with $n$ ranging from \code{@size(a)}
      to  \code{@size(a) + @size(b)}. If \code{a} and \code{b} are
      ``vectors'' (\emph{i.e.} the range is an interval $[0, p]$ for some
      $p$), then \code{@map_compose} is the vector concatenation. 



      
      %%% -------------------------------------------------------

      \fitem{map_history}(\emph{variable}) : This is a special form. It
      returns a map of the value of the variable in
      argument. See. sect.~\ref{sec:mapvariable}
      page~\pageref{sec:mapvariable} and the 
      \code{@tab_historyXXX} functions. 


      %%% -------------------------------------------------------

      \fitem{map_history_date}(\emph{variable}) : This is a special
      form. It returns a map of the date in physical time of the updates
      of the variable in argument. See. sect.~\ref{sec:mapvariable}
      page~\pageref{sec:mapvariable} and the 
      \code{@tab_historyXXX} functions. 


      %%% -------------------------------------------------------

      \fitem{map_history_rdate}(\emph{variable}) : This is a special
      form. It returns a map of the date in relative time of the updates
      of the variable in argument. See. sect.~\ref{sec:mapvariable}
      page~\pageref{sec:mapvariable}  and the 
      \code{@tab_historyXXX} functions. 


      %%% -------------------------------------------------------

      \fitem{map_normalize}{(map)}


      %%% -------------------------------------------------------

      \fitem{map_reverse}(map): \code{@map_reverse(m)} reurns a new map
      \code{p} such that \code{p(i) = m(sz - i)} with %%
      \code{sz = @size(m)}. 


      %%% -------------------------------------------------------

      \fitem{mapval}(map, function): \code{mapval(m, f)} return a map
      \code{p} such that \code{p(x) = f(m(x))}.


      %%% -------------------------------------------------------

      \fitem{max_key}(map): returns the maximal element in the domain of
      the argument. 

      \fitem{max_key}(nim): return the coordinate $x_n$ of the last
      breakpoint o the nim. This coordinate is the sum of $x_0$ (the
      coordinate of the first breakpoint of the nim, and of all
      intervals $d_i$ of the breakpoints $i$. If the nim is vectorial,
      $x_n$ is a tab. See sect.~\ref{sec:nim}.


      %%% -------------------------------------------------------

      \fitem{max_val}(tab \emph{or} map \emph{or} nim): returns the
      maximal element in the tab if it is a map, the maximal element in
      the domain of the map if the argument is a map or a nim.


      %%% -------------------------------------------------------

      \fitem{max}(\vValue, \vValue); return the maximum of its
      arguments. %%
      \index{value!ordering} 
      % 
      Values in \Antescofo are totally ordered. The order
      between two elements of different type is implementation
      dependent. However, the order on numeric is as expected (numeric
      ordering, the integers are embedded in the decimals). For two
      argument of the same type, the ordering is as expected
      (lexicographic ordering for string, etc.).


      %%% -------------------------------------------------------

      \fitem{member}(tab \emph{or} map \emph{or} string, \vValue): returns
      true if the  second argument is an element of the first. For a map,
      the second arguments refers to a value stored in the dictionary. 
      See also \acode{count}, \acode{find} and \acode{occurs}.



      %%% -------------------------------------------------------

      \fitem{merge}(map, map): asymetric merge of the two argument
      maps. The result of \code{@merge(a, b)} is a map \code{c} such that
      \code{c(x) = a(x)} if \code{a(x)} is defined, and \code{b(x)}
      elsewhere. 


      %%% -------------------------------------------------------

      \fitem{min_key}(map): return the minimal element in the domain of
      its argument. 

      \fitem{min_key}(nim): return the coordinate $x_0$ of the initial
      breakpoint. If the nim is vectorial, $x_0$ is a tab. See
      sect.~\ref{sec:nim}. 


      %%% -------------------------------------------------------

      \fitem{min_val}(tab \emph{or} map \emph{or} nim): returns the
      minimal element present in the tab or the minimal element in the
      domain (if the argument is a map or a nim)


      %%% -------------------------------------------------------

      \fitem{min}(\vValue, \vValue): returns the minimal elements in its
      arguments.


      %%% -------------------------------------------------------

      \fitem{normalize}(tab, min:numeric, max:numeric): returns a new tab
      with the elements normalized between min and max.  If they are
      omitted, they are assumed to be 0 and 1.



      %%% -------------------------------------------------------

      \fitem{occurs}(tab \emph{or} map \emph{or} string, \vValue): returns
      the first index or the first key whose value equals the second
      argument. For example
      \begin{lstlisting}
            @occurs(["a", "b", "c", "a", "b"], "b") ->1
            @occurs("xyz", "z")  ->2
            @occurs(map{ ("zero", 0), ("null", 0), ("void", 0) }, 0)  ->"null"
      \end{lstlisting}
      In the last example, the answer \code{"null"} is returned because
      \code{"null" < "void" < "zero"}. 
      %% 
      See also \acode{count}, \acode{find} and \acode{member}.




      %%% -------------------------------------------------------

      \fitem{permute}{(t:tab, n:numeric)} returns a new tab which contains the
      \code{n}th permutations of the elements of \code{t}. They are
      factorial \code{s} permutations, where \code{s} is the size of
      \code{t}. The first permutation is numbered 0 and corresponds to the
      permutation which rearranges the elements of \code{t} in an array
      $t_0$ such that they are sorted increasingly. The tab $t_0$ is the
      smallest element amongst all tab that can be done by rearranging the
      element of \code{t}.
      %% 
      The first permutation rearranges the elements of \code{t} in a tab
      $t_1$ such that $t_0 < t_1$ for the lexicographic order and such
      that any other permutation gives an array $t_k$ lexicographicaly
      greater than $t_0$ and $t_1$. Etc. The last permutation (factorial
      \code{s} - 1) returns a tab where all elements of \code{t} are in
      decreasing order.
      \begin{lstlisting}
            $t := [1, 2, 3]
            @permute($t, 0) == [1, 2, 3]
            @permute($t, 1) == [1, 3, 2]
            @permute($t, 2) == [2, 1, 3]
            @permute($t, 3) == [2, 3, 1]
            @permute($t, 4) == [3, 1, 2]
            @permute($t, 5) == [3, 2, 1]
      \end{lstlisting} %$



      %%% -------------------------------------------------------

      \fitem{plot}(\emph{variable}) or \atvar{plot}(\emph{variable}$_1$,
      ... \emph{variable}$_p$) is a special form (the arguments are
      restricted to be variables). Calling this special form plots the
      values stored in the history of the variables as time series in
      absolute time using the \texttt{gnuplot} function. See
      page~\pageref{sec:plot} and also the library function \atvar{rplot}.




      %%% -------------------------------------------------------

      \fitem{pow}(numeric, numeric), \vListable: \code{@pow(x, y)}
      computes \code{x} raised to the power \code{y}.


      %%% -------------------------------------------------------

      \fitem{projection}{(nim, p:numeric)} extracts the \code{p}th
      component of a vectorial nim. See \acode{aggregate}.


      %%% -------------------------------------------------------

      \fitem{push_back}(tab, \vValue), \vImpure: add the second argument at
      the end of the first argument. The first argument, modified by
      side-effect, is the returned value. 


      %%% -------------------------------------------------------

      \fitem{push_back}(nim:NIM, d:numeric, y1:numeric, it:string),
      \vImpure: add a breakpoint as the last breakpoint of \code{nim}.
      The first argument, modified by side-effect, is the nim, which is
      also the returned value. The argument \code{d} specifies the length
      of the interpolation since the previous breakpoint, \code{y1} is the
      final value attained at the end of the breakpoint, and \code{it} is
      the interpolation type. The interpolation type can be omitted: in
      this case, the interpolation is linear. The initial value \code{y0}
      of the breakpoint is the \code{y1} value of the previous breakpoint.


      %%% -------------------------------------------------------

      \fitem{push_back}(nim:NIM, y0:numeric, d:numeric, y1:numeric,
      it:string),\vImpure: similar to the previous function but \code{y0}
      is explicitly given , making possible to specify discontinuous
      \code{NIM}. 


      %%% -------------------------------------------------------

      \fitem{push_front}(tab, \vValue), \vImpure: add the second argument
      at the beginning of its first argument. The first argument, modified
      by side-effect, is the returned value.


      %%% -------------------------------------------------------

      \fitem{rand_int}(int), \vImpure: returns a random integer between 0 and its
      argument (excluded). This is not a pure function because two calls
      with the same argument are likely to return different results. 


      %%% -------------------------------------------------------

      \fitem{random}(), \vImpure: returns a random number between 0 and 1
      (included). The resolution of this random number generator is
      $\frac{1}{2^{31} - 1}$, which means that the minimal step between
      two numbers in the images of this function is $\frac{1}{2^{31} -
        1}$.  This is not a pure function because two successive calls are
      likely to return different results.


      %%% -------------------------------------------------------

      \fitem{rand}(), \vImpure: similar to \code{@random} but rely on a different
      algorithm to generate the random numbers.


      %%% -------------------------------------------------------

      \fitem{reduce}(f:function, t:tab): if \code{t} is empty, an
      undefined value is returned. If \code{t} has only one element, this
      element is returned. In the other case, the binary operation
      \code{f} is used to combine all the elements in \code{t} into a
      single value \code{f(... f(f(t[0], t[1]), t[2]), ... t[n])}. 
      %% 
      For example, if \code{v} is a vector of booleans, %
      \code{@reduce(@||, v)} returns the logical disjunction of the
      \code{t}'s elements. 



      %%% -------------------------------------------------------

      \fitem{range}(m:map) returns the tab of the values present in the
      map. The order in the tab is irrelevant. 


      %%% -------------------------------------------------------

      \fitem{remove}{(t:tab, n:numeric)}, \vImpure: removes the element at
      index \code{n} in \code{t} (\code{t} is modified in place). Note
      that building a new tab by removing elements satisfying some
      property $P$ is easy with a comprehension:
      \begin{lstlisting}
            [ $x | $x in $t, !&$P$& ]
      \end{lstlisting} %$


      %%% -------------------------------------------------------

      \fitem{remove}{(m:map, k:val)}, \vImpure: removes the entry \code{k}
      in map \code{m} (\code{m} is modified in place). Does nothing if the
      entry \code{k} is not present in map \code{m}. 


      %%% -------------------------------------------------------

      \fitem{remove\_duplicate}{(t)}, \vImpure: keep only one occurrence
      of each element in \code {t}. Elements not removed are kept in order
      and \code{t} is modified in place.


      %%% -------------------------------------------------------

      \fitem{replace}{(t:tab, find:value, rep:value)}\label{fct:replace}
      returns a new tab in which a number of elements have been replaced
      by another. The argument \code{find} represents a sub-sequence to be
      replaced: if it is not a tab, then all the occurrences of this value
      at the top-level of \code{t} are replaced by \code{rep}:
      \begin{lstlisting}
            @replace([1, 2, 3, [2]], 2, 0]) ->[1, 0, 3, [2]]
      \end{lstlisting}
      If \code{find} is a tab, then the replacement is done on
      sub-sequence of \code{t}:
      \begin{lstlisting}
            @replace([1, 2, 3, 1, 2], [1, 2], 0) ->[0, 3, 0]
      \end{lstlisting}
      Note that the replacement is done eagerly: the first occurrence
      found is replaced and the replacement continue on the rest of the
      tab. Thus, there is no ambiguity in case of overlapping sub-sequences,
      only the first is replaced:
      \begin{lstlisting}
            @replace([1, 1, 1, 2], [1, 1], 0) ->[0, 1, 2]
      \end{lstlisting}
      If the \code{rep} argument is a tab, then it represents at
      sub-sequence to be inserted in place of the occurrences of
      \code{find}. So, if the replacement is a tab, it must be wrapped
      into a tab: 
      \begin{lstlisting}
            @replace([1, 2, 3], 2, [4,5]) ->[1, 4, 5, 3]
            @replace([1, 2, 3], 2, [[4, 5]]) ->[1, [4, 5], 3]
      \end{lstlisting}



      %%% -------------------------------------------------------

      \fitem{reshape}{(t, s)} builds an array of shape \code{s} with the
      element of tab \code{t}. These elements are taken circularly one
      after the other. For instance
      \begin{lstlisting}
            @reshape([1, 2, 3, 4, 5, 6], [3, 2])
            ->[ [1, 2], [3, 4], [5, 6] ]
      \end{lstlisting}



      %%% -------------------------------------------------------

      \fitem{resize}(tab, int), \vImpure: resize its argument and returns the
      results. If the second argument is smaller that the size of the
      first argument, it effectively shrinks the first argument. If it is
      greater, undefined values are used to extend the tab. 


      %%% -------------------------------------------------------

      \fitem{reverse}(tab): returns a new tab where the element are given in
      the reverse order. 


      %%% -------------------------------------------------------

      \fitem{reverse}(string): returns a new string where the character
      are given in the reverse order.


      %%% -------------------------------------------------------

      \fitem{rnd_bernoulli}($p$:float), \vImpure. The members of the
      \texttt{@rnd\_\emph{distribution}} family return a random generator
      in the form of an impure function $f$ taking no argument. Each time
      $f$ is called, the value of a random variable following the
      \texttt{\emph{distribution}} distribution is returned. The arguments
      of the \texttt{@rnd\_\emph{distribution}} are the parameters of the
      distribution. Two successive calls to
      \texttt{@rnd\_\emph{distribution}} returns two different random
      generators for the same distribution, that is, generators with
      unrelated seeds.

      \code{@rnd_bernouilli}($p$) returns a boolean random generator with
      a probability $p$ to have a \code{true} value. For example
      \begin{lstlisting}
            $bernouilli := @rnd_bernouilli(0.6)
            $t := [ $bernouilli() | (1000) ] 
      \end{lstlisting} %% $
      produces a tab of 1000 random boolean values with a probability of
      0.6 to be true. 

      

      %%% -------------------------------------------------------

      \fitem{rnd_binomial}($t$:int, $p$:float) returns a random generator
      that produces integers according to a \emph{binomial discrete
        distribution} $P$:
      $$
      P(i, | t, p) = \binom{t}{i} \, p^i \, (1 - p)^{t-i}, \quad i \geq 0.
      $$



      %%% -------------------------------------------------------

      \fitem{rnd_exponential}($\lambda$:float) returns a random generator
      that produces floats $x$ according to an \emph{exponential
        distribution} $P$:
      $$
      P(x | \lambda) = \lambda e^{-\lambda x}, \quad x > 0.
      $$



      %%% -------------------------------------------------------

      \fitem{rnd_gamma}($\alpha$:float): returns a random generator that
      produces floating-point values according to a \emph{gamma
        distribution} $P$:
      $$
      P(x | \alpha) = \frac{1}{\Gamma(\alpha)} \, x^{\alpha-1}, 
      \quad x \geq 0.
      $$



      %%% -------------------------------------------------------

      \fitem{rnd_geometric}($p$:int)  returns a random generator that
      produces integers following a \emph{geometric discrete
        distribution}:
      $$
      P(i | p) = p (1 - p)^i, \quad, i \geq 0.
      $$



      %%% -------------------------------------------------------

      \fitem{rnd_normal}($\mu$:float, $\sigma$:float) returns a random
      generator that produces floating-point values according to a
      \emph{normal distribution} $P$:
      $$
      P(x | \mu, \sigma) = 
      \frac{1}{\sigma \sqrt{2 \pi}}
      e^{-\frac{(x - \mu)^2}{2 \sigma^2}}
      $$



      %%% -------------------------------------------------------

      \fitem{rnd_uniform_int}($a$:int, $b$:int) returns a generator giving
      integer values according to a \emph{uniform discrete distribution}:
      $$
      P(i | a, b) = \frac{1}{b - a + 1}, \quad a \leq i \leq b.
      $$



      %%% -------------------------------------------------------

      \fitem{rnd_uniform_float}($a$:int, $b$:int) returns a generator giving
      float values according to a \emph{uniform distribution}:
      $$
      P(x | a, b) = \frac{1}{b - a}, \quad a \leq x < b.
      $$



      %%% -------------------------------------------------------

      \fitem{rotate}(t:tab, n:int) build a new array which contains the
      elements of \code{t} circularly shifted by \code{n}. If \code{n} is
      positive the element are right shifted, else they are left shifted.
      \begin{lstlisting}
            @rotate([1, 2, 3, 4], -1) == [2, 3, 4, 1]
            @rotate([1, 2, 3, 4], 1) == [4, 1, 2, 3] 
      \end{lstlisting}




      %%% -------------------------------------------------------

      \fitem{round}(numeric), \vListable: returns the integral value
      nearest to its argument rounding half-way cases away from zero,
      regardless of the current rounding direction.




      %%% -------------------------------------------------------

      \fitem{rplot}(\emph{variable}) or \atvar{rplot}(\emph{variable}$_1$,
      ... \emph{variable}$_p$) is a special form (the arguments are
      restricted to be variables). Calling this special form plots the
      values stored in the history of the variables as time series in
      relative time using
      the \texttt{gnuplot} function. See page~\pageref{sec:rplot} and also
      the library function \atvar{plot}.



      %%% -------------------------------------------------------

      \fitem{sample}{nim, p:numeric} build a new nim with linear
      interpolation type by sampling each component at \code{p} points
      equally spaced between the first and the last breakpoint. See
      p.~\pageref{fct:sample} and function \acode{linearize} and
      \acode{align_breakpoints}. 


      %%% -------------------------------------------------------

      \fitem{savevalue}(s:string, \vValue), \vImpure: argument is
      interpreted as the path of a file where the value of the second
      argument is saved. The format of the file is textual and corresponds
      to the \Antescofo grammar. This value can then be read using the
      function \atvar{loadvalue}. See also functions \atvar{dump},
      \atvar{dumpvar} and \atvar{loadvar}.

      

      %%% -------------------------------------------------------

      \fitem{scan}(f:function, t:tab) returns the tab %%
      \code{[ t[0], f(t[0],t[1]), f(f(t[0], t[1]),t[2]), ...]}. For
      example, the tab of the partial sums of the integers between
      \code{0} (included) and \code{10} (excluded) is computed by the
      expression:
      \begin{lstlisting}
            @scan(@+, [$x | $x in (10)])  -> [0,1,3,6,10,15,21,28,36,45]
      \end{lstlisting}



      %%% -------------------------------------------------------

      \fitem{scramble}(t:tab) : returns a new tab where the elements of 
      \code{t} have been scrambled. The argument is unchanged.%%


      %%% -------------------------------------------------------

      \fitem{select_map}


      %%% -------------------------------------------------------

      \fitem{shape}(t:value) %
      \index{dim@\atvar{dim}}\index{dimension}\index{shape} %
      returns 0 if \code{t} is not an array, and else returns a tab of
      integers each corresponding to the size of one of the dimensions of
      \code{t}. Notice that the elements of an array are homogeneous,
      \emph{i.e.} they have all exactly the same dimension and the same
      shape.



      %%% -------------------------------------------------------

      \fitem{shift_map}


      %%% -------------------------------------------------------

      \fitem{simplify_lang_v}(nim, tol:numeric, n:numeric) simplifies a
      nim by aggregating breakpoints using a Lang polyline
      simplification algorithm. See p.~\pageref{fct:simplifyLangV}.

      %%% -------------------------------------------------------

      \fitem{simplify_radial_distance_t}(nim, tol:numeric) simplifies a
      nim by aggregating consecutive breakpoints whose images are wihin
      a distance of \code{tol}. See
      p.~\pageref{fct:simplifyRadialDistanceT}.

      %%% -------------------------------------------------------

      \fitem{simplify_radial_distance_v}(nim, tol:numeric) simplifies a
      nim independantly for each component, by aggregating consecutive
      breakpoints that are wihin a distance of \code{tol}. See
      p.~\pageref{fct:simplifyRadialDistanceV}.


      %%% -------------------------------------------------------

      \fitem{sinh}(x:numeric), \vListable: computes the hyperbolic sine of
      \code{x}.


      %%% -------------------------------------------------------

      \fitem{sin}(x:numeric), \vListable: computes the sine of \code{x}
      (measured in radians).



      %%% -------------------------------------------------------

      \fitem{size}(x:\vValue): if \code{x} is a scalar value, it return
      a strictly negative integer related to the type of the argument
      (that is, two scalar values of the same type gives the same
      result). If it is a map or a tab, it returns the number of element
      in its argument (which is a positive integer). If it is a nim, it
      returns the number of breakpoints of the nim (which is not the
      dimension of the nim). Note that a nim with zero breakpoints is
      the result of a wrong definition.

      %%% -------------------------------------------------------

      \fitem{slice}{(t:tab, n:numeric, m:numeric)} gives the elements of
      \code{t} of indices between \code{n} included up to \code{m}
      excluded. If \code{n > m} the element are given in reverse
      order. So
      \begin{lstlisting}
            @slide(t, @size(t), 0) 
      \end{lstlisting}
      is equivalent to
      \begin{lstlisting}
            @reverse(t)
      \end{lstlisting}
      See also functions \acode{cdr}, \acode{drop} and \acode{take}.




      %%% -------------------------------------------------------

      \fitem{sort}{(t:tab)} \vImpure: sorts in-place the elements into
      ascending order using \code{<}.


      %%% -------------------------------------------------------

      \fitem{sort}{(t:tab, cmp:fct)} \vImpure: sorts in-place the elements
      into ascending order.  The elements are compared using the function
      \code{cmp}.  This function must accept two elements of the tab
      \code{t} as arguments, and returns a value converted to bool. The
      value returned indicates whether the element passed as first
      argument is considered to go before the second.



      %%% -------------------------------------------------------

      \fitem{sputter}{(t:tab, p:float, n:numeric)} \vImpure: returns a
      new tab of length \code{n}. This tab is filled as follows: for each
      element, a random number between 0 and 1 is compared with \code{p} :
      if it is lower, then the element is the current element in
      \code{t}. If it is greater, we take the next element in \code{t}
      which becomes the current element. The process starts with the first
      element in \code{t}.
      \begin{lstlisting}
            @sputter([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 0.5, 16) 
            ->[ 1, 1, 1, 1, 1, 2, 3, 4, 5, 6, 6, 6, 7, 8, 8, 9 ]
            ->[ 1, 2, 3, 3, 4, 5, 6, 7, 8, 8, 9, 9, 9, 9, 10 ]
            ->[ 1, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 4, 5, 5, 5 ]
      \end{lstlisting}



      %%% -------------------------------------------------------

      \fitem{sqrt}(x:numeric), \vListable: computes the non-negative
      square root of \code{x}.


      %%% -------------------------------------------------------

      \fitem{string2fun}(s:string): returns the function whose name is
      given in argument. The initial \code{@} in the function name can
      be omitted. Useful to convert directly a string received through
      OSC or through the \code{setvar} message into a function that can
      be applied. 

      %%% -------------------------------------------------------

      \fitem{string2proc}(s:string): returns the proc whose name is
      given in argument. The initial \code{::} in the proc identifier
      can be omitted. Useful to convert directly a string received
      through OSC or through the \code{setvar} message into a function
      that can be applied.

      For example, assuming that \var{channel} is set in the Max
      environment to a tab of two element, the first being a process
      identifier and the second an integer, then the code
      \begin{lstlisting}
            whenever($channel)
            {
                 :: (@string2proc($channel[0])) ($channel[1])
            }
      \end{lstlisting} %% $
      will react to the assignment to \var{channel} by calling the
      corresponding processes with the specified integer. 


      %%% -------------------------------------------------------

      \fitem{stutter}(t:tab, n:numeric), \vImpure: returns a new tab whose
      elements are repeated n times. The receiver is unchanged. The
      argument is unchanged.
      \begin{lstlisting}
            @stutter([1, 2, 3, 4, 5, 6], 2) 
            -> [ 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6 ]
      \end{lstlisting}


      %%% -------------------------------------------------------

      \fitem{system}(cmd:string), \vImpure: This function hands the
      argument command to the command interpreter sh.  The calling process
      waits for the shell to finish executing the command, ignoring SIGINT
      and SIGQUIT, and blocking SIGCHLD. A false boolean value is returned
      if an error occured (in this case an error message is issued). 


      
      %%% -------------------------------------------------------

      \fitem{tab_history}(\emph{variable}) : This is a special form. It
      returns a tab of the value of the variable in
      argument. See. sect.~\ref{sec:mapvariable}
      page~\pageref{sec:mapvariable} and the 
      \code{@map_historyXXX} functions. 

      %%% -------------------------------------------------------

      \fitem{tab_history_date}(\emph{variable}) : This is a special
      form. It returns a tab of the date in physical time of the updates
      of the variable in argument. See. sect.~\ref{sec:mapvariable}
      page~\pageref{sec:mapvariable}  and the 
      \code{@map_historyXXX} functions. 



      %%% -------------------------------------------------------

      \fitem{tab_history_rdate}(\emph{variable}) : This is a special
      form. It returns a tab of the date in relative time of the updates
      of the variable in argument. See. sect.~\ref{sec:mapvariable}
      page~\pageref{sec:mapvariable}  and the 
      \code{@map_historyXXX} functions. 


      %%% -------------------------------------------------------

      \fitem{take}(t:tab, n:numeric) gives the first \code{n} elements
      of \code{t} if \code{n} is a positive integer and the last
      \code{n} elements of \code{t} if \code{n} is a negative integer.

      %%% -------------------------------------------------------

      \fitem{take}(t:tab, x:tab) gives the tab of
      elements whose indices are in tab \code{x}. Equivalent to 
      \begin{lstlisting}
            [t[x[$i]] | $i in @size(x)]
      \end{lstlisting}
      See also functions \acode{cdr}, \acode{drop} and \acode{slice}.



      %%% -------------------------------------------------------

      \fitem{tan}(x:numeric), \vListable: computes the tangent of \code{x}
      (measured in radians).

      %%% -------------------------------------------------------


      \fitem{Tracing}() : start to trace the calls to all user-defined
      functions.

      %%% -------------------------------------------------------

      \fitem{Tracing}(x:function \emph{or} string \emph{or} tab, ...) :
      start to trace the calls to all functions specified by the
      arguments. Functions to trace are given by their name (as a
      string) or by their value (through their identifier) or by a tab
      containing such values.

      %%% -------------------------------------------------------

      \fitem{UnTracing}() : stop to trace the calls to all user-defined
      functions.

      %%% -------------------------------------------------------

      \fitem{UnTracing}(x:function \emph{or} string \emph{or} tab, ...)
      : stop to trace the calls to all functions specified by the
      arguments. Functions to trace are given by their name (as a
      string) or by their value (through their identifier).


      %%% -------------------------------------------------------

      \fitem{window_filter_t}(nim, coef:tab, pos:numeric) computes a new
      nim, where the image $y_0$ of each breakpoint is replaced by the dot
      product of \code{coef} with a sequence of $y$'s of the same length
      as \code{coef} where position \code{pos} corresponds to $y_0$. See
      p.~\pageref{fct:windowFilterT}. 

\end{itemize}
