continued work

[clqr.git] / clqr-numbers.tex

% Copyright (C) 2008 Bert Burgemeister
%
% Permission is granted to copy, distribute and/or modify this
% document under the terms of the GNU Free Documentation License,
% Version 1.2 or any later version published by the Free Software
% Foundation; with no Invariant Sections, no Front-Cover Texts and
% no Back-Cover Texts. For details see file COPYING.
%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Numbers} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Predicates} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{LIST}{1cm}

  \IT{\arrGOO{(\FU{\boldmath$=$}\RP{\VAR{
          number}})\\
      (\FU{\boldmath$/=$}\RP{\VAR{ number}})}{.}}
     {
       \index{=}%
       \index{/=}%
       Return \retval{\T} if all \VAR{number}s, or
       none, respectively,  are equal.
     }

  \IT{\arrGOO{(\FU{\boldmath$>$}\RP{\VAR{
          number}})\\(\FU{\boldmath$>=$}\RP{\VAR{
          number}})\\(\FU{\boldmath$<$}\RP{\VAR{
          number}})\\(\FU{\boldmath$<=$}\RP{\VAR{ number}})}{.}}
  {
  \index{>@$>$}%
  \index{>=@$>=$}%
  \index{<@$<$}%
  \index{<=@$<=$}%
  Return \retval{\T} if \VAR{number}s are
  monotonically decreasing, monotonically non-increasing,
  monotonically increasing, or monotonically non-decreasing, respectively. 
  }

  \IT{\arrGOO{(\FU*{MINUSP} \VAR{ a})\\
      (\FU*{ZEROP} \VAR{ a})\\
      (\FU*{PLUSP}
      \VAR{ a})}{.}}
  {
  Return \retval{\T} if $a < 0$, $a = 0$, or $a > 0$, respectively.
  }

  \IT{\arrGOO{(\FU*{EVENP } \VAR{integer})\\
      (\FU*{ODDP } \VAR{integer})}{\}}}
  {
    Return \retval{\T} if \VAR{integer} is even or odd, respectively.
  }

  \IT{\arrGOO{(\FU*{NUMBERP} \VAR{ foo})\\
      (\FU*{INTEGERP} \VAR{ foo})\\
      (\FU*{RATIONALP} \VAR{ foo})\\
      (\FU*{FLOATP} \VAR{ foo})\\
      (\FU*{REALP} \VAR{ foo})\\
      (\FU*{COMPLEXP} \VAR{ foo})\\
      (\FU*{RANDOM-STATE-P} \VAR{ foo})
      }{.}}
  {
  \retval{\T} if \VAR{foo} is of
  indicated type.
  }

  \IT{(\FU*{LOGBITP} \VAR{i} \VAR{integer})}
  {
  \retval{\T} if zero-indexed \VAR{i}th bit of \VAR{integer} is set.
  }


