
% Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
% All rights reserved.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
%
%     - Redistributions of source code must retain the above copyright
%       notice, this list of conditions and the following disclaimer.
%
%     - Redistributions in binary form must reproduce the above copyright
%       notice, this list of conditions and the following disclaimer in
%       the documentation and/or other materials provided with the
%       distribution.
%
%     - Neither the name of The Numerical ALgorithms Group Ltd. nor the
%       names of its contributors may be used to endorse or promote products
%       derived from this software without specific prior written permission.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
% IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
% TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
% PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
% OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES-- LOSS OF USE, DATA, OR
% PROFITS-- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.



Function are objects of type \pspadtype{Mapping}.
In this section we demonstrate some library operations from the
packages \spadtype{MappingPackage1}, \spadtype{MappingPackage2}, and
\spadtype{MappingPackage3} that manipulate and create functions.
Some terminology: a {\it nullary} function takes no arguments,
\index{function!nullary}
a {\it unary} function takes one argument, and
\index{function!unary}
a {\it binary} function takes two arguments.
\index{function!binary}

\xtc{
We begin by creating an example function that raises a
rational number to an integer exponent.
}{
\spadcommand{power(q: FRAC INT, n: INT): FRAC INT == q^n \bound{power}}
}
\xtc{
}{
\spadcommand{power(2,3) \free{power}}
}
\xtc{
The \spadfunFrom{twist}{MappingPackage3} operation
transposes the arguments of a binary function.
Here \spad{rewop(a, b)} is \spad{power(b, a)}.
}{
\spadcommand{rewop := twist power \free{power}\bound{rewop}}
}
\xtc{
This is \texht{$2^3.$}{\spad{2^3.}}
}{
\spadcommand{rewop(3, 2) \free{rewop}}
}
\xtc{
Now we define \userfun{square} in terms of \userfun{power}.
}{
\spadcommand{square: FRAC INT -> FRAC INT \bound{squaredec}}
}
\xtc{
The \spadfunFrom{curryRight}{MappingPackage3} operation creates a unary
function from a binary one by providing a constant
argument on the right.
}{
\spadcommand{square:= curryRight(power, 2) \free{squaredec poswer}\bound{square}}
}
\xtc{
Likewise, the
\spadfunFrom{curryLeft}{MappingPackage3} operation provides a constant
argument on the left.
}{
\spadcommand{square 4 \free{square}}
}
\xtc{
The \spadfunFrom{constantRight}{MappingPackage3} operation creates
(in a trivial way) a binary function from a unary one:
\spad{constantRight(f)} is the function \spad{g} such that
\spad{g(a,b)= f(a).}
}{
\spadcommand{squirrel:= constantRight(square)\$MAPPKG3(FRAC INT,FRAC INT,FRAC INT) \free{square}\bound{squirrel}}
}
\xtc{
Likewise,
\spad{constantLeft(f)} is the function \spad{g} such that \spad{g(a,b)= f(b).}
}{
\spadcommand{squirrel(1/2, 1/3) \free{squirrel}}
}
\xtc{
The \spadfunFrom{curry}{MappingPackage2} operation makes a unary function nullary.
}{
\spadcommand{sixteen := curry(square, 4/1) \free{square}\bound{sixteen}}
}
\xtc{
}{
\spadcommand{sixteen() \free{sixteen}}
}
\xtc{
The \spadopFrom{*}{MappingPackage3} operation
constructs composed functions.
}{
\spadcommand{square2:=square*square \free{square}\bound{square2}}
}
\xtc{
}{
\spadcommand{square2  3 \free{square2}}
}
\xtc{
Use the \spadopFrom{^}{MappingPackage1} operation to create
functions that are \spad{n}-fold iterations of other functions.
}{
\spadcommand{sc(x: FRAC INT): FRAC INT == x + 1 \bound{sc}}
}
\xtc{
This is a list of \pspadtype{Mapping} objects.
}{
\spadcommand{incfns := [sc^i for i in 0..10] \free{sc}\bound{incfns}}
}
\xtc{
This is a list of applications of those functions.
}{
\spadcommand{[f 4 for f in incfns] \free{incfns}}
}
\xtc{
Use the \spadfunFrom{recur}{MappingPackage1}
operation for recursion:
\spad{g := recur f} means \spad{g(n,x) == f(n,f(n-1,...f(1,x))).}
}{
\spadcommand{times(n:NNI, i:INT):INT == n*i \bound{rdec}}
}
\xtc{
}{
\spadcommand{r := recur(times) \free{rdec}\bound{r}}
}
\xtc{
This is a factorial function.
\index{factorial}
}{
\spadcommand{fact := curryRight(r, 1) \free{r}\bound{fact}}
}
\xtc{
}{
\spadcommand{fact 4 \free{fact}}
}
\xtc{
Constructed functions can be used within other functions.
}{
\begin{spadsrc}[\free{square}\bound{mto2ton}]
mto2ton(m, n) ==
  raiser := square^n
  raiser m
\end{spadsrc}
}
\xtc{
This is \texht{$3^{2^3}.$}{\spad{3^(2^3).}}
}{
\spadcommand{mto2ton(3, 3) \free{mto2ton}}
}
\xtc{
Here \userfun{shiftfib} is a unary function that modifies its argument.
}{
\begin{spadsrc}[\bound{shiftfib}]
shiftfib(r: List INT) : INT ==
  t := r.1
  r.1 := r.2
  r.2 := r.2 + t
  t
\end{spadsrc}
}
\xtc{
By currying over the argument we get a function with private state.
}{
\spadcommand{fibinit: List INT := [0, 1] \bound{fibinitdec}}
}
\xtc{
}{
\spadcommand{fibs := curry(shiftfib, fibinit) \free{shiftfib fibinit}\bound{fibs}}
}
\xtc{
}{
\spadcommand{[fibs() for i in 0..30] \free{fibs}}
}