\end{LIST}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Numeric Functions} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{LIST}{1cm}

  \IT{(\FU*{ABS} \VAR{n})}
  {
  Return \retval{$|n|$}
  }

  \IT{\arrGOO{(\FU*{+} \OPn{\VAR{ a}})\\
      (\FU*{*} \OPn{\VAR{ a}})}{.}}
  {
  Return \retval{$\sum{a}$} or \retval{$\prod{a}$}, respectively. Without any
  \VAR{a}s, return \retval{0} or \retval{1}, respectively.
  }

  \IT{\arrGOO{(\FU*{--} \VAR{ a}\OPn{\VAR{ b}})\\
      (\FU*{/} \VAR{ a}
      \OPn{\VAR{ b}})}{.}}
  {
  Return \retval{$a-\sum{b}$} or \retval{$a/\prod{b}$}, respectively. Without any
  \VAR{b}s, return \retval{$-a$} or \retval{$1/a$}, respectively.
  }

  \IT{\arrGOO{(\FU*{1+} \VAR{ a})\\(\FU*{1--} \VAR{ a})}{.}}
  {Return \retval{$a+1$} or
  \retval{$a-1$}, respectively.
  }

  \IT{(\xorGOO{\SF*{INCF}\\\SF*{DECF}}{\}} \VAR{place}
    \Op{\VAR{delta}\DF{1}})}
  {
  Increment or
  decrement \VAR{place} by \VAR{delta} returning \retval{new value}.
  }

  \IT{(\FU*{EXP} \VAR{p})}
  {Return \retval{$\mbox{e}^p$}.
    }

  \IT{(\FU*{EXPT} \VAR{b} \VAR{p})}
  {Return \retval{$b^p$}.
    }

  \IT{(\FU*{LOG} \VAR{a} \Op{\VAR{b}})}
  {
  Return \retval{$\log_b a$} or,
  without \VAR{b}, \retval{$\ln a$}.
  }

  \IT{\arrGOO{(\FU*{SQRT} \VAR{ n})\\
      (\FU*{ISQRT} \VAR{ n})}{.}}
  {
  Return, in complex or natural numbers, respectively, $\sqrt{n}$.
  }

  \IT{\arrGOO{(\FU*{LCM} \OPn{\VAR{ integer}}\DF{1})\\
      (\FU*{GCD} \OPn{\VAR{ integer}})}{.}}
  {
  \retval{Least common multiple} or \retval{greatest common
    denominator}, respectively, of \VAR{integer}s. 
  }

  \IT{\CNS*{PI}}
  {
  \kwd{long-float} approximation of $\pi$, Ludolph's number.
  }

  \IT{\arrGOO{(\FU*{SIN} \VAR{ a})\\
      (\FU*{COS} \VAR{ a})\\
      (\FU*{TAN} \VAR{ a})}{.}}
  {
  With \VAR{a} in radians, return \retval{$\sin a$}, \retval{$\cos
    a$}, or \retval{$\tan a$}, respectively.
  }

  \IT{\arrGOO{(\FU*{ASIN} \VAR{ a})\\
      (\FU*{ACOS} \VAR{ a})}{.}}
  {
  \retval{$\arcsin a$} or \retval{$\arccos
    a$}, respectively, in radians.
  }

  \IT{(\FU*{ATAN} \VAR{a} \Op{\VAR{b}\DF{1}})}
  {
  \retval{$\arctan \frac{a}{b}$} in radians.
  }

  \IT{\arrGOO{(\FU*{SINH} \VAR{ a})\\(\FU*{COSH} \VAR{ a})\\(\FU*{TANH}
      \VAR{ a})}{.}}
  {
  Return \retval{$\sinh a$}, \retval{$\cosh
    a$}, or \retval{$\tanh a$}, respectively.
  }

  \IT{\arrGOO{(\FU*{ASINH} \VAR{ a})\\
      (\FU*{ACOSH} \VAR{ a})
      \\(\FU*{ATANH} \VAR{ a})}{.}}
  {
  \retval{$\operatorname{asinh} a$}, \retval{$\operatorname{acosh}
    a$}, or \retval{$\operatorname{atanh} a$}, respectively.
  }

  \IT{(\FU*{CIS} \VAR{a})}
  {
  Return
  \retval{$\operatorname{e}^{\operatorname{i} a} = \cos a +
    \operatorname{i}\sin a$}.
  }

  \IT{(\FU*{CONJUGATE} \VAR{a})}
  {Return \retval{conjugate of \VAR{a}}.
    }

  \IT{\arrGOO{(\FU*{NUMERATOR} \VAR{ rational})\\
      (\FU*{DENOMINATOR} \VAR{ rational})}{.}}
  {
  Return \retval{numerator} or  \retval{denominator}, respectively, of
  \VAR{rational}'s canonical form.
  }

  \IT{\arrGOO{(\FU*{REALPART} \VAR{ number})\\
      (\FU*{IMAGPART} \VAR{ number})}{.}}
  {
  Return \retval{real part} or \retval{imaginary part}, respectively, of \VAR{number}.
  }

  \IT{\arrGOO{(\FU*{MAX } \RP{\VAR{num}})\\
      (\FU*{MIN } \RP{\VAR{num}})}{.}}
  {
  Return \retval{greatest} or \retval{least}, respectively, of \VAR{num}s.
  }

  \IT{(\xorGOO{%
      \Goo{\FU*{FLOOR}\XOR\FU*{FFLOOR}}\\
      \Goo{\FU*{CEILING}\XOR\FU*{FCEILING}}\\
      \Goo{\FU*{TRUNCATE}\XOR\FU*{FTRUNCATE}}\\
      \Goo{\FU*{ROUND}\XOR\FU*{FROUND}}}{\}}
    \VAR{n} \Op{\VAR{d}\DF{1}})}
  {
  Return \retval{$n/d$} (\kwd{integer} or \kwd{float}, respectively) truncated
  towards $-\infty$, $+\infty$, $0$, or rounded, respectively; and \retvalii{remainder}.
  }

  \IT{(\xorGOO{\FU*{MOD}\\
      \FU*{REM}}{\}} \VAR{n} \Op{\VAR{d}\DF{1}})}
  {Same as \FU{floor} or
  \FU{truncate}, respectively, but return \retval{remainder} only.
  }

  \IT{(\FU*{RANDOM} \VAR{limit} \Op{\VAR{state}\DF{\V{*random-state}}})} 
  {
    Return non-negative \retval{random
    number} less then, and  of type of \VAR{limit}.
  }

  \IT{(\FU*{MAKE-RANDOM-STATE} \Op{\VAR{state}\DF{\NIL}})}
  {
  Make \retval{random state}.
  }

  \IT{\V*{*random-state*}}
  {
  Current random state.
  }

  \IT{(\FU*{FLOAT-SIGN} \VAR{num-a} \Op{\VAR{num-b}\DF{1}})}
  {
  \retval{\VAR{num-b}} with the sign of \VAR{num-a}.
  }

  \IT{(\FU*{SIGNUM} \VAR{n})}
  {\retval{Number} of magnitude 1
  representing sign or phase of \VAR{n}.
  }

  \IT{(\FU*{COMPLEX} \VAR{real} \Op{\VAR{imag}\DF{0}})}
  {Make a \retval{complex number}.
    }

  \IT{(\FU*{PHASE} \VAR{number})}
  {\retval{Angle} of \VAR{number}'s polar representation.
    }

  \IT{\arrGOO{(\FU*{RATIONAL} \VAR{ real})\\
      (\FU*{RATIONALIZE} \VAR{ real})}{.}}
  {
  Convert \VAR{real} to \retval{rational}. Assume complete/limited accuracy for \VAR{real}.
  }

  \IT{(\FU*{FLOAT} \VAR{real}
    \Op{\VAR{prototype}\DF{\kwd{single-float}}})}
  {
  Convert \VAR{real} into \VAR{prototype}-shaped \retval{float}.
  }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Logic Functions} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{section:Logic Functions}

\begin{LIST}{1cm}

  \IT{(\kwd*{BOOLE} \VAR{operation} \VAR{int-a} \VAR{int-b})}
  {
  Return
  \retval{value} of bit-wise logical \VAR{operation}. \VAR{operation}s
  are
  }
  
  \begin{LIST}{.5cm}
    \IT{\CNS*{BOOLE-1}} {\retval{\VAR{int-a}}.}
    \IT{\CNS*{BOOLE-2}} {\retval{\VAR{int-b}}.}
    \IT{\CNS*{BOOLE-C1}} {\retval{Two's complement of \VAR{int-a}}.}
    \IT{\CNS*{BOOLE-C2}} {\retval{Two's complement of \VAR{int-b}}.}
    \IT{\CNS*{BOOLE-SET}} {\retval{All bits set}.}
    \IT{\CNS*{BOOLE-CLR}} {\retval{All bits zero}.}
    \IT{\CNS*{BOOLE-EQV}} {\retval{$\text{\VAR{int-a}} \equiv \text{\VAR{int-b}}$}.}
    \IT{\CNS*{BOOLE-AND}} {\retval{$\text{\VAR{int-a}}\land\text{\VAR{int-b}}$}.}
    \IT{\CNS*{BOOLE-ANDC1}} {\retval{Two's complement of \VAR{int-a} $\land$ \VAR{int-b}}.}
    \IT{\CNS*{BOOLE-ANDC2}} {\retval{\VAR{int-a} $\land$ two's complement of \VAR{int-b}}.}
    \IT{\CNS*{BOOLE-NAND}} {\retval{$\lnot(\text{\VAR{int-a}} \land \text{\VAR{int-b}})$}.}
    \IT{\CNS*{BOOLE-IOR}} {\retval{$\text{\VAR{int-a}} \lor \text{\VAR{int-b}}$}.}
    \IT{\CNS*{BOOLE-ORC1}} {\retval{Two's complement of \VAR{int-a} $\lor$ \VAR{int-b}}.}
    \IT{\CNS*{BOOLE-ORC2}} {\retval{\VAR{int-a} $\lor$ two's complement of \VAR{int-b}}.}
    \IT{\CNS*{BOOLE-XOR}} {\retval{$\lnot(\text{\VAR{int-a}} \equiv \text{\VAR{int-b}})$}.}
    \IT{\CNS*{BOOLE-NOR}} {\retval{$\lnot(\text{\VAR{int-a}} \lor \text{\VAR{int-b}})$}.}
  \end{LIST}

  \IT{(\FU*{LOGNOT}\VAR{ integer})}
  {
    \retval{Two's complement of \VAR{integer}}.
  }

  \IT{\arrGOO{(\FU*{LOGEQV} \OPn{\VAR{ integer}})\\
      (\FU*{LOGAND} \OPn{\VAR{ integer}})}{.}}
  {
  Return \retval{value of exclusive-nored or anded \VAR{integer}s},
  respectively. Without any \VAR{integer}, return \retval{$-1$}.
  }

  \IT{(\FU*{LOGANDC1} \VAR{ int-a} \VAR{ int-b})}
  {
   \retval{Two's complement of \VAR{int-a} $\land$ \VAR{int-b}}.
   }

  \IT{(\FU*{LOGANDC2} \VAR{ int-a} \VAR{ int-b})}
  {
  \retval{\VAR{int-a} $\land$ two's complement of \VAR{int-b}}.
  }

  \IT{(\FU*{LOGNAND} \VAR{ int-a} \VAR{ int-b})}
  {
  \retval{$\lnot(\text{\VAR{int-a}} \land \text{\VAR{int-b}})$}.
  }

  \IT{\arrGOO{(\FU*{LOGXOR} \OPn{\VAR{ integer}})\\
      (\FU*{LOGIOR} \OPn{\VAR{ integer}})}{.}}
  {
  Return \retval{value of exclusive-ored or ored \VAR{integer}s},
  respectively. Without any \VAR{integer}, return \retval{0}.
  }

  \IT{(\FU*{LOGORC1} \VAR{ int-a} \VAR{ int-b})}
  {
 \retval{Two's complement of \VAR{int-a} $\lor$ \VAR{int-b}}.
 }

  \IT{(\FU*{LOGORC2} \VAR{ int-a} \VAR{ int-b})}
  {
  \retval{\VAR{int-a} $\lor$ two's complement of \VAR{int-b}}.
  }

  \IT{(\FU*{LOGNOR} \VAR{ int-a} \VAR{ int-b})}
  {
  \retval{$\lnot(\text{\VAR{int-a}} \lor \text{\VAR{int-b}})$}.
  }

  \IT{(\FU*{LOGTEST} \VAR{int-a} \VAR{int-b})}
  {Return \retval{\T} if
  there is any bit set in \VAR{int-a} which ist set in \VAR{int-b} as well.
  }

  \IT{(\FU*{LOGCOUNT} \VAR{integer})}
  {
    \retval{number of bits} set
  in \VAR{integer}.
  }

  \IT{(\FU*{ASH} \VAR{integer} \VAR{count})}
  {
  Return copy of \retval{\VAR{integer}} arithmetically shifted left with zeros added
  at the right, or, for $\VAR{count}<0$, shifted right discarding
  bits. 
  }

  \IT{(\FU*{MASK-FIELD} \VAR{byte-spec} \VAR{integer})}
  {
  Return copy of \retval{\VAR{integer}} with all bits unset but those denoted by
  \VAR{byte-spec}. \kwd{setf}able.
  }


\end{LIST}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Integer Functions} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}

  \IT{(\FU*{INTEGER-LENGTH} \VAR{integer})}
  {
  \retval{Number of bits} necessary to represent \VAR{integer}. 
  }

  \IT{(\FU*{LDB-TEST} \VAR{byte-spec} \VAR{integer})}
  {
  Return \retval{\T} if any bit specified by \VAR{byte-spec} in
  \VAR{integer} is set.
  }

  \IT{(\FU*{LDB} \VAR{byte-spec} \VAR{integer})}
  {
  Extract \retval{byte} denoted by \VAR{byte-spec} from
  \VAR{integer}. \kwd{setf}able. 
  }

  \IT{(\FU*{BYTE} \VAR{size} \VAR{position})}
  {
  \retval{Byte specifier} for a byte of \VAR{size} bits starting at a
  weight of $2^{\VAR{position}}$. 
  }

  \IT{\arrGOO{(\FU*{BYTE-SIZE} \VAR{ byte-spec})\\
      (\FU*{BYTE-POSITION} \VAR{ byte-spec})}{.}}
  {
  \retval{Size} or \retval{position}, respective,  of \VAR{byte-spec}.
  }

  \IT{(\xorGOO{\FU*{DEPOSIT-FIELD}\\
      \FU*{DPB}}{\}}
    \VAR{int-a} \VAR{byte-spec} \VAR{int-b})}
  {
  Return \retval{\VAR{int-b}} with bits denoted by \VAR{byte-spec} replaced
  by corresponding bits of \VAR{int-a}, or by the low (\FU{byte-size}
  \VAR{byte-spec}) bits of \VAR{int-a}, respectively. 
  }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[Implementation- Dependent]{Implementation-Dependent} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}

  \IT{\arrGOO{\CNS{SHORT-FLOAT}\\
      \CNS{SINGLE-FLOAT}\\
      \CNS{DOUBLE-FLOAT}\\
      \CNS{LONG-FLOAT}}{\}}\kwd{-}%
    \xorGOO{\kwd{EPSILON}\\
      \kwd{NEGATIVE-EPSILON}}{.}}
  {
  \index{SHORT-FLOAT-EPSILON}%
  \index{SINGLE-FLOAT-EPSILON}%
  \index{DOUBLE-FLOAT-EPSILON}%
  \index{LONG-FLOAT-EPSILON}%
  \index{SHORT-FLOAT-NEGATIVE-EPSILON}%
  \index{SINGLE-FLOAT-NEGATIVE-EPSILON}%
  \index{DOUBLE-FLOAT-NEGATIVE-EPSILON}%
  \index{LONG-FLOAT-NEGATIVE-EPSILON}%
  Smallest possible number making a difference when added or subtracted, respectively.
  }

  \IT{\arrGOO{%
      \CNS{LEAST-NEGATIVE}\\
      \CNS{LEAST-NEGATIVE-NORMALIZED}\\
      \CNS{LEAST-POSITIVE}\\
      \CNS{LEAST-POSITIVE-NORMALIZED}}{\}}%
    \kwd{-}%
    \xorGOO{%
      \kwd{SHORT-FLOAT}\\
      \kwd{SINGLE-FLOAT}\\
      \kwd{DOUBLE-FLOAT}\\
      \kwd{LONG-FLOAT}}{.}}
  {
  \index{LEAST-NEGATIVE-SHORT-FLOAT}%
  \index{LEAST-NEGATIVE-NORMALIZED-SHORT-FLOAT}%
  \index{LEAST-NEGATIVE-SINGLE-FLOAT}%
  \index{LEAST-NEGATIVE-NORMALIZED-SINGLE-FLOAT}%
  \index{LEAST-NEGATIVE-DOUBLE-FLOAT}%
  \index{LEAST-NEGATIVE-NORMALIZED-DOUBLE-FLOAT}%
  \index{LEAST-NEGATIVE-LONG-FLOAT}%
  \index{LEAST-NEGATIVE-NORMALIZED-LONG-FLOAT}%
  \index{LEAST-POSITIVE-SHORT-FLOAT}%
  \index{LEAST-POSITIVE-NORMALIZED-SHORT-FLOAT}%
  \index{LEAST-POSITIVE-SINGLE-FLOAT}%
  \index{LEAST-POSITIVE-NORMALIZED-SINGLE-FLOAT}%
  \index{LEAST-POSITIVE-DOUBLE-FLOAT}%
  \index{LEAST-POSITIVE-NORMALIZED-DOUBLE-FLOAT}%
  \index{LEAST-POSITIVE-LONG-FLOAT}%
  \index{LEAST-POSITIVE-NORMALIZED-LONG-FLOAT}%
  Available numbers closest to $-0$ or $+0$, respectively.
  }

  \IT{\arrGOO{\CNS{MOST-NEGATIVE}\\
      \CNS{MOST-POSITIVE}}{\}}%
    \kwd{-}%
    \xorGOO{%
      \kwd{DOUBLE-FLOAT}\\
      \kwd{LONG-FLOAT}\\
      \kwd{SHORT-FLOAT}\\
      \kwd{SINGLE-FLOAT}\\
      \kwd{FIXNUM}}{.}}
  {
  \index{MOST-NEGATIVE-DOUBLE-FLOAT}%
  \index{MOST-NEGATIVE-LONG-FLOAT}%
  \index{MOST-NEGATIVE-SHORT-FLOAT}%
  \index{MOST-NEGATIVE-SINGLE-FLOAT}%
  \index{MOST-NEGATIVE-FIXNUM}%
  \index{MOST-POSITIVE-DOUBLE-FLOAT}%
  \index{MOST-POSITIVE-LONG-FLOAT}%
  \index{MOST-POSITIVE-SHORT-FLOAT}%
  \index{MOST-POSITIVE-SINGLE-FLOAT}%
  \index{MOST-POSITIVE-FIXNUM}%
  Available numbers closest to $-\infty$ or $+\infty$, respectively.
  }

  \IT{\arrGOO{(\FU*{DECODE-FLOAT} \VAR{ n})\\
      (\FU*{INTEGER-DECODE-FLOAT} \VAR{ n})}{.}}
  {
  Return \retval{significand}, \retvalii{exponent}, and
  \retvaliii{sign} of \kwd{float} \VAR{n}.
  }

  \IT{(\FU*{SCALE-FLOAT} \VAR{n} \Op{\VAR{i}})}
  {
  With \VAR{n}'s radix $b$, return $n b^{i}$.
  }

  \IT{\arrGOO{
      (\FU*{FLOAT-RADIX} \VAR{ n})\\
      (\FU*{FLOAT-DIGITS} \VAR{ n})\\
      (\FU*{FLOAT-PRECISION} \VAR{ n})}{.}}
  {
  \retval{Radix}, \retval{number of digits} in that radix, or
  \retval{precision} in that radix, respectively, of float \VAR{n}.
  }

  \IT{(\FU*{UPGRADED-COMPLEX-PART-TYPE} \VAR{foo})}
  {\retval{Type} of
  most specialized complex number able to hold parts of type \VAR{foo}.
  }

\end{LIST}