
\documentclass[a4paper]{book}
\usepackage{amsmath,amssymb,amsthm}
\usepackage[utf8]{inputenc}
\usepackage[pdftex]{graphicx}
\usepackage{index}

\makeindex

\input commands.tex


\title{\theme\ Standard Library Reference} \author{Tommi Höynälänmaa}


\begin{document}


\frontmatter


\maketitle


%% \begin{titlepage}
%%   \title{\theme\ Standard Library Reference}
%%   \author{Tommi H\"oyn\"al\"anmaa}
%%   \maketitle
%% \end{titlepage}


Copyright \copyright\ 2012-2025 Tommi Höynälänmaa


\tableofcontents


\mainmatter


\chapter{Introduction}


Here is an overview for the modules in the \theme\ standard library:
\begin{itemize}
\item
  Module \code{core} includes basic functionality of the
  \theme\ environment and it should generally be always included by
  the user source code.
\item
  Module \code{platform-specific-impl} is a platform-dependent
  module. It implements procedure \code{raise} and
  forms \code{guard-general}, \code{guard-general-nonpure}, and
  \code{guard-general-without-result}.
\item
  Module \code{core-forms} defines some basic control structures as
  macros.
\item
  Module \code{core-forms2} defines some basic control structures that
  depend on the platform-specific features.
\item
  Module \code{list-utilities} implements basic list operations.
\item
  Module \code{string-utilities} implements basic string operations.
\item
  Module \code{basic-math} defines basic arithmetical operations for
  integer and real numbers.
\item
  Module \code{bitwise-arithmetic} implements basic bit operations.
\item
  Module \code{promise} implements promises (delayed evaluation).
\item
  Module \code{stream} implements streams.
\item
  Module \code{iterator} implements purely functional iterators.
\item
  Module \code{nonpure-iterator} implements nonpure iterators
  analogous to the pure ones.
\item
  Module \code{object-string-conversion} implements readable string
  forms of the \theme\ objects.
\item
  Module \code{bytevector} implements utilities for bytevectors.
\item
  Module \code{files} defines primitive classes for input and
  output ports and operations to open and close them.
\item
  Module \code{text-file-io} defines basic operations for text file IO.
\item
  Module \code{binary-file-io} defines basic operations for binary file IO.
\item
  Module \code{console-io} implements console input and output.
\item
  Module \code{system} implements some OS level functionality.
\item
  Module \code{rational} implements rational numbers.
\item
  Module \code{complex} implements complex numbers.
\item
  Module \code{real-math} implements operations between real and
  rational values and real scientific functions.
\item
  Module \code{math} implements the numerical tower and generic
  scientific functions. It is a frontend to other mathematical
  modules.
\item
  Module \code{extra-math} implements wrapper procedures for many
  standard C mathematical functions. Some methods using the wrappers
  are implemented, too.
\item
  Module \code{posix-math} implements wrapper procedures for some
  POSIX C mathematical functions not present in the C standard. Some
  methods using the wrappers are implemented, too.
\item
  Module \code{matrix} implements matrices.
\item
  Module \code{bvm-matrix-base} implements matrices using the bytevector
  IEEE 754 interface.
\item
  Module \code{bvm-diag-matrix} implements diagonal matrices using
  the bytevector IEEE 754 interface.
\item
  Module \code{bvm-matrices} exports both \code{bvm-matrix-base} and
  \code{bvm-diag-matrix}.
\item
  Module \code{dynamic-list} implements dynamically type checked
  lists.
\item
  Module \code{mutable-pair} implements mutable pairs.
\item
  Module \code{singleton} implements singletons.
\item
  Module \code{hash-table0} implements hash tables using the guile hash tables.
\item
  Modules \code{hash-table} and \code{hash-table-opt} implement hash
  tables from scratch. Module \code{hash-table-opt} is slightly more
  optimized.
\item
  Module \code{command-line-parser} implements a parser for command
  line arguments.
\item
  Module \code{statprof} provides an interface to the guile
  \code{statprof} profiler.
\item
  Module \code{plugins} implements dynamically loaded plugins.
\end{itemize}

Modules \code{hash-table0}, \code{extra-math}, and \code{posix-math}
work only for the target platform Guile.

When we document procedures and methods we use the notation
\newline

\shortprocdef{proc-name}{arg-type-1 ... arg-type-n}{result-type}

to indicate that method \code{method-name} takes arguments of types
\code{arg-type-i} and returns a value of type \code{result-type}.

When we document methods we use the notation
\newline

\methoddefwithvalue{method-name}{arg-type-1 %
  ... arg-type-n}{result-type}{procedure}

that the method is additionally equal to the procedure
\code{procedure}.

The notation
\newline

\abstmethoddef{method-name}{arg-type-1 ... arg-type-n}{result-type}

means that the method only raises an exception and its purpose is to
help in the static dispatch of the result type.
When we document virtual methods we use the notation
\newline

\methoddefwithincl{vgp}{arg-type-1 %
  ... arg-type-n}{result-type}{method}

to mean that the virtual generic procedure \code{vgp} includes a normal method
\code{method} with the same signature.
We write ``pure'' in
a procedure definition to indicate that the procedure is pure and
``static'' to indicate that the method is dispatched statically.


\chapter{Exceptions}
\label{ch:exceptions}


Error handling in \theme\ is based on exceptions that resemble Scheme
R7RS \cite{shinn2017} exceptions. The module \code{core} in the
standard library defines custom primitive class \code{<condition>},
which represents Scheme exceptions in the runtime target environment.
Note that the exceptions do not have to be objects of class
\code{<condition>}. Exceptions are raised with procedure \code{raise}
(or procedures using \code{raise}). Exception handlers are defined
by the following forms:
\begin{itemize}
\item \code{guard}
\item \code{guard-nonpure},
\item \code{guard-without-result}
\item \code{guard-general}
\item \code{guard-general-nonpure}
\item \code{guard-general-without-result}
\end{itemize}
See section \ref{sec:core-forms2_macros} and \ref{sec:platform_macros}
for the guard expressions and \ref{sec:core_control_simpleproc} for
raise expressions.

The \theme\ runtime environment and
standard library create runtime environment (RTE) exceptions. An RTE
exception is an object of class \code{<condition>} having
\textit{kind} and \textit{info}. \textit{Kind} is a symbol that
defines the kind of the exception. \textit{Info} is an association
list containing properties (pairs) with a key (a symbol).

When the exception info is enabled the runtime environment adds some
extra information into the exceptions it generates. When a
\theme\ program is run the flag is initially \false\ and it is set to
\true\ when the main procedure is called. The reason for this
behaviour is that the \theme\ objects in the exception info could
cause ugly output with the default Guile error handler.
When the info is disabled then exceptions raised by the
\theme\ runtime environment contain only the exception kind (a
symbol). Note that this is not true for the exceptions raised by the
Scheme code called by the runtime environment.
The exception info can be enabled with procedure
\code{enable-rte-exception-info} and disabled with procedure
\code{disable-rte-exception-info} (section
\ref{sec:core_control_simpleproc}).


A \theme\ program can be terminated with procedures \code{exit} or
\code{raw-exit} (section \ref{sec:core_control_simpleproc}). In
general, you should normally use \theme\ procedure \code{exit} unless
you exit the program in a toplevel expression in a script.


\chapter{Numerical Tower}
\label{ch:numerical-tower}


The \theme\ Standard Library implements a numerical tower similar to
Scheme. Easiest way to import it is to import module
\code{(standard-library math)}. Numerical types \builtin{<integer>}
and \builtin{<real>} are built in the \theme\ language and types
\builtin{<rational>} and \builtin{<complex>} are implemented by the
standard library.

We say that a rational number is in the \defterm{simplified form} if
its denominator is positive and the greatest common divisor between
the numerator and the denominator is 1. Additionally we require that
if the numerator is 0 the denominator is 1.

Terms \nan, inf, and -inf mean the exceptional floating point
values (not a number, positive infinity, and negative infinity)
defined by the IEEE 754 standard. If your system does not support
these the behaviour of the procedures in case they are specified to
return an exceptional value is undefined.

Numbers belonging to classes \builtin{<integer>} and \code{<rational>}
are called \defterm{exact} and numbers belonging to classes
\builtin{<real>} and \code{<complex>} \defterm{inexact}. The terms
\defterm{exact 0} and \defterm{exact 1} mean the integer and rational
values 0 and 1.

When the results of the real math functions in module \code{real-math}
are complex or not defined these procedures usually return an
exceptional value. When the optimized real functions are used (this is
on by default) the complex value is not actually computed but the
exceptional values are returned directly.

When applied to integer or real numbers the equality predicate
\code{equal?} follows the rules for Scheme predicate \code{eqv?} in
the R7RS standard \cite{shinn2017}. The equality predicate \code{=}
follows the rules for Scheme predicate \code{=} in R7RS for integer
and real numbers. Predicate \code{=} returns \true\ when its arguments
are numerically equal.


\chapter{Module \code{(standard-library core)}}


\section{Control Structures}


\subsection{Data Types}


\begin{datatype}
  \datatypename{<condition>}
  \datatypetype{\builtin{<class>}}
  \datatypedesc{The data type for Scheme conditions}
\end{datatype}


\begin{datatype}
  \datatypename{<rte-exception-kind>}
  \datatypetype{\builtin{<class>}}
  \datatypedesc{The kind of an exception.}
  \datatypedef{<symbol>}
\end{datatype}


\begin{datatype}
  \datatypename{<rte-exception-info>}
  \datatypetype{\builtin{:union}}
  \datatypedesc{Auxiliary information for an exception.}
  \datatypedef{(:alist <symbol> <object>)}
\end{datatype}


\subsection{Simple Procedures}
\label{sec:core_control_simpleproc}


\procdef{call-with-current-continuation} \\
\procdef{call/cc}


\startprocsyntax
\begin{codeblock}
  \noindent
  \slp
  \builtin{call-with-current-continuation}
  \procarg{body}
  \srp
\end{codeblock}


\typeparams{\typeparam{body-type}, \typeparam{jump-type}}


\startprocarguments
\begin{arglist}
  \argument{body}{\code{(:procedure ((:procedure (\typeparam{jump-type}) <none> pure)) %
      \typeparam{body-type} pure)}}
  {The procedure to be called}
\end{arglist}


\procresult{Either the value of the body procedure or a value passed into the jump procedure}%
{\code{(\builtin{:union} \typeparam{body-type} \typeparam{jump-type})}}


\procpurity{pure}


This procedures is a built-in
parametrized procedure that works as the corresponding procedure in Scheme. The argument
\procarg{body} is a procedure taking a single procedure argument.
If the body procedure invokes this argument the continuation is
transferred into the continuation of the
\code{call-with-current-continuation} expression.
Variable \code{call/cc} is defined as an alias to
\builtin{call-with-current-continuation}.


\procdefexcl{call-with-current-continuation-nonpure}{call-with-...-nonpure} \\
\procdef{call/cc-nonpure}


\startprocsyntax
\begin{codeblock}
  \noindent
  \slp
  \builtin{call-with-current-continuation-nonpure}
  \procarg{body}
  \srp
\end{codeblock}


\typeparams{\typeparam{body-type}, \typeparam{jump-type}}


\startprocarguments
\begin{arglist}
  \argument{body}{\code{(:procedure ((:procedure (\typeparam{jump-type}) <none> pure)) %
      \typeparam{body-type} nonpure)}}
  {The procedure to be called}
\end{arglist}


\procresult{Either the value of the body procedure or a value passed into the jump procedure}%
{\code{(\builtin{:union} \typeparam{body-type} \typeparam{jump-type})}}


\procpurity{nonpure}


This is a nonpure version of \code{call-with-current-continuation}, see the previous section.
This procedure has an alias \code{call/cc-nonpure}.


\procdefexcl{call-with-current-continuation-without-result}{call-with-...-without-result}\\
\procdef{call/cc-without-result}


\startprocsyntax
\begin{codeblock}
  \noindent
  \slp
  \builtin{call-with-current-continuation-without-result}
  \procarg{body}
  \srp
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{body}{\code{(:procedure ((:procedure () <none> pure)) %
      <none> nonpure)}}
  {The procedure to be called}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This is a version of \code{call-with-current-continuation} having no result value.
This procedure has an alias \code{call/cc-without-result}.


\procdef{exit}


\startprocsyntax
\begin{codeblock}
  (exit \procarg{exit-code})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{exit-code}{\builtin{<integer>}}%
  {The exit code passed to the operating system}
\end{arglist}


\noprocresult


\procpurity{nonpure}


Procedure \code{exit} terminates a program. The exit code given as an
argument is passed to the operating system. This procedure actually
rows an RTE exception with kind \code{exit} and property
\code{i-exit-code} containing the exit code. The \theme\ main program
exception handler terminates the program with the exit code when it
receives this exception.


\procdef{raw-exit}


\startprocsyntax
\begin{codeblock}
  (raw-exit \procarg{exit-code})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{exit-code}{\builtin{<integer>}}%
  {The exit code passed to the operating system}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure calls the Guile procedure \code{exit} in order to
terminate the program. In general, you should normally use
\theme\ procedure \code{exit} unless you exit the program in a
toplevel expression in a script.


\procdef{enable-rte-exception-info}


\startprocsyntax
\begin{codeblock}
  (enable-rte-exception-info)
\end{codeblock}


\noprocarguments


\noprocresult


\procpurity{pure}


This procedure sets the exception info flag on. See chapter
\ref{ch:exceptions}.


\procdef{disable-rte-exception-info}


\startprocsyntax
\begin{codeblock}
  (disable-rte-exception-info)
\end{codeblock}


\noprocarguments


\noprocresult


\procpurity{pure}


This procedure sets the exception info flag off. See chapter
\ref{ch:exceptions}.


\procdef{make-rte-exception}


\startprocsyntax
\begin{codeblock}
  (make-rte-exception \procarg{s-kind} \procarg{al-info})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{s-kind}{\code{<rte-exception-kind>}}{The kind of the exception}
  \argument{al-info}{\code{<rte-exception-info>}}%
           {Auxiliary information for the exception}
\end{arglist}


\procresult{An exception object}{\code{<condition>}}


\procpurity{pure}


\procdef{rte-exception?}


\startprocsyntax
\begin{codeblock}
  (rte-exception? \procarg{x})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{<object>}}{An object}
\end{arglist}


\procresult{\true\ iff the object is an RTE exception}{\builtin{<boolean>}}


\procpurity{pure}


\procdef{get-rte-exception-kind0}


\startprocsyntax
\begin{codeblock}
  (get-rte-exception-kind0 \procarg{exc})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{exc}{\code{<condition>}}{A condition object}
\end{arglist}


\procresult{The kind of the RTE exception}%
{\code{(:alt-maybe <rte-exception-kind>)}}
           

\procpurity{pure}


This procedure returns \false\ if the argument is not a RTE exception.


\procdef{get-rte-exception-kind}


\startprocsyntax
\begin{codeblock}
  (get-rte-exception-kind \procarg{exc})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{exc}{\code{<condition>}}{An RTE exception}
\end{arglist}


\precondition
The argument has to be a RTE exception.


\procresult{The kind of the RTE exception}%
{\code{<rte-exception-kind>}}
           

\procpurity{pure}


\procdef{get-rte-exception-info0}


\startprocsyntax
\begin{codeblock}
  (get-rte-exception-info0 \procarg{exc})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{exc}{\code{<condition>}}{A condition object}
\end{arglist}


\procresult{The RTE exception auxiliary info}%
{\code{(:alt-maybe <rte-exception-info>)}}
           

\procpurity{pure}


This procedure returns \false\ if the argument is not a RTE exception.


\procdef{get-rte-exception-info}


\startprocsyntax
\begin{codeblock}
  (get-rte-exception-info \procarg{exc})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{exc}{\code{<condition>}}{An RTE exception}
\end{arglist}


\precondition
The argument has to be a RTE exception.


\procresult{The RTE exception info}%
{\code{<rte-exception-info>}}
           

\procpurity{pure}


\procdef{make-simple-exception}


\startprocsyntax
\begin{codeblock}
  (make-simple-exception s-kind)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{s-kind}{\builtin{<symbol>}}%
  {The kind of the exception}
\end{arglist}


\procresult{An RTE exception object}%
{\builtin{<condition>}}


\procpurity{pure}


The result is an RTE exception object whose kind is the value of the
argument and info is \code{null}.


\procdef{raise-simple}


\startprocsyntax
\begin{codeblock}
  (raise-simple s-kind)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{s-kind}{\builtin{<symbol>}}%
  {The kind of the exception}
\end{arglist}


\noprocresult


\procpurity{pure}


This procedure raises a simple exception and the procedure
never returns. The exception is created with procedure
\code{make-simple-exception}.


\procdef{make-numerical-overflow}


\startprocsyntax
\begin{codeblock}
  (make-numerical-overflow s-procedure)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{s-procedure}{\builtin{<symbol>}}%
  {The name of the procedure from which the exception is raised}
\end{arglist}


\procresult{An RTE exception object}%
{\builtin{<condition>}}


\procpurity{pure}


The result is an RTE exception object whose kind is
\code{numerical-overflow} and the value corresponding to key
\code{s-proc-name} is the value the argument \code{s-procedure}.


\procdef{\_debug-print}


\startprocsyntax
\begin{codeblock}
  (\_debug-print x-message)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x-message}{\builtin{<object>}}%
  {The object to be printed}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure prints the argument with Scheme procedure
\code{display} and flushes the ports. This procedure may be called
body and program toplevel without prelinking any module bodies.


\procdef{raise-numerical-overflow}


\startprocsyntax
\begin{codeblock}
  (raise-numerical-overflow s-procedure)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{s-procedure}{\builtin{<symbol>}}%
  {The name of the procedure from which the exception is raised}
\end{arglist}


\noprocresult


\procpurity{pure}


This procedure raises a numerical overflow exception and the procedure
never returns.


\section{Command Line}


\subsection{Simple Procedures}


\procdef{command-line-arguments}


\startprocsyntax
\begin{codeblock}
(command-line-arguments)
\end{codeblock}


\noprocarguments


\procresult{List of command line arguments}%
{\code{(\builtin{:uniform-list} \builtin{<string>})}}


\procpurity{pure}


\section{Equality Predicates}


The main equality predicate in \theme\ is the generic procedure
\code{equal?}.


\subsection{Simple Procedures}


\procdef{boolean=?}


\startprocsyntax
\begin{codeblock}
(boolean=? object1 object2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object1}{\builtin{<boolean>}}{A boolean value to be compared}
  \argument{object2}{\builtin{<boolean>}}{A boolean value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{object1} is equal to \code{object2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{character=?}


\startprocsyntax
\begin{codeblock}
(character=? object1 object2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object1}{\builtin{<character>}}{A character to be compared}
  \argument{object2}{\builtin{<character>}}{A character to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{object1} is equal to \code{object2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{eq?}


\startprocsyntax
\begin{codeblock}
(eq? object1 object2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object1}{\builtin{<object>}}{An object to be compared}
  \argument{object2}{\builtin{<object>}}{An object to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{object1} and \code{object2} are the same object}%
{\builtin{<boolean>}}


\procpurity{pure}


This procedure calls the Scheme procedure \code{eq?}.  See references
\cite{sperber2007} and \cite{shinn2017} for more information.


\procdef{integer=?}


\startprocsyntax
\begin{codeblock}
(integer=? object1 object2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object1}{\builtin{<integer>}}{An integer value to be compared}
  \argument{object2}{\builtin{<integer>}}{An integer value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{object1} is equal to \code{object2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer=}


\startprocsyntax
\begin{codeblock}
(integer= object1 object2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object1}{\builtin{<integer>}}{An integer value to be compared}
  \argument{object2}{\builtin{<integer>}}{An integer value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{object1} is numerically equal to %
  \code{object2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer-real=}


\startprocsyntax
\begin{codeblock}
(integer-real= object1 object2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object1}{\builtin{<integer>}}{An integer value to be compared}
  \argument{object2}{\builtin{<real>}}{A real value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{object1} is numerically equal to %
  \code{object2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{keyword=?}


\startprocsyntax
\begin{codeblock}
(keyword=? object1 object2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object1}{\builtin{<keyword>}}{A keyword to be compared}
  \argument{object2}{\builtin{<keyword>}}{A keyword to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{object1} is equal to \code{object2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real=?}


\startprocsyntax
\begin{codeblock}
(real=? object1 object2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object1}{\builtin{<real>}}{A real value to be compared}
  \argument{object2}{\builtin{<real>}}{A real value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{object1} is equal to \code{object2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real=}


\startprocsyntax
\begin{codeblock}
(real= object1 object2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object1}{\builtin{<real>}}{A real value to be compared}
  \argument{object2}{\builtin{<real>}}{A real value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{object1} is numerically equal to %
  \code{object2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real-integer=}


\startprocsyntax
\begin{codeblock}
(real-integer= object1 object2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object1}{\builtin{<real>}}{A real value to be compared}
  \argument{object2}{\builtin{<integer>}}{An integer value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{object1} is numerically equal to %
  \code{object2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{string=?}


\startprocsyntax
\begin{codeblock}
(string=? object1 object2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object1}{\builtin{<string>}}{A string to be compared}
  \argument{object2}{\builtin{<string>}}{A string to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{object1} is equal to \code{object2}}%
{\builtin{<boolean>}}


\procpurity{pure}


This procedure compares the contents of the argument strings.


\procdef{symbol=?}


\startprocsyntax
\begin{codeblock}
(symbol=? object1 object2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object1}{\builtin{<symbol>}}{A symbol to be compared}
  \argument{object2}{\builtin{<symbol>}}{A symbol to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{object1} is equal to \code{object2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\subsection{Virtual Methods}

\indexmethod{equal?}

\noindent
\puremethoddefwithvalue{equal?}{<object> <object>}{<boolean>}{equal-values?}
\puremethoddefwithvalue{equal?}{<boolean> <boolean>}{<boolean>}{boolean=?}
\puremethoddefwithvalue{equal?}{<integer> <integer>}{<boolean>}{integer=?}
\puremethoddefwithvalue{equal?}{<real> <real>}{<boolean>}{real=?}
\puremethoddefwithvalue{equal?}{<symbol> <symbol>}{<boolean>}{symbol=?}
\puremethoddefwithvalue{equal?}{<string> <string>}{<boolean>}{string=?}
\puremethoddefwithvalue{equal?}{<character> <character>}{<boolean>}{character=?}
\puremethoddefwithvalue{equal?}{<keyword> <keyword>}{<boolean>}{keyword=?}
\puremethoddef{equal?}{<null> <null>}{<boolean>}

\noindent
\staticpuremethoddef{equal?}{<boolean> <object>}{<boolean>}
\staticpuremethoddef{equal?}{<object> <boolean>}{<boolean>}
\staticpuremethoddef{equal?}{<integer> <object>}{<boolean>}
\staticpuremethoddef{equal?}{<object> <integer>}{<boolean>}
\staticpuremethoddef{equal?}{<real> <object>}{<boolean>}
\staticpuremethoddef{equal?}{<object> <real>}{<boolean>}
\staticpuremethoddef{equal?}{<symbol> <object>}{<boolean>}
\staticpuremethoddef{equal?}{<object> <symbol>}{<boolean>}
\staticpuremethoddef{equal?}{<string> <object>}{<boolean>}
\staticpuremethoddef{equal?}{<object> <string>}{<boolean>}
\staticpuremethoddef{equal?}{<character> <object>}{<boolean>}
\staticpuremethoddef{equal?}{<object> <character>}{<boolean>}
\staticpuremethoddef{equal?}{<keyword> <object>}{<boolean>}
\staticpuremethoddef{equal?}{<object> <keyword>}{<boolean>}
\staticpuremethoddef{equal?}{<null> <object>}{<boolean>}
\staticpuremethoddef{equal?}{<object> <null>}{<boolean>}

\indexmethod{=}

\noindent
\puremethoddefwithvalue{=}{<integer> <integer>}{<boolean>}{integer=}
\puremethoddefwithvalue{=}{<real> <real>}{<boolean>}{real=}
\puremethoddefwithvalue{=}{<integer> <real>}{<boolean>}{integer-real=}
\puremethoddefwithvalue{=}{<real> <integer>}{<boolean>}{real-integer=}

The static \code{equal?} methods ensure that equality checks involving
primitive types are optimized to use Scheme procedures \code{eq?} and
\code{eqv?}, except \code{<string>} for which Scheme procedure
\code{equal?} is used.


\section{Class Membership Predicates}


\subsection{Data Types}


\begin{datatype}
  \datatypename{<type-predicate>}
  \datatypetype{\builtin{:procedure}}
  \datatypedesc{The data type for type membership predicates}
\end{datatype}


\subsection{Simple Procedures}


\procdef{boolean?}


\startprocsyntax
\begin{codeblock}
(boolean? object)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object}{\builtin{<object>}}{An object to be tested}
\end{arglist}


\procresult{\code{\#t} iff \code{object} is an instance of 
  \builtin{<boolean>}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{character?}


\startprocsyntax
\begin{codeblock}
(character? object)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object}{\builtin{<object>}}{An object to be tested}
\end{arglist}


\procresult{\code{\#t} iff \code{object} is an instance of 
  \builtin{<character>}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer?}


\startprocsyntax
\begin{codeblock}
(integer? object)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object}{\builtin{<object>}}{An object to be tested}
\end{arglist}


\procresult{\code{\#t} iff \code{object} is an instance of \builtin{<integer>}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{null?}


\startprocsyntax
\begin{codeblock}
(null? object)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object}{\builtin{<object>}}{An object to test}
\end{arglist}


\procresult{\code{\#t} iff \code{object} is null}%
{\code{<boolean>}}


\procpurity{pure}


\procdef{not-null?}


\startprocsyntax
\begin{codeblock}
(not-null? object)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object}{\builtin{<object>}}{An object to test}
\end{arglist}


\procresult{\code{\#t} iff \code{object} is not null}%
{\code{<boolean>}}


\procpurity{pure}


\procdef{pair?}


\startprocsyntax
\begin{codeblock}
(pair? object)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object}{\builtin{<object>}}{An object to be tested}
\end{arglist}


\procresult{\code{\#t} iff \code{object} is an instance of 
  \builtin{<pair>}}%
{\builtin{<boolean>}}


\procpurity{pure}


This procedure returns \code{\#t} for any pair.


\procdef{real?}


\startprocsyntax
\begin{codeblock}
(real? object)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object}{\builtin{<object>}}{An object to be tested}
\end{arglist}


\procresult{\code{\#t} iff \code{object} is an instance of \builtin{<real>}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{string?}


\startprocsyntax
\begin{codeblock}
(string? object)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object}{\builtin{<object>}}{An object to be tested}
\end{arglist}


\procresult{\code{\#t} iff \code{object} is an instance of \builtin{<string>}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{symbol?}


\startprocsyntax
\begin{codeblock}
(symbol? object)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object}{\builtin{<object>}}{An object to be tested}
\end{arglist}


\procresult{\code{\#t} iff \code{object} is an instance of \builtin{<symbol>}}%
{\builtin{<boolean>}}


\procpurity{pure}


\section{Lists, Tuples, and Pairs}


\subsection{Data Types}


\begin{datatype}
  \datatypename{:alist}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{2}
  \datatypedesc{An association list}
\end{datatype}


\begin{datatype}
  \datatypename{:nonempty-alist}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{2}
  \datatypedesc{An association list containing at least one element}
\end{datatype}


\begin{datatype}
  \datatypename{:maybe}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{1}
  \datatypedesc{A value that is either \builtin{null} or an instance %
    of the component type}
\end{datatype}


\begin{datatype}
  \datatypename{:alt-maybe}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{1}
  \datatypedesc{A value that is either \builtin{<boolean>} or an instance %
    of the component type. Usually the value is not allowed to be
    \code{\#t}.}
\end{datatype}


\begin{datatype}
  \datatypename{:nonempty-uniform-list}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{1}
  \datatypedesc{A uniform list with at least one element}
\end{datatype}


\begin{datatype}
  \datatypename{<list>}
  \datatypetype{\builtin{:union}}
  \datatypedesc{A list consisting of any objects}
\end{datatype}


\begin{datatype}
  \datatypename{<nonempty-list>}
  \datatypetype{\builtin{:pair}}
  \datatypedesc{A nonempty list consisting of any objects}
\end{datatype}


\begin{datatype}
  \datatypename{<pair>}
  \datatypetype{\builtin{:pair}}
  \datatypedesc{A pair consisting of any objects}
\end{datatype}


\subsection{Parametrized Procedures}


\procdef{car}


\startprocsyntax
\begin{codeblock}
  (car pair)
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{pair}{\code{(\builtin{:pair} \typeparam{type1} \typeparam{type2})}}%
  {A pair}
\end{arglist}


\procresult{The first element of the pair}%
{\code{\typeparam{type1}}}


\procpurity{pure}


\procdef{cdr}


\startprocsyntax
\begin{codeblock}
  (cdr pair)
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{pair}{\code{(\builtin{:pair} \typeparam{type1} \typeparam{type2})}}%
  {A pair}
\end{arglist}


\procresult{The second element of the pair}%
{\code{\typeparam{type2}}}


\procpurity{pure}


\procdef{gen-car}


\startprocsyntax
\begin{codeblock}
  (gen-car pair)
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{pair}{\code{(\builtin{:union} (\builtin{:pair}
      \typeparam{type1} \typeparam{type2}) \builtin{<null>})}}%
  {A pair}
\end{arglist}


\procresult{The first element of the pair}%
{\code{\typeparam{type1}}}


\procpurity{pure}


If the argument is \code{null} an exception is raised.


\procdef{gen-cdr}


\startprocsyntax
\begin{codeblock}
  (gen-cdr pair)
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{pair}{\code{(\builtin{:union} (\builtin{:pair}
      \typeparam{type1} \typeparam{type2}) \builtin{<null>})}}%
  {A pair}
\end{arglist}


\procresult{The second element of the pair}%
{\code{\typeparam{type2}}}


\procpurity{pure}


If the argument is \code{null} an exception is raised.


\procdef{cons}


\startprocsyntax
\begin{codeblock}
(cons first second)
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{first}{\code{\typeparam{type1}}}{The first object of the new pair}
  \argument{second}{\code{\typeparam{type2}}}{The second object of the new pair}
\end{arglist}


\procresult{A pair with values \code{first} and \code{second}}%
{\code{(\builtin{:pair} \typeparam{type1} \typeparam{type2})}}


\procpurity{pure}


\procdef{list}


\startprocsyntax
\begin{codeblock}
(list item-1 ... item-n)
\end{codeblock}


\typeparams{\typeparam{arglist}}


\startprocarguments
\begin{arglist}
  \indexedargument{item}{k}{\indexedsyntaxvarf{t}{k}}{A list item}
\end{arglist}


\procresult{A list constructed from the arguments}%
{\code{\typeparam{arglist}}}


\procpurity{pure}


Metavariable \indexedsyntaxvarf{t}{k} is the type of \code{item-k} for
each \(k\)..
Type variable \code{\typeparam{arglist}} is equivalent to
\code{(\builtin{\tupletype} \indexedsyntaxvarf{t}{1} %
  ... \indexedsyntaxvarf{t}{n})}.


\procdef{member?}


\startprocsyntax
\begin{codeblock}
(member? \code{object} \code{lst})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{object}{\code{\typeparam{type}}}%
  {the object to be searched}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}
  {the list to be searched}
\end{arglist}


\procresult{Result of the search}%
{\code{<boolean>}}


\procpurity{pure}


The list \code{lst} is searched for
\code{object}. If \code{object} is found return \code{\#t}. Otherwise
return \code{\#f}. The list items are compared with the equivalence
predicate \code{equal?}.


\section{Logical Operations}


\subsection{Simple Procedures}


\procdef{not}


\startprocsyntax
\begin{codeblock}
(not boolean-value)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{boolean-value}{\builtin{<boolean>}}{A boolean value}
\end{arglist}


\procresult{\code{\#t} iff the value of \code{boolean-value} is %
  \code{\#f}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{not-false?}


\startprocsyntax
\begin{codeblock}
(not-false? x)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\builtin{<boolean>}}{Any value}
\end{arglist}


\procresult{\code{\#t} iff the value of \code{boolean-value} is not %
  \code{\#f}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{not-object}


\startprocsyntax
\begin{codeblock}
(not-object obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<object>}}{Any object}
\end{arglist}


\procresult{\true\ iff \code{obj} is false, \false\ otherwise}%
{\code{<boolean>}}


\procpurity{pure}


\procdef{xor}


\startprocsyntax
\begin{codeblock}
  (xor \procarg{boolean-value1} \procarg{boolean-value2})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{boolean-value1}{\builtin{<boolean>}}{A boolean value}
  \argument{boolean-value2}{\builtin{<boolean>}}{A boolean value}
\end{arglist}


\procresult{\code{\#t} iff exactly one of the values %
  \procarg{boolean-value1} and \procarg{boolean-value2} is \code{\#t}}%
{\builtin{<boolean>}}


\procpurity{pure}


\section{Vectors}


\subsection{Parametrized Procedures}


\procdef{mutable-value-vector-length}


\startprocsyntax
\begin{codeblock}
  (mutable-value-vector-length vec)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{vec}{\code{(\builtin{:mutable-value-vector} %
      \typeparam{type})}}{A vector}
\end{arglist}


\procresult{Length of the vector \code{vec}}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{mutable-value-vector-ref}


\startprocsyntax
\begin{codeblock}
  (mutable-value-vector-ref vec index)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{vec}{\code{(\builtin{:mutable-value-vector} %
      \typeparam{type})}}{A vector}
  \argument{index}{\builtin{<integer>}}{Index to the vector}
\end{arglist}


\procresult{Element of vector \code{vec} at the position %
  \code{index}}%
{\code{\typeparam{type}}}


\procpurity{pure}


\procdefexcl{mutable-value-vector-set!}{mutable-value-vector-set{"!}}


\startprocsyntax
\begin{codeblock}
  (mutable-value-vector-set! vec index element)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{vec}{\code{(\builtin{:mutable-value-vector} \typeparam{type})}}{A vector}
  \argument{index}{\builtin{<integer>}}{Index to the vector}
  \argument{element}{\code{\typeparam{type}}}{The new value of the element}
\end{arglist}


\noprocresult


\procpurity{nonpure}


\procdef{mutable-vector-length}


\startprocsyntax
\begin{codeblock}
(mutable-vector-length vec)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{vec}{\code{(\builtin{:mutable-vector} \typeparam{type})}}{A vector}
\end{arglist}


\procresult{Length of the vector \code{vec}}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{mutable-vector-ref}


\startprocsyntax
\begin{codeblock}
(mutable-vector-ref vec index)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{vec}{\code{(\builtin{:mutable-vector} \typeparam{type})}}{A vector}
  \argument{index}{\builtin{<integer>}}{Index to the vector}
\end{arglist}


\procresult{Element of vector \code{vec} at the position %
  \code{index}}%
{\code{\typeparam{type}}}


\procpurity{pure}


\procdefexcl{mutable-vector-set!}{mutable-vector-set{"!}}


\startprocsyntax
\begin{codeblock}
(mutable-vector-set! vec index element)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{vec}{\code{(\builtin{:mutable-vector} \typeparam{type})}}{A vector}
  \argument{index}{\builtin{<integer>}}{Index to the vector}
  \argument{element}{\code{\typeparam{type}}}{The new value of the element}
\end{arglist}


\noprocresult


\procpurity{nonpure}


\procdef{value-vector-length}


\startprocsyntax
\begin{codeblock}
(value-vector-length vec)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{vec}{\code{(\builtin{:value-vector} \typeparam{type})}}{A vector}
\end{arglist}


\procresult{Length of the vector \code{vec}}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{value-vector-ref}


\startprocsyntax
\begin{codeblock}
(value-vector-ref vec index)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{vec}{\code{(\builtin{:value-vector} \typeparam{type})}}{A vector}
  \argument{index}{\builtin{<integer>}}{Index to the vector}
\end{arglist}


\procresult{Element of vector \code{vec} at the position %
  \code{index}}%
{\code{\typeparam{type}}}


\procpurity{pure}


\procdef{vector-length}


\startprocsyntax
\begin{codeblock}
(vector-length vec)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{vec}{\code{(\builtin{:vector} \typeparam{type})}}{A vector}
\end{arglist}


\procresult{Length of the vector \code{vec}}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{vector-ref}


\startprocsyntax
\begin{codeblock}
(vector-ref vec index)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{vec}{\code{(\builtin{:vector} \typeparam{type})}}{A vector}
  \argument{index}{\builtin{<integer>}}{Index to the vector}
\end{arglist}


\procresult{Element of vector \code{vec} at the position %
  \code{index}}%
{\code{\typeparam{type}}}


\procpurity{pure}


\section{Arithmetic Operations}


\subsection{Simple Procedures}


\procdef{integer+}


\startprocsyntax
\begin{codeblock}
(integer+ int1 int2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{int1}{\builtin{<integer>}}{An integer value}
  \argument{int2}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{integer-}


\startprocsyntax
\begin{codeblock}
(integer- int1 int2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{int1}{\builtin{<integer>}}{An integer value}
  \argument{int2}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{integer*}


\startprocsyntax
\begin{codeblock}
(integer* int1 int2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{int1}{\builtin{<integer>}}{An integer value}
  \argument{int2}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{integer<}


\startprocsyntax
\begin{codeblock}
(integer< int1 int2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{int1}{\builtin{<integer>}}{An integer value}
  \argument{int2}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{\code{\#t} iff \code{int1} \(<\) \code{int2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer>}


\startprocsyntax
\begin{codeblock}
(integer> int1 int2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{int1}{\builtin{<integer>}}{An integer value}
  \argument{int2}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{\code{\#t} iff \code{int1} \(>\) \code{int2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer>=}


\startprocsyntax
\begin{codeblock}
(integer>= int1 int2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{int1}{\builtin{<integer>}}{An integer value}
  \argument{int2}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{\code{\#t} iff \code{int1} \(\geq\) \code{int2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer<=}


\startprocsyntax
\begin{codeblock}
(integer<= int1 int2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{int1}{\builtin{<integer>}}{An integer value}
  \argument{int2}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{\code{\#t} iff \code{int1} \(\leq\) \code{int2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{i-neg}


\startprocsyntax
\begin{codeblock}
  (i-neg n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{n}{\builtin{<integer>}}%
  {An integer number}
\end{arglist}


\procresult{The opposite number of the argument}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{integer-real+}


\startprocsyntax
\begin{codeblock}
(integer-real+ i r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{integer-real-}


\startprocsyntax
\begin{codeblock}
(integer-real- i r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{integer-real*}


\startprocsyntax
\begin{codeblock}
(integer-real* i r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{integer-real/}


\startprocsyntax
\begin{codeblock}
(integer-real/ i r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{integer-real<}


\startprocsyntax
\begin{codeblock}
(integer-real< i r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{\code{\#t} iff \code{i} \(<\) \code{r}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer-real<=}


\startprocsyntax
\begin{codeblock}
(integer-real<= i r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{\code{\#t} iff \code{i} \(<=\) \code{r}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer-real>}


\startprocsyntax
\begin{codeblock}
(integer-real> i r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{\code{\#t} iff \code{i} \(>\) \code{r}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer-real>=}


\startprocsyntax
\begin{codeblock}
(integer-real>= i r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{\code{\#t} iff \code{i} \(>=\) \code{r}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{r-neg}


\startprocsyntax
\begin{codeblock}
  (r-neg r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The opposite number of the argument}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real+}


\startprocsyntax
\begin{codeblock}
(real+ real1 real2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{real1}{\builtin{<real>}}{A real value}
  \argument{real2}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real-}


\startprocsyntax
\begin{codeblock}
(real- real1 real2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{real1}{\builtin{<real>}}{A real value}
  \argument{real2}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real*}


\startprocsyntax
\begin{codeblock}
(real* real1 real2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{real1}{\builtin{<real>}}{A real value}
  \argument{real2}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real/}


\startprocsyntax
\begin{codeblock}
(real/ real1 real2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{real1}{\builtin{<real>}}{A real value}
  \argument{real2}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real<}


\startprocsyntax
\begin{codeblock}
(real< real1 real2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{real1}{\builtin{<real>}}{A real value}
  \argument{real2}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{\code{\#t} iff \code{real1} \(<\) \code{real2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real>}


\startprocsyntax
\begin{codeblock}
(real> real1 real2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{real1}{\builtin{<real>}}{A real value}
  \argument{real2}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{\code{\#t} iff \code{real1} \(>\) \code{real2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real<=}


\startprocsyntax
\begin{codeblock}
(real<= real1 real2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{real1}{\builtin{<real>}}{A real value}
  \argument{real2}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{\code{\#t} iff \code{real1} \(\leq\) \code{real2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real>=}


\startprocsyntax
\begin{codeblock}
(real>= real1 real2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{real1}{\builtin{<real>}}{A real value}
  \argument{real2}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{\code{\#t} iff \code{real1} \(\geq\) \code{real2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real->integer}


\startprocsyntax
\begin{codeblock}
(real->integer r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{An integer value of type \builtin{<real>}}
\end{arglist}


\procresult{The real value converted to an integer value of type \builtin{<integer>}}%
{\builtin{<integer>}}


\procpurity{pure}


If \code{r} is not an integer value (xxx.0) an exception is raised.


\procdef{real-integer+}


\startprocsyntax
\begin{codeblock}
(real-integer+ r i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{i}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real-integer-}


\startprocsyntax
\begin{codeblock}
(real-integer- r i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{i}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real-integer*}


\startprocsyntax
\begin{codeblock}
(real-integer* r i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{i}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real-integer/}


\startprocsyntax
\begin{codeblock}
(real-integer/ r i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{i}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real-integer<}


\startprocsyntax
\begin{codeblock}
(real-integer< r i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{i}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{\code{\#t} iff \code{r} \(<\) \code{i}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real-integer<=}


\startprocsyntax
\begin{codeblock}
(real-integer<= r i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{i}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{\code{\#t} iff \code{r} \(<=\) \code{i}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real-integer>}


\startprocsyntax
\begin{codeblock}
(real-integer> r i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{i}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{\code{\#t} iff \code{r} \(>\) \code{i}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real-integer>=}


\startprocsyntax
\begin{codeblock}
(real-integer>= r i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{i}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{\code{\#t} iff \code{r} \(>=\) \code{i}}%
{\builtin{<boolean>}}


\procpurity{pure}


\subsection{Virtual Methods}

\indexmethod{+}

\noindent
\puremethoddefwithvalue{+}{<integer> <integer>}{<integer>}{integer+}
\puremethoddefwithvalue{+}{<integer> <real>}{<real>}{integer-real+}
\puremethoddefwithvalue{+}{<real> <integer>}{<real>}{real-integer+}
\puremethoddefwithvalue{+}{<real> <real>}{<real>}{real+}

\indexmethod{-}

\noindent
\puremethoddefwithvalue{-}{<integer> <integer>}{<integer>}{integer-}
\puremethoddefwithvalue{-}{<integer> <real>}{<real>}{integer-real-}
\puremethoddefwithvalue{-}{<real> <integer>}{<real>}{real-integer-}
\puremethoddefwithvalue{-}{<real> <real>}{<real>}{real-}

\indexmethod{*}

\noindent
\puremethoddefwithvalue{*}{<integer> <integer>}{<integer>}{integer*}
\puremethoddefwithvalue{*}{<integer> <real>}{<real>}{integer-real*}
\puremethoddefwithvalue{*}{<real> <integer>}{<real>}{real-integer*}
\puremethoddefwithvalue{*}{<real> <real>}{<real>}{real*}

\indexmethod{/}

\noindent
\puremethoddefwithvalue{/}{<integer> <real>}{<real>}{integer-real/}
\puremethoddefwithvalue{/}{<real> <integer>}{<real>}{real-integer/}
\puremethoddefwithvalue{/}{<real> <real>}{<real>}{real/}

Note that division \code{/} between two integers is not defined in the
core module as its result is a rational number.

\indexmethod{<}

\noindent
\puremethoddefwithvalue{<}{<integer> <integer>}{<boolean>}{integer<}
\puremethoddefwithvalue{<}{<integer> <real>}{<boolean>}{integer-real<}
\puremethoddefwithvalue{<}{<real> <integer>}{<boolean>}{real-integer<}
\puremethoddefwithvalue{<}{<real> <real>}{<boolean>}{real<}

\indexmethod{<=}

\noindent
\puremethoddefwithvalue{<=}{<integer> <integer>}{<boolean>}{integer<=}
\puremethoddefwithvalue{<=}{<integer> <real>}{<boolean>}{integer-real<=}
\puremethoddefwithvalue{<=}{<real> <integer>}{<boolean>}{real-integer<=}
\puremethoddefwithvalue{<=}{<real> <real>}{<boolean>}{real<=}

\indexmethod{>}

\noindent
\puremethoddefwithvalue{>}{<integer> <integer>}{<boolean>}{integer>}
\puremethoddefwithvalue{>}{<integer> <real>}{<boolean>}{integer-real>}
\puremethoddefwithvalue{>}{<real> <integer>}{<boolean>}{real-integer>}
\puremethoddefwithvalue{>}{<real> <real>}{<boolean>}{real>}

\indexmethod{>=}

\noindent
\puremethoddefwithvalue{>=}{<integer> <integer>}{<boolean>}{integer>=}
\puremethoddefwithvalue{>=}{<integer> <real>}{<boolean>}{integer-real>=}
\puremethoddefwithvalue{>=}{<real> <integer>}{<boolean>}{real-integer>=}
\puremethoddefwithvalue{>=}{<real> <real>}{<boolean>}{real>=}

\indexmethod{-}

\noindent
\puremethoddefwithvalue{-}{<integer>}{<integer>}{i-neg}
\puremethoddefwithvalue{-}{<real>}{<real>}{r-neg}


\section{Other}
\label{sec:core-other}


\subsection{Data Types}


\begin{datatype}
  \datatypename{:unary-predicate}
  \datatypetype{parametrized procedure class}
  \datatypedesc{Unary predicate}
\end{datatype}


\begin{datatype}
  \datatypename{:binary-predicate}
  \datatypetype{parametrized procedure class}
  \datatypedesc{Binary predicate}
\end{datatype}


\subsection{Simple Procedures}


\procdef{keyword->symbol}


\startprocsyntax
\begin{codeblock}
(keyword->symbol kw)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{kw}{\builtin{<keyword>}}{A keyword}
\end{arglist}


\procresult{The symbol corresponding to the keyword}%
{\builtin{<symbol>}}


\procpurity{pure}

Note that the returned symbol does not contain the prefix \#:.


\procdef{symbol->keyword}


\startprocsyntax
\begin{codeblock}
(symbol->keyword s)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{s}{\builtin{<symbol>}}{A symbol}
\end{arglist}


\procresult{The keyword corresponding to the symbol}%
{\builtin{<keyword>}}


\procpurity{pure}

Note that the prefix \#: is appended to the result.


\subsection{Parametrized Procedures}


\procdef{identity}


\startprocsyntax
\begin{codeblock}
(identity \code{x})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{\typeparam{type}}}%
  {an object}
\end{arglist}


\procresult{The argument object}%
{\code{\typeparam{type}}}


\procpurity{pure}


\chapter{Module \code{(standard-library platform-specific-impl)}}


\section{Simple Procedures}


\procdef{raise}


\startprocsyntax
\begin{codeblock}
  (raise \procarg{exception-object})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{exception-object}{\builtin{<object>}}%
  {The exception object to be raised}
\end{arglist}


\noprocresult


\procpurity{pure}


Procedure \code{raise} raises an exception. Exceptions can be caught
with \keyword{guard-general} and \keyword{guard} forms, see the
language manual and section \ref{subsec:guard} in this guide.
The semantics of \keyword{guard} and \code{raise} are similar to their
semantics in Scheme.


\procdef{object-address}


\startprocsyntax
\begin{codeblock}
(object-address object)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{object}{\builtin{<object>}}{An object}
\end{arglist}


\procresult{The memory address of the argument object}%
{\builtin{<integer>}}


\procpurity{pure}


\section{Macros}
\label{sec:platform_macros}


\macrodef{guard-general}
\label{subsec:guard-general}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{guard-general} \syntaxvar{variable-name}
  \syntaxvar{exception-handler} \syntaxvar{body}
  \srp \\
  \\
  \syntaxvar{variable-name} \syntaxdefequal \syntaxelement{identifier}
\end{syntaxblock}


Form \keyword{guard-general} evaluates the expression
\syntaxvarf{body}.  If an exception is raised the variable
\syntaxvarf{variable-name} is bound to the exception object and
expression \syntaxvarf{exception-handler} is evaluated and its value
is the value of the \keyword{guard-general} expression. If no
exception is raised during the evaluation of the body its value is
returned as the value of the \keyword{guard-general} expression.  Note
that the exception handler may itself raise exceptions in which case
the surrounding exception handler evaluates them.
Both the exception handler and body must be pure expressions.
Their types may not be \code{<none>}. The exception handler must never
return.


\macrodef{guard-general-nonpure}
\label{subsec:guard-general-nonpure}


This from is like \code{guard-general} except that the body and
exception handler may be nonpure.


\macrodef{guard-general-without-result}
\label{subsec:guard-general-without-result}


This from is like \code{guard-general} except that the result type of
the body and exception handler may be \code{<none>} and the type of
the form is \code{<none>}, too.


\chapter{Module \code{(standard-library core-forms)}}


\section{Macros}
\label{sec:core-forms_macros}


\macrodef{with-syntax}

See \cite{sperber2007}.


\macrodef{syntax-rules}

See \cite{sperber2007}.


\macrodef{identifier-syntax}

See \cite{sperber2007}.


\macrodef{quasiquote}

See \cite{sperber2007}.


\macrodef{quasisyntax}

See \cite{sperber2007}.


\macrodef{apply}


\startmacrosyntax
\begin{syntaxblock}
    \slp
    \skeyword{apply}
    \syntaxvar{proc} \syntaxvar{arglist}
    \srp \\
    \slp
    \skeyword{apply}
    \syntaxvar{proc}
    \indexedsyntaxvar{arg}{1} ... \indexedsyntaxvar{arg}{n}
    \syntaxvar{arglist}
    \srp \\
    \syntaxvar{proc} \syntaxdefequal \syntaxelement{expression} \\
    \syntaxvar{arglist} \syntaxdefequal \syntaxelement{expression} \\
    \indexedsyntaxvar{arg}{k} \syntaxdefequal \syntaxelement{expression}
\end{syntaxblock}


The semantics of this form is similar to procedure apply in Scheme
\cite{sperber2007}.
In the first form, procedure \syntaxvarf{proc} is called with arguments from
\syntaxvarf{arglist}. In the second form, procedure \syntaxvarf{proc} is called
with argument list obtained by concatenating list (\indexedsyntaxvarf{arg}{1} ...
\indexedsyntaxvarf{arg}{n}) and \syntaxvarf{arglist}, although the actual
argument list computation is not done this way. Procedure \syntaxvarf{proc} has
to be a pure procedure.


\macrodef{apply-nonpure}


\startmacrosyntax
\begin{syntaxblock}
    \slp
    \skeyword{apply-nonpure}
    \syntaxvar{proc} \syntaxvar{arglist}
    \srp \\
    \slp
    \skeyword{apply-nonpure}
    \syntaxvar{proc}
    \indexedsyntaxvar{arg}{1} ... \indexedsyntaxvar{arg}{n}
    \syntaxvar{arglist}
    \srp \\
    \syntaxvar{proc} \syntaxdefequal \syntaxelement{expression} \\
    \syntaxvar{arglist} \syntaxdefequal \syntaxelement{expression} \\
    \indexedsyntaxvar{arg}{k} \syntaxdefequal \syntaxelement{expression}
\end{syntaxblock}


This form is similar to \skeyword{apply} except the argument procedure does not
have to be pure.


\macrodef{cond}
\label{subsec:cond}


\startmacrosyntax
\begin{syntaxblock}
  \slp
  \skeyword{cond} \syntaxopt{\syntaxvar{clause-list}}
  \syntaxopt{\syntaxvar{else-clause}}
  \srp \\
  \\
  \syntaxvar{clause-list} \syntaxdefequal
  \indexedsyntaxvar{clause}{1},
  \sldots,
  \indexedsyntaxvar{clause}{n} \\
  \indexedsyntaxvar{clause}{k} \syntaxdefequal \slp \indexedsyntaxvar{condition}{k}
  \indexedsyntaxvar{expr}{k,1}, \sldots, \indexedsyntaxvar{expr}{k,m(k)} \srp \\
  \syntaxvar{else-clause} \syntaxdefequal \slp \skeyword{else}
  \indexedsyntaxvar{else-expr}{1}, \sldots,
  \indexedsyntaxvar{else-expr}{p} \srp
\end{syntaxblock}


Each condition must have type \builtin{<boolean>}.
The type of each \indexedsyntaxvarf{clause}{k} is the type of
\indexedsyntaxvarf{expr}{k,m(k)} (the last expression in the clause).
If \syntaxvarf{else-clause} is present its type is the type of
\indexedsyntaxvarf{else-expr}{p} (the last expression in the else clause).
If \syntaxvarf{else-expression} is defined the type of the
\keyword{cond} expression is the union of the types of each clause and
the type of the \syntaxvarf{else-clause}. Otherwise the type of the
\keyword{cond} expression is \builtin{<none>}.

Each \indexedsyntaxvarf{condition}{k} is evaluated in order until some of them
returns \code{\#t}. When some \indexedsyntaxvarf{condition}{k} returns
\code{\#t} the expressions \indexedsyntaxvarf{expr}{k,1}, ...,
\indexedsyntaxvarf{expr}{k,m(k)} are evaluated in order. If the result type of the
\keyword{cond} expression is not \builtin{<none>} the value of the
last expression \indexedsyntaxvarf{expr}{k,m(k)} is returned as the value of the
\keyword{cond} expression. If none of the conditions return \code{\#t}
and \syntaxvarf{else-clause} is present the expressions
\indexedsyntaxvarf{else-expr}{1}, ...,
\indexedsyntaxvarf{else-expr}{p} are evaluated in
order. If the result type of the
\keyword{cond} expression is not \builtin{<none>} the value of the
last expression \indexedsyntaxvarf{else-expr}{p} is returned as the value of the
\keyword{cond} expression.


\macrodef{and}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{and} \indexedsyntaxvar{arg}{1} \sldots
  \indexedsyntaxvar{arg}{n} \srp
\end{syntaxblock}


The type of each \indexedsyntaxvarf{arg}{k} has to be
\builtin{<boolean>}.
The arguments are evaluated in order until some of the arguments
returns \code{\#f}. If all of the arguments return \code{\#t} the
result of the \keyword{and} expression is \code{\#t}. Otherwise the
result value is \code{\#f}. Note that all of the arguments are not
necessarily evaluated at all.


\macrodef{or}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{or} \indexedsyntaxvar{arg}{1} \sldots
  \indexedsyntaxvar{arg}{n} \srp
\end{syntaxblock}


The type of each \indexedsyntaxvarf{arg}{k} has to be
\builtin{<boolean>}.
The arguments are evaluated in order until some of the arguments
returns \code{\#t}. If all of the arguments return \code{\#f} the
result of the \keyword{or} expression is \code{\#f}. Otherwise the
result value is \code{\#t}. Note that all of the arguments are not
necessarily evaluated at all.


\macrodef{cond-object}
\label{subsec:cond-object}


\startmacrosyntax
\begin{syntaxblock}
  \slp
  \skeyword{cond-object} \syntaxopt{\syntaxvar{clause-list}}
  \syntaxopt{\syntaxvar{else-clause}}
  \srp \\
  \\
  \syntaxvar{clause-list} \syntaxdefequal
  \indexedsyntaxvar{clause}{1},
  \sldots,
  \indexedsyntaxvar{clause}{n} \\
  \indexedsyntaxvar{clause}{k} \syntaxdefequal \slp \indexedsyntaxvar{condition}{k}
  \indexedsyntaxvar{expr}{k,1}, \sldots,
  \indexedsyntaxvar{expr}{k,m(k)} \srp
  \syntaxor
  \slp \indexedsyntaxvar{condition}{k} \condarrow
  \indexedsyntaxvar{handler}{k} \srp
  \\
  \syntaxvar{else-clause} \syntaxdefequal \slp \skeyword{else}
  \indexedsyntaxvar{else-expr}{1}, \sldots,
  \indexedsyntaxvar{else-expr}{p} \srp
\end{syntaxblock}


This form works as \skeyword{cond} except all nonfalse values are
implemented as true in the conditions.
When a clause is of type \syntaxformulacmd{
  \slp \indexedsyntaxvar{condition}{k} \condarrow
  \indexedsyntaxvar{handler}{k} \srp}
expression \indexedsyntaxvarf{handler}{k} has to be a procedure
accepting a single argument. When this kind of clause is encountered
the \indexedsyntaxvarf{condition}{k} is evaluated and if its result is
not false it is passed to the procedure \indexedsyntaxvarf{handler}{k}
whose result is returned.


\macrodef{and-object}
\label{subsec:and-object}


\startmacrosyntax
\begin{syntaxblock}
  \slp
  \skeyword{and-object}
  \syntaxvar{expression} ...
  \srp
\end{syntaxblock}


Start evaluating the argument expressions from the left. If any
argument returns \false\ stop the evaluation and return
\false. Otherwise return the value of the last expression.


\macrodef{or-object}
\label{subsec:or-object}


\startmacrosyntax
\begin{syntaxblock}
  \slp
  \skeyword{or-object}
  \syntaxvar{expression} ...
  \srp
\end{syntaxblock}


Start evaluating the argument expressions from the left. If any
argument returns a nonfalse value stop the evaluation and return
this value. Otherwise return \false.


\macrodef{let*}

\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{let*}
  \syntaxspace \slp \indexedsyntaxvar{var-spec}{1} ... \indexedsyntaxvar{var-spec}{n}
  \srp
  \syntaxspace \syntaxvar{let-body-expressions} \srp \\
  \\
  \indexedsyntaxvar{var-spec}{k} \syntaxdefequal \slp
  \indexedsyntaxvar{var-name}{k}
  \syntaxopt{\indexedsyntaxvar{var-type}{k}} \indexedobjectvar{value}{k}
  \srp \\
  \indexedsyntaxvar{var-name}{k} \syntaxdefequal
  \syntaxelement{identifier} \\
  \syntaxvar{let-body-expressions} \syntaxdefequal
  \syntaxelement{expression} \sldots
\end{syntaxblock}


The \keyword{let*} form is similar to \keyword{let} except that the
expressions \indexedobjectvarf{value}{k} are evaluated in order and
each expression may use the variables defined before it.


\macrodef{let*-mutable}

\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{let*-mutable}
  \syntaxspace  \slp \indexedsyntaxvar{var-spec}{1} \sldots
  \indexedsyntaxvar{var-spec}{n} \srp
  \syntaxspace  \syntaxvar{let-body-expressions} \srp \\
  \\
  \indexedsyntaxvar{var-spec}{k} \syntaxdefequal \slp
  \indexedsyntaxvar{var-name}{k}
  \indexedsyntaxvar{var-type}{k} \indexedobjectvar{value}{k}) \\
  \indexedsyntaxvar{var-name}{k} \syntaxdefequal \syntaxelement{identifier} \\
  \syntaxvar{let-body-expressions} \syntaxdefequal
  \syntaxelement{expression} \sldots
\end{syntaxblock}


The \keyword{let*-mutable} form is similar to \keyword{let-mutable}
except that the expressions \indexedobjectvarf{value}{k} are evaluated
in order and each expression may use the variables defined before it.


\macrodef{let*-volatile}

\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{let*-volatile}
  \syntaxspace  \slp \indexedsyntaxvar{var-spec}{1} \sldots
  \indexedsyntaxvar{var-spec}{n} \srp
  \syntaxspace  \syntaxvar{let-body-expressions} \srp \\
  \\
  \indexedsyntaxvar{var-spec}{k} \syntaxdefequal \slp
  \indexedsyntaxvar{var-name}{k}
  \indexedsyntaxvar{var-type}{k} \indexedobjectvar{value}{k}) \\
  \indexedsyntaxvar{var-name}{k} \syntaxdefequal \syntaxelement{identifier} \\
  \syntaxvar{let-body-expressions} \syntaxdefequal
  \syntaxelement{expression} \sldots
\end{syntaxblock}


The \keyword{let*-volatile} form is similar to \keyword{let-volatile}
except that the expressions \indexedobjectvarf{value}{k} are evaluated
in order and each expression may use the variables defined before it.


\macrodef{case}
%%\subsubsection{\keyword{case}}
%%\label{subsec:case}


\startmacrosyntax
\begin{syntaxblock}
  \slp
  \skeyword{case} \syntaxvar{value}
  \syntaxopt{\syntaxvar{clause-list}}
  \syntaxopt{\syntaxvar{else-clause}}
  \srp \\
  \\
  \syntaxvar{clause-list} \syntaxdefequal
  \indexedsyntaxvar{clause}{1},
  \sldots,
  \indexedsyntaxvar{clause}{n} \\
  \indexedsyntaxvar{clause}{k} \syntaxdefequal \slp
  \slp \indexedsyntaxvar{key}{k,1} \sldots \indexedsyntaxvar{key}{k,p(k)} \srp
  \; \indexedsyntaxvar{expr}{k,1}, \sldots,
  \indexedsyntaxvar{expr}{k,m(k)}
  \srp \\
  \syntaxvar{else-clause} \syntaxdefequal \slp \skeyword{else}
  \indexedsyntaxvar{else-expr}{1}, \sldots,
  \indexedsyntaxvar{else-expr}{q} \srp
\end{syntaxblock}


The clauses are processed in order. If \syntaxvar{value} is equal to
some of the keys for clause \(k\) in the sense of the equality
predicate \code{equal?} processing the clauses is stopped and
expressions \indexedsyntaxvar{expr}{k,j} are evaluated in order and the
value of the last of these expressions is returned as the value of the
\code{case} expression.
If none of the clauses match and the else clause is present the
expressions \indexedsyntaxvar{else-expr}{j} are evaluated in order and
the value of the last of these expressions is returned.
If none of the clauses match and the else clause is not present the
\code{case} expression returns nothing.


\macrodef{do}

\startmacrosyntax
\begin{syntaxblock}
  \slp \keyword{do}
  \slp \indexedsyntaxvar{var-spec}{1} ... \indexedsyntaxvar{var-spec}{n}
  \srp \\
  \noindent \mbox{ } \hspace{0.5cm}
  \slp \syntaxvar{condition}
  \syntaxopt{\syntaxvar{result-expression}} \srp \\
  \noindent \mbox{ } \hspace{0.5cm}
  \indexedsyntaxvar{body-expression}{1} \sldots
  \indexedsyntaxvar{body-expression}{n} \srp \\
  \\
  \indexedsyntaxvar{var-spec}{k} \syntaxdefequal \slp
  \indexedsyntaxvar{var-name}{k}
  \indexedsyntaxvar{var-type}{k}
  \indexedobjectvar{init-value}{k}
  \indexedobjectvar{update-expr}{k} \srp \\
  \indexedsyntaxvar{var-name}{k} \syntaxdefequal \syntaxelement{identifier} \\
\end{syntaxblock}


The type of \syntaxvarf{condition} has to be \builtin{<boolean>}. At the
beginning of each iteration \syntaxvarf{condition} is evaluated. If it
returns \code{\#t} the iteration is stopped and the value of
\syntaxvarf{result-expression} is returned as the result of the
\keyword{do} expression. Otherwise the body expressions are
evaluated in order, variables \indexedsyntaxvarf{var-name}{k} are
assigned new values obtained by evaluating each
\indexedsyntaxvarf{update-expr}{k} in order, and the next iteration is
started from the beginning. If \syntaxvar{result-type} is not
specified the type of the
\keyword{do} expression is \builtin{<none>}.
Expression
\begin{syntaxblock}
  \slp \keyword{do}
  \slp
  \slp \indexedsyntaxvar{var-name}{1}
  \indexedsyntaxvar{var-type}{1}
  \indexedobjectvar{init-value}{1}
  \indexedobjectvar{update-expr}{1} \srp
  \sldots \\
  \noindent \mbox{ } \hspace{0.7cm}
  \slp \indexedsyntaxvar{var-name}{m}
  \indexedsyntaxvar{var-type}{m}
  \indexedobjectvar{init-value}{m}
  \indexedobjectvar{update-expr}{m} \srp
  \srp \\
  \noindent \mbox{ } \hspace{0.5cm}
  \slp \syntaxvar{condition}
  \syntaxopt{\syntaxvar{result-expression}} \srp \\
  \noindent \mbox{ } \hspace{0.5cm}
  \indexedsyntaxvar{body-expression}{1} \sldots
  \indexedsyntaxvar{body-expression}{n} \srp
\end{syntaxblock}
is equivalent to
\begin{syntaxblock}
  \slp \keyword{let-mutable}
  \slp
  \slp \indexedsyntaxvar{var-name}{1}
  \indexedsyntaxvar{var-type}{1}
  \indexedobjectvar{init-value}{1}
  \srp
  \sldots \\
  \noindent \mbox{ } \hspace{2.2cm}
  \slp \indexedsyntaxvar{var-name}{m}
  \indexedsyntaxvar{var-type}{m}
  \indexedobjectvar{init-value}{m}
  \srp
  \srp \\
  \noindent \mbox{ } \hspace{0.5cm}
  \slp \keyword{until}
  \slp \syntaxvar{condition}
  \syntaxopt{\syntaxvar{result-expression}} \srp \\
  \noindent \mbox{ } \hspace{1.0cm}
  \indexedsyntaxvar{body-expression}{1} \sldots \\
  \noindent \mbox{ } \hspace{1.0cm}
  \indexedsyntaxvar{body-expression}{n} \\
  \noindent \mbox{ } \hspace{1.0cm}
  \slp \keyword{set!} \indexedsyntaxvar{var-name}{1}
  \indexedsyntaxvar{update-expr}{1} \srp \sldots \\
  \noindent \mbox{ } \hspace{1.0cm}
  \slp \keyword{set!} \indexedsyntaxvar{var-name}{m}
  \indexedsyntaxvar{update-expr}{m} \srp
  \srp \srp
\end{syntaxblock}


\macrodef{receive}


\startmacrosyntax
\begin{syntaxblock}
  \slp \keyword{receive}
  \slp \indexedsyntaxvar{var}{1} ... \indexedsyntaxvar{var}{n}
  \srp
  \; \syntaxvar{source-expr}
  \syntaxvar{body-expr}
  \srp
\end{syntaxblock}


Expression \syntaxvarf{source-expr} has to return a tuple value with
\(n\) components. The expression \syntaxvarf{source-expr} is evaluated
and variables \indexedsyntaxvar{var}{k} are bound to the components of
the return value. Then expression \syntaxvarf{body-expr} is evaluated
and its value is returned as the value of the \macro{receive}
expression.


\macrodef{fluid-let}


\startmacrosyntax
\begin{syntaxblock}
  \slp \keyword{fluid-let}
  \syntaxspace \slp \indexedsyntaxvar{var-spec}{1} ... \indexedsyntaxvar{var-spec}{m}
  \srp
  \syntaxspace \indexedsyntaxvar{body-expr}{1} ...
  \indexedsyntaxvar{body-expr}{n} 
  \srp \\
  \\
  \indexedsyntaxvar{var-spec}{k} \syntaxdefequal \slp
  \indexedsyntaxvar{var-name}{k}
  \indexedobjectvar{value}{k}
  \srp \\
  \indexedsyntaxvar{var-name}{k} \syntaxdefequal
  \syntaxelement{identifier}
\end{syntaxblock}


Variables \indexedsyntaxvarf{var-name}{k} have to be defined in the
environment of the \keyword{fluid-let} expression. First the values of
the component variables are saved. Then each variable
\indexedsyntaxvarf{var-name}{k} is assigned the value of expression
\indexedsyntaxvarf{value}{k}. Expressions
\indexedsyntaxvarf{body-expr}{k} are evaluated and the values of the
variables are restored from the saved values. The result of the last
body expression is returned as the result of the \macro{fluid-let}
expression.


\macrodef{unwind-protect-local}


\startmacrosyntax
\begin{syntaxblock}
  \slp \keyword{unwind-protect-local} \syntaxvar{expr} \syntaxvar{protect} \srp
\end{syntaxblock}


First \syntaxvarf{expr} is evaluated, then \syntaxvarf{protect} is evaluated and
the value of \syntaxvarf{expr} is returned as the value of the
\code{unwind-protect-local} expression. Note that \syntaxvarf{protect} is not
evaluated if \syntaxvarf{expr} is exited nonlocally.


\vspace{1cm}
\macrodefa{\$let*}
\macrodefa{\$letrec}
\macrodefa{\$letrec*}

\startmacrosyntax
\begin{syntaxblock}
  \slp \mlp \skeyword{\$let*} \syntaxor \skeyword{\$letrec}
  \syntaxor \skeyword{\$letrec*} \mrp
  \syntaxspace \slp \indexedsyntaxvar{var-spec}{1} ... \indexedsyntaxvar{var-spec}{n}
  \srp
  \syntaxspace \syntaxvar{let-body-expressions} \srp \\
  \\
  \indexedsyntaxvar{var-spec}{k} \syntaxdefequal \slp
  \indexedsyntaxvar{var-name}{k}
  \indexedobjectvar{value}{k}
  \srp \\
  \indexedsyntaxvar{var-name}{k} \syntaxdefequal
  \syntaxelement{identifier} \\
  \syntaxvar{let-body-expressions} \syntaxdefequal
  \syntaxelement{expression} \sldots
\end{syntaxblock}


These forms work like the corresponding Scheme forms without the
leading '\$', see \cite{shinn2017}. These forms may only be used in
macro transformers.


\macrodef{\$and}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{\$and} \syntaxvar{expression} \sldots \srp
\end{syntaxblock}


This form works like \theme\ \keyword{and-object} and Scheme form
\keyword{and}. This form may only be used in macro transformers.


\macrodef{\$or}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{\$or} \syntaxvar{expression} \sldots \srp
\end{syntaxblock}


This form works like \theme\ \keyword{or-object} and Scheme form
\keyword{or}. This form may only be used in macro transformers.


\macrodef{create}


\startmacrosyntax
\begin{syntaxblock}
  \slp \keyword{create} \syntaxvar{class}
  \indexedsyntaxvar{field-value}{1}
  \sldots \indexedsyntaxvar{field-value}{n} \srp
\end{syntaxblock}


Keyword \keyword{create} creates an instance of \syntaxvarf{class} calling
the constructor of \syntaxvarf{class} and passing the arguments
\indexedsyntaxvarf{field-value}{k}. Expression \syntaxvarf{class} has to be a
static type expression and its value has to be a class.


\macrodef{define-normal-goops-class}
\label{subsec:define-normal-goops-class}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{define-normal-goops-class} 
  \syntaxvar{name}
  \syntaxvar{target-name}
  \syntaxvar{superclass}
  \syntaxvar{inheritable?}
  \syntaxvar{immutable?}
  \syntaxvar{equal-by-value?}
  \srp
  \\
  \syntaxvar{name} \syntaxdefequal \syntaxelement{identifier} \\
  \syntaxvar{target-name} \syntaxdefequal \syntaxelement{identifier} \\
  \syntaxvar{inheritable?} \syntaxdefequal \syntaxelement{boolean} \\
  \syntaxvar{immutable?} \syntaxdefequal \syntaxelement{boolean} \\
  \syntaxvar{equal-by-value?} \syntaxdefequal \syntaxelement{boolean}
\end{syntaxblock}


This is a more compact syntax to define GOOPS classes.


\macrodef{define-param-method}
\label{subsec:expr-define-param-method}

\macrodef{define-param-virtual-method}
\label{subsec:expr-define-param-virtual-method}

\macrodef{define-static-param-virtual-method}
\label{subsec:expr-define-static-param-virtual-method}


\startmacrosyntax
\begin{syntaxblock}
  \slp \syntaxvar{keyword} \syntaxvar{method-name}
  \slp \indexedsyntaxvar{type}{1} ... \indexedsyntaxvar{type}{n} \srp
  \slp
  \syntaxvar{argument-list}
  \syntaxvar{result-type}
  \syntaxvar{attribute-list} \srp
  \syntaxspace \indexedsyntaxvar{body-expr}{1}, \sldots,
  \indexedsyntaxvar{body-expr}{n} \srp \\
  \\
  \syntaxvar{keyword} \syntaxdefequal
  \skeyword{define-param-method} \syntaxor
  \skeyword{define-param-virtual-method} \syntaxor
  \skeyword{define-static-param-virtual-method} \\
  \syntaxvar{method-name} \syntaxdefequal
  \syntaxelement{identifier} \\
  \syntaxvar{argument-list} \syntaxdefequal \slp
  \syntaxopt{\indexedsyntaxvar{arg}{1} \sldots
    \indexedsyntaxvar{arg}{n}} \srp \\
  \indexedsyntaxvar{arg}{k} \syntaxdefequal (\indexedsyntaxvar{arg-name}{k}
  \indexedsyntaxvar{arg-type}{k}) \\
  \indexedsyntaxvar{arg-name}{k} \syntaxdefequal
  \syntaxelement{identifier} \\
  \attrlistdef
\end{syntaxblock}


Keyword \keyword{define-param-method} defines a normal
parametrized method.
Keyword \keyword{define-param-virtual-method} defines a virtual
dynamic parametrized method.
Keyword \keyword{define-static-param-virtual-method} defines a virtual
static parametrized method.
Note that
the argument list may be \code{()}.
Expressions \indexedsyntaxvarf{arg-type}{k} and
\syntaxvarf{result-type} have to be static type expressions.
It is an error if the result type is not \builtin{<none>} and
the type of the last body expression is not a subtype of
\syntaxvarf{result-type}. If \syntaxvarf{result-type} is not
\builtin{<none>} the result value of the procedure is the value of the
last body expression.


\macrodef{define-param-proc}
\label{subsec:expr-define-param-proc}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{define-param-proc} \syntaxvar{procedure-name}
  \slp \indexedsyntaxvar{type}{1} ... \indexedsyntaxvar{type}{n} \srp
  \syntaxspace
  \slp
  \syntaxvar{argument-list}
  \syntaxvar{result-type}
  \syntaxvar{attribute-list} \srp
  \syntaxspace \indexedsyntaxvar{body-expr}{1}, \sldots,
  \indexedsyntaxvar{body-expr}{n} \srp \\
  \\
  \syntaxvar{procedure-name} \syntaxdefequal
  \syntaxelement{identifier} \\
  \indexedsyntaxvar{type}{k} \syntaxdefequal
  \syntaxelement{identifier} \\
  \syntaxvar{argument-list} \syntaxdefequal \slp
  \syntaxopt{\indexedsyntaxvar{arg}{1} \sldots
    \indexedsyntaxvar{arg}{n}} \srp \\
  \indexedsyntaxvar{arg}{k} \syntaxdefequal (\indexedsyntaxvar{arg-name}{k}
  \indexedsyntaxvar{arg-type}{k}) \\
  \indexedsyntaxvar{arg-name}{k} \syntaxdefequal \syntaxelement{identifier} \\
  \attrlistdef
\end{syntaxblock}


Keyword \keyword{define-param-proc} defines constant
\syntaxvarf{procedure-name} with a parametrized procedure value.
Note that
the argument list may be \code{()}.
Expressions \indexedsyntaxvarf{arg-type}{k} and
\syntaxvarf{result-type} have to be static type expressions.
It is an error if the type of the last body expression is not a
subtype of \syntaxvarf{result-type}. If \syntaxvarf{result-type} is not
\builtin{<none>} the result value of the procedure is the value of the
last body expression.


\macrodef{define-simple-method}
\label{subsec:expr-define-simple-method}

\macrodef{define-simple-virtual-method}
\label{subsec:expr-define-simple-virtual-method}

\macrodef{define-static-simple-virtual-method}
\label{subsec:expr-define-static-simple-virtual-method}


\startmacrosyntax
\begin{syntaxblock}
  \slp \syntaxvar{keyword} \syntaxvar{method-name} \slp
  \syntaxvar{argument-list}
  \syntaxvar{result-type}
  \syntaxvar{attribute-list} \srp
  \syntaxspace \indexedsyntaxvar{body-expr}{1}, \sldots,
  \indexedsyntaxvar{body-expr}{n} \srp \\
  \\
  \syntaxvar{keyword} \syntaxdefequal
  \skeyword{define-simple-method} \syntaxor
  \skeyword{define-simple-virtual-method} \syntaxor
  \skeyword{define-static-simple-virtual-method} \\
  \syntaxvar{method-name} \syntaxdefequal
  \syntaxelement{identifier} \\
  \syntaxvar{argument-list} \syntaxdefequal \slp
  \syntaxopt{\indexedsyntaxvar{arg}{1} \sldots
    \indexedsyntaxvar{arg}{n}} \srp \\
  \indexedsyntaxvar{arg}{k} \syntaxdefequal (\indexedsyntaxvar{arg-name}{k}
  \indexedsyntaxvar{arg-type}{k}) \\
  \indexedsyntaxvar{arg-name}{k} \syntaxdefequal \syntaxelement{identifier} \\
  \attrlistdef
\end{syntaxblock}


Keyword \keyword{define-simple-method} defines a normal
simple method.
Keyword \keyword{define-simple-virtual-method} defines a virtual
dynamic simple method.
Keyword \keyword{define-static-simple-virtual-method} defines a virtual
static simple method.
Note that
the argument list may be \code{()}.
Expressions \indexedsyntaxvarf{arg-type}{k} and
\syntaxvarf{result-type} have to be static type expressions.
It is an error if the result type is not \builtin{<none>} and
the type of the last body expression is not a subtype of
\syntaxvarf{result-type}. If \syntaxvarf{result-type} is not
\builtin{<none>} the result value of the procedure is the value of the
last body expression.


\macrodef{define-simple-proc}
\label{subsec:expr-define-simple-proc}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{define-simple-proc} \syntaxvar{procedure-name} \slp
  \syntaxvar{argument-list}
  \syntaxvar{result-type}
  \syntaxvar{attribute-list} \srp
  \syntaxspace \indexedsyntaxvar{body-expr}{1}, \sldots,
  \indexedsyntaxvar{body-expr}{n} \srp \\
  \\
  \syntaxvar{procedure-name} \syntaxdefequal
  \syntaxelement{identifier} \\
  \syntaxvar{argument-list} \syntaxdefequal \slp
  \syntaxopt{\indexedsyntaxvar{arg}{1} \sldots
    \indexedsyntaxvar{arg}{n}} \srp \\
  \indexedsyntaxvar{arg}{k} \syntaxdefequal (\indexedsyntaxvar{arg-name}{k}
  \indexedsyntaxvar{arg-type}{k}) \\
  \indexedsyntaxvar{arg-name}{k} \syntaxdefequal \syntaxelement{identifier} \\
  \attrlistdef
\end{syntaxblock}


Keyword \keyword{define-simple-proc} defines constant
\syntaxvarf{procedure-name} with a simple procedure value.
Note that
the argument list may be \code{()}.
Expressions \indexedsyntaxvarf{arg-type}{k} and
\syntaxvarf{result-type} have to be static type expressions.
It is an error if the result type is not \builtin{<none>} and
the type of the last body expression is not a subtype of
\syntaxvarf{result-type}.
If \syntaxvarf{result-type} is not
\builtin{<none>} the result value of the procedure is the value of the
last body expression.


\macrodef{define-main-proc}
\label{subsec:expr-define-main-proc}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{define-main-proc} \slp
  \syntaxvar{argument-list}
  \syntaxvar{result-type}
  \syntaxvar{attribute-list} \srp
  \syntaxspace \indexedsyntaxvar{body-expr}{1}, \sldots,
  \indexedsyntaxvar{body-expr}{n} \srp \\
  \\
  \syntaxvar{argument-list} \syntaxdefequal \slp
  \syntaxopt{\indexedsyntaxvar{arg}{1} \sldots
    \indexedsyntaxvar{arg}{n}} \srp \\
  \indexedsyntaxvar{arg}{k} \syntaxdefequal (\indexedsyntaxvar{arg-name}{k}
  \indexedsyntaxvar{arg-type}{k}) \\
  \indexedsyntaxvar{arg-name}{k} \syntaxdefequal \syntaxelement{identifier} \\
  \attrlistdef
\end{syntaxblock}


This form defines the main procedure of a program. See section
``Programs and Modules'' in the language manual.


\macrodef{execute-with-current-continuation}
\macrodef{exec/cc}


\begin{syntaxblock}
  \slp \skeyword{execute-with-current-continuation} \syntaxor
  \skeyword{exec/cc} \syntaxvar{jump-proc} \syntaxvar{jump-type}
  \syntaxvar{body}
  \srp \\
  \\
  \syntaxvar{jump-proc} \syntaxdefequal \syntaxelement{identifier}
\end{syntaxblock}

This is a frontend for the procedure \code{call/cc}.
The \syntaxvarf{body} is an expression that
may invoke procedure \syntaxvarf{jump-proc}. This kind of invocation
sets the current continuation to the continuation of the
\keyword{exec/cc} expression. Type \syntaxvarf{jump-type} is the type
of the object that \syntaxvarf{jump-proc} passes into the
continuation. Keyword \keyword{exec/cc} is defined as an alias to
\keyword{execute-with-current-continuation}. The body expression has
to be pure and its type must not be \code{<none>}.


\macrodef{execute-with-current-continuation-nonpure}
\macrodef{exec/cc-nonpure}


These macros are like \code{exec/cc} except that the body expression
may be nonpure.


\macrodef{execute-with-current-continuation-without-result}
\macrodef{exec/cc-without-result}


These macros are like \code{exec/cc-nonpure} except that the type of
the body expression may be \code{<none>}.


\chapter{Module \code{(standard-library core-forms2)}}


\section{Macros}
\label{sec:core-forms2_macros}


\macrodef{guard}
\label{subsec:guard}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{guard} \slp
  \syntaxvar{exception-variable}
  \indexedsyntaxvar{clause}{1} \sldots
  \indexedsyntaxvar{clause}{n}
  \syntaxopt{\syntaxvar{else-clause}} \srp \\
  \indexedsyntaxvar{body-expr}{1} \sldots
  \indexedsyntaxvar{body-expr}{n} \srp \\
  \indexedsyntaxvar{clause}{k} \syntaxdefequal \slp
  \indexedsyntaxvar{condition}{k}
  \indexedsyntaxvar{expr}{k,1}, \sldots,
  \indexedsyntaxvar{expr}{k,m(k)} \srp \\
  \syntaxvar{else-clause} \syntaxdefequal \slp \skeyword{else}
  \indexedsyntaxvar{else-expr}{1}, \sldots,
  \indexedsyntaxvar{else-expr}{p} \srp
\end{syntaxblock}


The syntax of \indexedsyntaxvarf{clause}{k} and
\syntaxvarf{else-clause} is similar to the same syntax elements in
\keyword{cond} form, see section \ref{subsec:cond}.
When a \keyword{guard} form is executed it starts evaluating the body
expressions in order. If an exception is raised during the body
expression evaluation do the following:
\begin{itemize}
  \item Bind the variable \syntaxvarf{exception-variable} to the
    exception.
  \item
    Evaluate conditions in clauses \indexedsyntaxvarf{clause}{k} in
    order. When the first condition returns true evaluate the
    corresponding clause expressions and return the value of the last
    expression as the value of the \keyword{guard} expression.
  \item
    If none of the conditions returns true evaluate the
    \syntaxvarf{else-clause} and return its value as the value of the
    \keyword{guard} expression.
  \item
    If none of the conditions returns true and
    \syntaxvarf{else-clause} is not present reraise the exception to
    be handled by the surrounding exception handler.
\end{itemize}
The conditions, condition expressions, and the body expressions have
to be pure and not \code{<none>}.


\macrodef{guard-nonpure}
\label{subsec:guard-nonpure}


This form is like \code{guard} except that the conditions, condition
expressions, and the body expressions may be nonpure.


\macrodef{guard-without-result}
\label{subsec:guard-without-result}


This form is like \code{guard-nonpure} except that the types of the condition
expressions and body expressions may be \code{<none>}.


\chapter{Module \code{(standard-library list-utilities)}}


\section{Simple Methods}


\procdef{length}


\startprocsyntax
\begin{codeblock}
  (length lst)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(\builtin{:uniform-list} \builtin{<object>})}}%
  {A list}
\end{arglist}


\procresult{Number of elements in the list}%
{\builtin{<integer>}}


\procpurity{pure}


\section{Parametrized Methods}


\procdef{but-last}


\startprocsyntax
\begin{codeblock}
  (but-last lst)
\end{codeblock}


\typeparams{\typeparam{element}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:nonempty-uniform-list \typeparam{element})}}
  {A nonempty list}
\end{arglist}


\procresult{The list without the last element}%
{\code{(:uniform-list \typeparam{element})}}


\procpurity{pure}


\procdef{but-last0}


\startprocsyntax
\begin{codeblock}
  (but-last0 lst)
\end{codeblock}


\typeparams{\typeparam{element}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list \typeparam{element})}}
  {A list}
\end{arglist}


\procresult{The list without the last element}%
{\code{(:uniform-list \typeparam{element})}}


\procpurity{pure}


If the argument list is empty raise an exception.


\procdef{caar}


\startprocsyntax
\begin{codeblock}
  (\code{caar} x)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{((:pair (:pair \typeparam{type} <object>) <object>))}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\code{\typeparam{type}}}


\procpurity{pure}


Expression \code{(caar x)} is equivalent to \code{(car (car x))}.


\procdef{cadr}


\startprocsyntax
\begin{codeblock}
  (\code{cadr} x)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{(:pair <object> (:pair \typeparam{type} <object>))}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\code{\typeparam{type}}}


\procpurity{pure}


Expression \code{(cadr x)} is equivalent to \code{(car (cdr x))}.


\procdef{cdar}


\startprocsyntax
\begin{codeblock}
  (\code{cdar} x)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{(:pair (:pair <object> \typeparam{type}) <object>)}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\code{\typeparam{type}}}


\procpurity{pure}


Expression \code{(cdar x)} is equivalent to \code{(cdr (car x))}.


\procdef{cddr}


\startprocsyntax
\begin{codeblock}
  (\code{cddr} x)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{(:pair <object> (:pair <object> \typeparam{type}))}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\code{\typeparam{type}}}


\procpurity{pure}


Expression \code{(cddr x)} is equivalent to \code{(cdr (cdr x))}.


\procdef{caddr}


\startprocsyntax
\begin{codeblock}
  (\code{caddr} x)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{(:pair <object> (:pair <object> (:pair \typeparam{type} <object>)))}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\code{\typeparam{type}}}


\procpurity{pure}


Expression \code{(caddr x)} is equivalent to \code{(car (cdr (cdr x)))}.


\procdef{cdddr}


\startprocsyntax
\begin{codeblock}
  (\code{cdddr} x)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{(:pair <object> (:pair <object> (:pair <object> \typeparam{type})))}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\code{\typeparam{type}}}


\procpurity{pure}


Expression \code{(cdddr x)} is equivalent to \code{(cdr (cdr (cdr x)))}.


\procdef{cadddr}


\startprocsyntax
\begin{codeblock}
  (\code{cadddr} x)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{(:pair <object> (:pair <object> (:pair <object> (:pair \typeparam{type} <object>))))}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\code{\typeparam{type}}}


\procpurity{pure}


Expression \code{(cadddr x)} is equivalent to \code{(car (cdr (cdr (cdr x))))}.


\procdef{delete}


\startprocsyntax
\begin{codeblock}
  (\code{delete} x l pred-eq)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{\typeparam{type}}}{An object}
  \argument{l}{\code{(:uniform-list \typeparam{type})}}%
  {A list}
  \argument{pred-eq}{\code{(:binary-predicate \typeparam{type} \typeparam{type})}}%
  {A binary predicate}
\end{arglist}


\procresult{A list constructed by deleting elements equal to \code{x} from \code{l}}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


The equality of objects is checked with procedure \code{pred-eq}.


\procdef{drop}


\startprocsyntax
\begin{codeblock}
  (\code{drop} lst count)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}%
  {A list}
  \argument{count}{\builtin{<integer>}}{Number of elements to be dropped}
\end{arglist}


\procresult{A list constructed by dropping away the first \code{count} %
  elements of list \code{lst}}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


If \code{count} is larger than the length of \code{lst} an exception is raised.


\procdef{drop-right}


\startprocsyntax
\begin{codeblock}
  (\code{drop-right} lst count)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}%
  {A list}
  \argument{count}{\builtin{<integer>}}{Number of elements to be dropped}
\end{arglist}


\procresult{A list constructed by dropping away the last \code{count} %
  elements of list \code{lst}}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


If \code{count} is larger than the length of \code{lst} an exception is raised.


\procdef{head}


\startprocsyntax
\begin{codeblock}
  (\code{head} l)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{l}{\code{(:uniform-list \typeparam{type})}}%
  {A list}
\end{arglist}


\procresult{The head of the list}%
{\code{\typeparam{type}}}


\procpurity{pure}


This method returns the head of the list. If the list is empty an exception is
raised.


\procdef{tail}


\startprocsyntax
\begin{codeblock}
  (\code{tail} l)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{l}{\code{(:uniform-list \typeparam{type})}}%
  {A list}
\end{arglist}


\procresult{The tail of the list}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


This method returns the tail of the list. If the list is empty an exception is
raised.


\procdef{take}


\startprocsyntax
\begin{codeblock}
  (\code{take} lst count)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}%
  {A list}
  \argument{count}{\builtin{<integer>}}{Number of elements to be taken}
\end{arglist}


\procresult{A list containing the first \code{count} elements of list %
  \code{lst}}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


If \code{count} is larger than the length of \code{lst} an exception is raised.


\procdef{take-right}


\startprocsyntax
\begin{codeblock}
  (\code{take-right} lst count)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}%
  {A list}
  \argument{count}{\builtin{<integer>}}{Number of elements to be taken}
\end{arglist}


\procresult{A list containing the last \code{count} elements of list %
  \code{lst}}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


If \code{count} is larger than the length of \code{lst} an exception is raised.


\procdef{last}


\startprocsyntax
\begin{codeblock}
  (last lst)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:nonempty-uniform-list \typeparam{type})}}
  {A nonempty list}
\end{arglist}


\procresult{The last element of the list \procarg{lst}}%
{\code{\typeparam{type}}}


\procpurity{pure}


\procdef{last0}


\startprocsyntax
\begin{codeblock}
  (last0 lst)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}
  {A list}
\end{arglist}


\procresult{The last element of the list \procarg{lst}}%
{\code{\typeparam{type}}}


\procpurity{pure}


If the argument list is empty an exception is raised.


\procdef{for-each}
\label{sec:for-each}


\startprocsyntax
\begin{codeblock}
  (for-each \procarg{proc} \indexedprocarg{lst}{1} ... \indexedprocarg{lst}{n})
\end{codeblock}


\typeparams{\typeparam{arglist}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      ((\builtin{splice} \typeparam{arglist})) %
      \cbuiltin{<none>} nonpure)}}%
  {A procedure to apply}
  \indexedargument{lst}{k}{\code{(:uniform-list \indexedsyntaxvarf{t}{k})}}%
  {A list to take arguments from}
\end{arglist}


\noprocresult


\procpurity{nonpure}


The semantics resembles Scheme \code{for-each}.
Procedure \procarg{proc} is applied to the
\(j\)th elements of the \indexedprocarg{lst}{k}'s for each
\(j=1, \ldots, m\) (in this order) where \(m\)
is the minimum of the lengths of \indexedprocarg{lst}{k}'s.
You may use a procedure with result type \builtin{<none>} as the first
argument to \code{for-each}.
The value of the type
parameter \code{\typeparam{arglist}} is a tuple type consisting of
types \indexedsyntaxvarf{t}{k}, \(k=1,\ldots,n\).
Procedure \procarg{proc} takes arguments with types
\indexedsyntaxvarf{t}{k}, \(k=1,\ldots,n\).

\procdef{for-each1}
\label{sec:for-each1}


\startprocsyntax
\begin{codeblock}
  (for-each1 \procarg{proc} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{arg-type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{arg-type}) %
      <none> nonpure)}}%
  {A procedure to apply}
  \argument{lst}{\code{(:uniform-list \typeparam{arg-type})}}%
  {Values to which the procedure is applied}
\end{arglist}


\noprocresult


\procpurity{nonpure}


The semantics resembles Scheme \code{for-each}.
You may use a procedure with result type \builtin{<none>} as the first
argument to \code{for-each}.


\procdef{for-each2}
\label{sec:for-each2}


\startprocsyntax
\begin{codeblock}
  (for-each2 \procarg{proc} \procarg{lst1} \procarg{lst2})
\end{codeblock}


\typeparams{\typeparam{arg1}, \typeparam{arg2}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{arg1} \typeparam{arg2}) %
      <none> nonpure)}}%
  {A procedure to apply}
  \argument{lst1}{\code{(:uniform-list \typeparam{arg1})}}%
  {Values to which the procedure is applied}
  \argument{lst2}{\code{(:uniform-list \typeparam{arg2})}}%
  {Values to which the procedure is applied}
\end{arglist}


\noprocresult


\procpurity{nonpure}


The semantics resembles Scheme \code{for-each}.
You may use a procedure with result type \builtin{<none>} as the first
argument to \code{for-each}.


\procdef{map}
\label{sec:map}


\startprocsyntax
\begin{codeblock}
  (map \procarg{proc} \indexedprocarg{lst}{1} ... \indexedprocarg{lst}{n})
\end{codeblock}


\typeparams{\typeparam{arglist}, \typeparam{result-type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      ((\builtin{splice} \typeparam{arglist})) %
      \typeparam{result-type} pure)}}%
  {A procedure to apply}
  \indexedargument{lst}{k}{\code{(:uniform-list \indexedsyntaxvarf{t}{k})}}%
  {Lists to take arguments from}
\end{arglist}


\procresult{A list constructed by applying \procarg{proc} to the %
  \(j\)th elements of the \indexedprocarg{lst}{k}'s for each %
  \(j=1, \ldots, m\) where \(m\) %
  is the minimum of the list lengths}%
{\code{(\cbuiltin{:uniform-list} \typeparam{result-type})}}


\procpurity{pure}


The semantics resembles Scheme \code{map}. The procedure is applied to
the arguments in the order of increasing \(j\).
The value of the type
parameter \code{\typeparam{arglist}} is a tuple type consisting of
types \indexedsyntaxvarf{t}{k}, \(k=1,\ldots,n\). Note that you
cannot use procedure with result type \builtin{<none>} as the first
argument of \code{map}.


\procdef{map1}
\label{sec:map1}


\startprocsyntax
\begin{codeblock}
  (map1 \procarg{proc} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{arg-type}, \typeparam{result-type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{arg-type}) %
      \typeparam{result-type} pure)}}%
  {A procedure to apply}
  \argument{lst}{\code{(:uniform-list \typeparam{arg-type})}}%
  {Values to which the procedure is applied}
\end{arglist}


\procresult{A list constructed by applying \procarg{proc} to the %
  elements of list \procarg{lst}}
{\code{(\cbuiltin{:uniform-list} \typeparam{result-type})}}


\procpurity{pure}


The semantics resembles \code{map} except this procedure takes exactly
one argument list. The procedure is applied to
the arguments in the order they are listed.
Note that you cannot use procedure with result type \builtin{<none>}
as the first argument of \code{map1}.


\procdef{map2}
\label{sec:map2}


\startprocsyntax
\begin{codeblock}
  (map2 \procarg{proc} \procarg{lst1} \procarg{lst2})
\end{codeblock}


\typeparams{\typeparam{arg1}, \typeparam{arg2}, \typeparam{result}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{arg1} \typeparam{arg2}) %
      \typeparam{result} pure)}}%
  {A procedure to apply}
  \argument{lst1}{\code{(:uniform-list \typeparam{arg1})}}%
  {Values to which the procedure is applied}
  \argument{lst2}{\code{(:uniform-list \typeparam{arg2})}}%
  {Values to which the procedure is applied}
\end{arglist}


\procresult{A list constructed by applying \procarg{proc} to the %
  elements of lists \procarg{lst1} and \procarg{lst2}}
{\code{(\cbuiltin{:uniform-list} \typeparam{result})}}


\procpurity{pure}


The semantics resembles \code{map} except this procedure takes exactly
two argument lists.
Note that you cannot use procedure with result type \builtin{<none>}
as the first argument of \code{map2}.


\procdef{map-nonpure}
\label{sec:map-nonpure}


\startprocsyntax
\begin{codeblock}
  (map-nonpure \procarg{proc} \indexedprocarg{lst}{1} ... \indexedprocarg{lst}{n})
\end{codeblock}


\typeparams{\typeparam{arglist}, \typeparam{result-type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      ((\builtin{splice} \typeparam{arglist})) %
      \typeparam{result-type} nonpure)}}%
  {A procedure to apply}
  \indexedargument{lst}{k}{\code{(:uniform-list \indexedsyntaxvarf{t}{k})}}%
  {A list to take arguments from}
\end{arglist}


\procresult{A list constructed by applying \procarg{proc} to the %
  \(j\)th elements of the \indexedprocarg{lst}{k}'s for each %
  \(j=1, \ldots, m\) where \(m\) %
  is the minimum of the list lengths}%
{\code{(\cbuiltin{:uniform-list} \typeparam{result-type})}}


\procpurity{nonpure}


The semantics of \code{map-nonpure} resemble \code{map} except
\code{proc} may be nonpure. The value of
the type parameter \code{\typeparam{arglist}} is a tuple type
consisting of types \indexedsyntaxvarf{t}{k}, \(k=1,\ldots,n\). Note
that you cannot use procedure with result type \builtin{<none>} as the
first argument of \code{map-nonpure}.


\procdef{map-nonpure1}
\label{sec:map-nonpure1}


\startprocsyntax
\begin{codeblock}
  (map-nonpure1 \procarg{proc} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{arg-type}, \typeparam{result-type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{arg-type}) %
      \typeparam{result-type} nonpure)}}%
  {A procedure to apply}
  \argument{lst}{\code{(:uniform-list \typeparam{arg-type})}}%
  {Values to which the procedure is applied}
\end{arglist}


\procresult{A list constructed by applying \procarg{proc} to the %
  elements of list \procarg{lst}}
{\code{(\cbuiltin{:uniform-list} \typeparam{result-type})}}


\procpurity{nonpure}


The semantics resembles \code{map-nonpure} except this procedure takes
exactly one argument list.
Note that you cannot use procedure with result type \builtin{<none>}
as the first argument of \code{map-nonpure1}.


\procdef{map-nonpure2}
\label{sec:map-nonpure2}


\startprocsyntax
\begin{codeblock}
  (map-nonpure2 \procarg{proc} \procarg{lst1} \procarg{lst2})
\end{codeblock}


\typeparams{\typeparam{arg1}, \typeparam{arg2}, \typeparam{result}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{arg1} \typeparam{arg2}) %
      \typeparam{result} nonpure)}}%
  {A procedure to apply}
  \argument{lst1}{\code{(:uniform-list \typeparam{arg1})}}%
  {Values to which the procedure is applied}
  \argument{lst2}{\code{(:uniform-list \typeparam{arg2})}}%
  {Values to which the procedure is applied}
\end{arglist}


\procresult{A list constructed by applying \procarg{proc} to the %
  elements of lists \procarg{lst1} and \procarg{lst2}}
{\code{(\cbuiltin{:uniform-list} \typeparam{result})}}


\procpurity{nonpure}


The semantics resembles \code{map-nonpure} except this procedure takes
exactly two argument lists.
Note that you cannot use procedure with result type \builtin{<none>}
as the first argument of \code{map2}.


\procdef{fold1}
\label{sec:fold1}


\startprocsyntax
\begin{codeblock}
  (fold1 \procarg{proc} \procarg{x-init} \procarg{l})
\end{codeblock}


\typeparams{\typeparam{component}, \typeparam{result}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
  (\typeparam{component} \typeparam{result}) %
  \typeparam{result} pure)}}
  {A procedure to apply}
  \argument{x-init}{\code{\typeparam{result}}}
  {Initial value for folding}
  \argument{l}{\code{(:uniform-list \typeparam{component})}}
  {A list to fold}
\end{arglist}


\procresult{A list constructed by folding the argument list with the argument %
procedure}
{\code{\typeparam{result}}}


\procpurity{pure}


Each \code{proc} call is \code{(proc elem previous)} where elem is from \code{l}
and \code{previous} is the return value from the previous call to \code{proc},
or the given \code{x-init} for the first call. Procedure \code{fold1} works
through the list elements from first to last.


\procdef{fold-right1}
\label{sec:fold-right1}


\startprocsyntax
\begin{codeblock}
  (fold-right1 \procarg{proc} \procarg{x-init} \procarg{l})
\end{codeblock}


\typeparams{\typeparam{component}, \typeparam{result}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
  (\typeparam{component} \typeparam{result}) %
  \typeparam{result} pure)}}
  {A procedure to apply}
  \argument{x-init}{\code{\typeparam{result}}}
  {Initial value for folding}
  \argument{l}{\code{(:uniform-list \typeparam{component})}}
  {A list to fold}
\end{arglist}


\procresult{A list constructed by folding the argument list with the argument %
procedure}
{\code{\typeparam{result}}}


\procpurity{pure}


This procedure is similar to \code{fold1} but the list elements are worked
from last to first.


\procdef{for-all?}
\label{sec:for-all?}


\startprocsyntax
\begin{codeblock}
  (for-all? \procarg{proc} \indexedprocarg{lst}{1} ... \indexedprocarg{lst}{n})
\end{codeblock}


\typeparams{\typeparam{arglist}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      ((\builtin{splice} \typeparam{arglist})) %
      \cbuiltin{<boolean>} pure)}}%
  {A procedure to apply}
  \indexedargument{lst}{k}{\code{(:uniform-list \indexedsyntaxvarf{t}{k})}}%
  {Lists to take arguments from}
\end{arglist}


\procresult{\true\ iff \procarg{proc} returns \true\ for each
  elementwise application to lists \indexedprocarg{lst}{k}}
{\cbuiltin{<boolean>}}


\procpurity{pure}


Procedure \code{proc} is
applied to the arguments in the order they are listed.
Note that if any of the applications of \procarg{proc} returns
\false\ the rest of the elements are not evaluated.  If the lengths of
the lists are different the number of evaluations is the length of the
shortest list. If all the argument lists are \builtin{null} return
\true.  The value of the type parameter \code{\typeparam{arglist}} is
a tuple type consisting of types \indexedsyntaxvarf{t}{k},
\(k=1,\ldots,n\).
Procedure \procarg{proc} takes arguments with types
\indexedsyntaxvarf{t}{k}, \(k=1,\ldots,n\).


\procdef{for-all1?}
\label{sec:for-all1?}


\startprocsyntax
\begin{codeblock}
  (for-all1? \procarg{proc} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{argtype}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{argtype})) %
      \cbuiltin{<boolean>} pure)}}%
  {A procedure to apply}
  \argument{lst}{\code{(:uniform-list \typeparam{argtype})}}
  {A list to take arguments from}
\end{arglist}


\procresult{\true\ iff \procarg{proc} returns \true\ for each
  application to the elements of list \procarg{lst}}%
{\cbuiltin{<boolean>}}


\procpurity{pure}


Procedure \code{proc} is
applied to the arguments in the order they are listed.
Note that if any of the applications of \procarg{proc} returns
\false\ the rest of the elements are not evaluated.
If \procarg{lst} is \builtin{null} return \true.


\procdef{for-all2?}
\label{sec:for-all2?}


\startprocsyntax
\begin{codeblock}
  (for-all2? \procarg{proc} \procarg{lst1} \procarg{lst2})
\end{codeblock}


\typeparams{\typeparam{arg1}, \typeparam{arg2}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{arg1} \typeparam{arg2})) %
      \cbuiltin{<boolean>} pure)}}%
  {A procedure to apply}
  \argument{lst1}{\code{(:uniform-list \typeparam{arg1})}}%
  {A list to take arguments from}
  \argument{lst2}{\code{(:uniform-list \typeparam{arg2})}}%
  {A list to take arguments from}
\end{arglist}


\procresult{\true\ iff \procarg{proc} returns \true\ for each
  application to the elements of lists \procarg{lst1} and \procarg{lst2}}%
{\cbuiltin{<boolean>}}


\procpurity{pure}


Procedure \code{proc} is
applied to the arguments in the order they are listed.
Note that if any of the applications of \procarg{proc} returns
\false\ the rest of the elements are not evaluated.
If \procarg{lst1} or \procarg{lst2} is \builtin{null} return \true.


\procdef{for-all-nonpure?}
\label{sec:for-all-nonpure?}


\startprocsyntax
\begin{codeblock}
  (for-all-nonpure? \procarg{proc} \indexedprocarg{lst}{1} ...
  \indexedprocarg{lst}{n})
\end{codeblock}


\typeparams{\typeparam{arglist}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      ((\builtin{splice} \typeparam{arglist})) %
      \cbuiltin{<boolean>} nonpure)}}%
  {A procedure to apply}
  \indexedargument{lst}{k}{\code{(:uniform-list \indexedsyntaxvarf{t}{k})}}%
  {Lists to take arguments from}
\end{arglist}


\procresult{\true\ iff \procarg{proc} returns \true\ for each
  elementwise application to lists \indexedprocarg{lst}{k}}
{\cbuiltin{<boolean>}}


\procpurity{nonpure}


This procedure is similar to \code{for-all?} except that \procarg{proc}
may have side effects.


\procdef{for-all-nonpure1?}
\label{sec:for-all-nonpure1?}


\startprocsyntax
\begin{codeblock}
  (for-all-nonpure1? \procarg{proc} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{argtype}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{argtype})) %
      \cbuiltin{<boolean>} nonpure)}}%
  {A procedure to apply}
  \argument{lst}{\code{(:uniform-list \typeparam{argtype})}}
  {A list to take arguments from}
\end{arglist}


\procresult{\true\ iff \procarg{proc} returns \true\ for each
  application to the elements of list \procarg{lst}}%
{\cbuiltin{<boolean>}}


\procpurity{nonpure}


This procedure is similar to \code{for-all1?} except that \procarg{proc}
may have side effects.


\procdef{for-all-nonpure2?}
\label{sec:for-all-nonpure2?}


\startprocsyntax
\begin{codeblock}
  (for-all-nonpure2? \procarg{proc} \procarg{lst1} \procarg{lst2})
\end{codeblock}


\typeparams{\typeparam{arg1}, \typeparam{arg2}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{arg1} \typeparam{arg2})) %
      \cbuiltin{<boolean>} nonpure)}}%
  {A procedure to apply}
  \argument{lst1}{\code{(:uniform-list \typeparam{arg1})}}%
  {A list to take arguments from}
  \argument{lst2}{\code{(:uniform-list \typeparam{arg2})}}%
  {A list to take arguments from}
\end{arglist}


\procresult{\true\ iff \procarg{proc} returns \true\ for each
  application to the elements of lists \procarg{lst1} and \procarg{lst2}}%
{\cbuiltin{<boolean>}}


\procpurity{nonpure}


This procedure is similar to \code{for-all2?} except that \procarg{proc}
may have side effects.


\procdef{exists?}
\label{sec:exists?}


\startprocsyntax
\begin{codeblock}
  (exists? \procarg{proc} \indexedprocarg{lst}{1} ... \indexedprocarg{lst}{n})
\end{codeblock}


\typeparams{\typeparam{arglist}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      ((\builtin{splice} \typeparam{arglist})) %
      \cbuiltin{<boolean>} pure)}}%
  {A procedure to apply}
  \indexedargument{lst}{k}{\code{(:uniform-list \indexedsyntaxvarf{t}{k})}}%
  {Lists to take arguments from}
\end{arglist}


\procresult{\true\ iff \procarg{proc} returns \true\ for any
  elementwise application to lists \indexedprocarg{lst}{k}}
{\cbuiltin{<boolean>}}


\procpurity{pure}


The value of the type parameter \code{\typeparam{arglist}} is
a tuple type consisting of types \indexedsyntaxvarf{t}{k},
\(k=1,\ldots,n\).
Procedure \procarg{proc} takes arguments with types
\indexedsyntaxvarf{t}{k}, \(k=1,\ldots,n\).
Procedure \code{proc} is applied to the arguments in the order they
are listed.
Note that if any of the applications of \procarg{proc} returns
\true\ the rest of the elements are not evaluated.
If the lengths of the lists are different the number of evaluations is
the length of the shortest list. If all the argument lists are
\builtin{null} return \false.


\procdef{exists1?}
\label{sec:exists1?}


\startprocsyntax
\begin{codeblock}
  (exists1? \procarg{proc} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{argtype}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{argtype})) %
      \cbuiltin{<boolean>} pure)}}%
  {A procedure to apply}
  \argument{lst}{\code{(:uniform-list \typeparam{argtype})}}
  {A list to take arguments from}
\end{arglist}


\procresult{\true\ iff \procarg{proc} returns \true\ for some
  application to the elements of list \procarg{lst}}%
{\cbuiltin{<boolean>}}


\procpurity{pure}


Procedure \code{proc} is applied to the arguments in the order they
are listed.
Note that if any of the applications of \procarg{proc} returns
\true\ the rest of the elements are not evaluated.
If \procarg{lst} is \builtin{null} return \false.


\procdef{exists2?}
\label{sec:exists2?}


\startprocsyntax
\begin{codeblock}
  (exists2? \procarg{proc} \procarg{lst1} \procarg{lst2})
\end{codeblock}


\typeparams{\typeparam{arg1}, \typeparam{arg2}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{arg1} \typeparam{arg2})) %
      \cbuiltin{<boolean>} pure)}}%
  {A procedure to apply}
  \argument{lst1}{\code{(:uniform-list \typeparam{arg1})}}%
  {A list to take arguments from}
  \argument{lst2}{\code{(:uniform-list \typeparam{arg2})}}%
  {A list to take arguments from}
\end{arglist}


\procresult{\true\ iff \procarg{proc} returns \true\ for some
  application to the elements of lists \procarg{lst1} and \procarg{lst2}}%
{\cbuiltin{<boolean>}}


\procpurity{pure}


Procedure \code{proc} is applied to the arguments in the order they
are listed.
Note that if any of the applications of \procarg{proc} returns
\true\ the rest of the elements are not evaluated.
If \procarg{lst1} or \procarg{lst2} is \builtin{null} return \false.


\procdef{exists-nonpure?}
\label{sec:exists-nonpure?}


\startprocsyntax
\begin{codeblock}
  (exists-nonpure? \procarg{proc} \indexedprocarg{lst}{1} ...
  \indexedprocarg{lst}{n})
\end{codeblock}


\typeparams{\typeparam{arglist}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      ((\builtin{splice} \typeparam{arglist})) %
      \cbuiltin{<boolean>} nonpure)}}%
  {A procedure to apply}
  \indexedargument{lst}{k}{\code{(:uniform-list \indexedsyntaxvarf{t}{k})}}%
  {Lists to take arguments from}
\end{arglist}


\procresult{\true\ iff \procarg{proc} returns \true\ for any
  elementwise application to lists \indexedprocarg{lst}{k}}
{\cbuiltin{<boolean>}}


\procpurity{nonpure}


This procedure is similar to \code{exists?} except that \procarg{proc}
may have side effects.


\procdef{exists-nonpure1?}
\label{sec:exists-nonpure1?}


\startprocsyntax
\begin{codeblock}
  (exists-nonpure1? \procarg{proc} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{argtype}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{argtype})) %
      \cbuiltin{<boolean>} nonpure)}}%
  {A procedure to apply}
  \argument{lst}{\code{(:uniform-list \typeparam{argtype})}}
  {A list to take arguments from}
\end{arglist}


\procresult{\true\ iff \procarg{proc} returns \true\ for some
  application to the elements of list \procarg{lst}}%
{\cbuiltin{<boolean>}}


\procpurity{nonpure}


This procedure is similar to \code{exists1?} except that \procarg{proc}
may have side effects.


\procdef{exists-nonpure2?}
\label{sec:exists-nonpure2?}


\startprocsyntax
\begin{codeblock}
  (exists-nonpure2? \procarg{proc} \procarg{lst1} \procarg{lst2})
\end{codeblock}


\typeparams{\typeparam{arg1}, \typeparam{arg2}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
      (\typeparam{arg1} \typeparam{arg2})) %
      \cbuiltin{<boolean>} nonpure)}}%
  {A procedure to apply}
  \argument{lst1}{\code{(:uniform-list \typeparam{arg1})}}%
  {A list to take arguments from}
  \argument{lst2}{\code{(:uniform-list \typeparam{arg2})}}%
  {A list to take arguments from}
\end{arglist}


\procresult{\true\ iff \procarg{proc} returns \true\ for some
  application to the elements of lists \procarg{lst1} and \procarg{lst2}}%
{\cbuiltin{<boolean>}}


\procpurity{nonpure}


This procedure is similar to \code{exists2?} except that \procarg{proc}
may have side effects.


\procdef{map-car}
\label{sec:map-car}


\startprocsyntax
\begin{codeblock}
  (map-car \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{arglist}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:tuple (:nonempty-uniform-list
      \indexedsyntaxvarf{t}{1}) ... (:nonempty-uniform-list
      \indexedsyntaxvarf{t}{n}))}}
  {Lists to take arguments from}
\end{arglist}


\procresult{A list constructed by taking the first element of each
  component list of \procarg{lst}}
{\code{\typeparam{arglist}}}


\procpurity{pure}


The value of the type parameter \code{\typeparam{arglist}} is
a tuple type consisting of types \indexedsyntaxvarf{t}{k},
\(k=1,\ldots,n\).


\procdef{map-cdr}
\label{sec:map-cdr}


\startprocsyntax
\begin{codeblock}
  (map-cdr \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{arglist}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:tuple (:nonempty-uniform-list
      \indexedsyntaxvarf{t}{1}) ... (:nonempty-uniform-list
      \indexedsyntaxvarf{t}{n}))}}
  {Lists to take arguments from}
\end{arglist}


\procresult{A list constructed by taking the tail of each
  component list of \procarg{lst}}
{\code{(type-loop \typeparam{type} \typeparam{arglist} %
  (:uniform-list \typeparam{type}))}}


\procpurity{pure}


The value of the type parameter \code{\typeparam{arglist}} is
a tuple type consisting of types \indexedsyntaxvarf{t}{k},
\(k=1,\ldots,n\).


\procdef{assoc-general}


\startprocsyntax
\begin{codeblock}
(assoc-general \code{key} \code{association-list} \code{default}
  \code{my-eq?})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}, \typeparam{default}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}%
  {the key to be searched}
  \argument{association-list}{\code{(:alist \typeparam{type1} %
      \typeparam{type2})}}%
  {the association list to be searched}
  \argument{default}{\code{\typeparam{default}}}%
  {the value returned if no association is found}
  \argument{my-eq?}{\code{(:procedure (\typeparam{type1} \typeparam{type1}) %
      <boolean> pure)}}%
    {the equivalence predicate to be used in the search}
\end{arglist}


\procresult{The result of the search}%
{\code{(:union (:pair \typeparam{type1} \typeparam{type2}) %
    \typeparam{default})}}


\procpurity{pure}


The association list \code{association-list} is searched for
\code{key}. If \code{key} is found return the first association having
the key. Otherwise return \code{default}. The keys are compared with
the equivalence predicate \code{my-eq?}.


\procdef{assoc}


\startprocsyntax
\begin{codeblock}
(assoc \code{key} \code{association-list} \code{default})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}, \typeparam{default}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}%
  {the key to be searched}
  \argument{association-list}{\code{(:alist \typeparam{type1} %
      \typeparam{type2})}}%
  {the association list to be searched}
  \argument{default}{\code{\typeparam{default}}}%
  {the value returned if no association is found}
\end{arglist}


\procresult{The result of the search}%
{\code{(:union (:pair \typeparam{type1} \typeparam{type2}) %
    \typeparam{default})}}


\procpurity{pure}


The association list \code{association-list} is searched for
\code{key}. If \code{key} is found return the first association having
the key. Otherwise return \code{default}. The keys are compared with
the equivalence predicate \code{equal?}.


\procdef{assoc-values}


\startprocsyntax
\begin{codeblock}
(assoc-values \code{key} \code{association-list} \code{default})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}, \typeparam{default}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}%
  {the key to be searched}
  \argument{association-list}{\code{(:alist \typeparam{type1} %
      \typeparam{type2})}}%
  {the association list to be searched}
  \argument{default}{\code{\typeparam{default}}}%
  {the value returned if no association is found}
\end{arglist}


\procresult{The result of the search}%
{\code{(:union (:pair \typeparam{type1} \typeparam{type2}) %
    \typeparam{default})}}


\procpurity{pure}


The association list \code{association-list} is searched for
\code{key}. If \code{key} is found return the first association having
the key. Otherwise return \code{default}. The keys are compared with
the equivalence predicate \code{equal-values?}.


\procdef{assoc-objects}


\startprocsyntax
\begin{codeblock}
(assoc-objects \code{key} \code{association-list} \code{default})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}, \typeparam{default}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}%
  {the key to be searched}
  \argument{association-list}{\code{(:alist \typeparam{type1} %
      \typeparam{type2})}}%
  {the association list to be searched}
  \argument{default}{\code{\typeparam{default}}}%
  {the value returned if no association is found}
\end{arglist}


\procresult{The result of the search}%
{\code{(:union (:pair \typeparam{type1} \typeparam{type2}) %
    \typeparam{default})}}


\procpurity{pure}


The association list \code{association-list} is searched for
\code{key}. If \code{key} is found return the first association having
the key. Otherwise return \code{default}. The keys are compared with
the equivalence predicate \code{equal-objects?}.


\procdef{assoc-contents}


\startprocsyntax
\begin{codeblock}
(assoc-contents \code{key} \code{association-list} \code{default})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}, \typeparam{default}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}%
  {the key to be searched}
  \argument{association-list}{\code{(:alist \typeparam{type1} %
      \typeparam{type2})}}%
  {the association list to be searched}
  \argument{default}{\code{\typeparam{default}}}%
  {the value returned if no association is found}
\end{arglist}


\procresult{The result of the search}%
{\code{(:union (:pair \typeparam{type1} \typeparam{type2}) %
    \typeparam{default})}}


\procpurity{pure}


The association list \code{association-list} is searched for
\code{key}. If \code{key} is found return the first association having
the key. Otherwise return \code{default}. The keys are compared with
the equivalence predicate \code{equal-contents?}.


\procdef{general-alist-delete}


\startprocsyntax
\begin{codeblock}
(general-alist-delete \code{key} \code{alist} \code{my-eq?})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}%
  {the key to be searched}
  \argument{alist}{\code{(:alist \typeparam{type1} %
      \typeparam{type2})}}%
  {the association list to be searched}
  \argument{my-eq?}{\code{(:procedure (\typeparam{type1} \typeparam{type1}) %
      <boolean> pure)}}%
    {the equivalence predicate to be used in the search}
\end{arglist}


\procresult{The association list obtained by removing all bindings %
  for key \procarg{key} from \procarg{alist}}%
{\code{(:alist \typeparam{type1} \typeparam{type2})}}


\procpurity{pure}


The keys are compared with the equivalence predicate \procarg{my-eq?}.


\procdef{alist-delete}


\startprocsyntax
\begin{codeblock}
(alist-delete \code{key} \code{alist})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}%
  {the key to be searched}
  \argument{alist}{\code{(:alist \typeparam{type1} %
      \typeparam{type2})}}%
  {the association list to be searched}
\end{arglist}


\procresult{The association list obtained by removing all bindings %
  for key \procarg{key} from \procarg{alist}}%
{\code{(:alist \typeparam{type1} \typeparam{type2})}}


\procpurity{pure}


The keys are compared with the equivalence predicate \procarg{equal?}.


\procdef{value-alist-delete}


\startprocsyntax
\begin{codeblock}
(value-alist-delete \code{key} \code{alist})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}%
  {the key to be searched}
  \argument{alist}{\code{(:alist \typeparam{type1} %
      \typeparam{type2})}}%
  {the association list to be searched}
\end{arglist}


\procresult{The association list obtained by removing all bindings %
  for key \procarg{key} from \procarg{alist}}%
{\code{(:alist \typeparam{type1} \typeparam{type2})}}


\procpurity{pure}


The keys are compared with the equivalence predicate \procarg{equal-values?}.


\procdef{object-alist-delete}


\startprocsyntax
\begin{codeblock}
(object-alist-delete \code{key} \code{alist})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}%
  {the key to be searched}
  \argument{alist}{\code{(:alist \typeparam{type1} %
      \typeparam{type2})}}%
  {the association list to be searched}
\end{arglist}


\procresult{The association list obtained by removing all bindings %
  for key \procarg{key} from \procarg{alist}}%
{\code{(:alist \typeparam{type1} \typeparam{type2})}}


\procpurity{pure}


The keys are compared with the equivalence predicate \procarg{equal-objects?}.


\procdef{content-alist-delete}


\startprocsyntax
\begin{codeblock}
(content-alist-delete \code{key} \code{alist})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}%
  {the key to be searched}
  \argument{alist}{\code{(:alist \typeparam{type1} %
      \typeparam{type2})}}%
  {the association list to be searched}
\end{arglist}


\procresult{The association list obtained by removing all bindings %
  for key \procarg{key} from \procarg{alist}}%
{\code{(:alist \typeparam{type1} \typeparam{type2})}}


\procpurity{pure}


The keys are compared with the equivalence predicate \procarg{equal-contents?}.


\procdef{member-general?}


\startprocsyntax
\begin{codeblock}
(member-general? \code{object} \code{lst} \code{my-eq?})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{object}{\code{\typeparam{type}}}%
  {the object to be searched}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}
  {the list to be searched}
  \argument{my-eq?}{\code{(:procedure (\typeparam{type} \typeparam{type}) %
      <boolean> pure)}}%
    {equivalence predicate to be used in the search}
\end{arglist}


\procresult{Result of the search}%
{\code{<boolean>}}


\procpurity{pure}


The list \code{lst} is searched for
\code{object}. If \code{object} is found return \code{\#t}. Otherwise
return \code{\#f}. The list items are compared with the equivalence
predicate \code{my-eq?}.


\procdef{member-values?}


\startprocsyntax
\begin{codeblock}
(member-values? \code{object} \code{lst})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{object}{\code{\typeparam{type}}}%
  {the object to be searched}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}
  {the list to be searched}
\end{arglist}


\procresult{Result of the search}%
{\code{<boolean>}}


\procpurity{pure}


The list \code{lst} is searched for
\code{object}. If \code{object} is found return \code{\#t}. Otherwise
return \code{\#f}. The list items are compared with the equivalence
predicate \code{equal-values?}.


\procdef{member-objects?}


\startprocsyntax
\begin{codeblock}
(member-objects? \code{object} \code{lst})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{object}{\code{\typeparam{type}}}%
  {the object to be searched}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}
  {the list to be searched}
\end{arglist}


\procresult{Result of the search}%
{\code{<boolean>}}


\procpurity{pure}


The list \code{lst} is searched for
\code{object}. If \code{object} is found return \code{\#t}. Otherwise
return \code{\#f}. The list items are compared with the equivalence
predicate \code{equal-objects?}.


\procdef{member-contents?}


\startprocsyntax
\begin{codeblock}
(member-contents? \code{object} \code{lst})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{object}{\code{\typeparam{type}}}%
  {the object to be searched}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}
  {the list to be searched}
\end{arglist}


\procresult{Result of the search}%
{\code{<boolean>}}


\procpurity{pure}


The list \code{lst} is searched for
\code{object}. If \code{object} is found return \code{\#t}. Otherwise
return \code{\#f}. The list items are compared with the equivalence
predicate \code{equal-contents?}.


\procdef{append}


\startprocsyntax
\begin{codeblock}
  (\code{append} list-1 ... list-n)
\end{codeblock}


\typeparams{\typeparam{types}}


\startprocarguments
\begin{arglist}
  \argument{list-k}{\code{(:uniform-list \indexedsyntaxvarf{t}{k})}}%
  {A list to be merged}
\end{arglist}


\procresult{A list constructed by appending the arguments}%
{\code{(:uniform-list (\builtin{:union} \indexedsyntaxvarf{t}{1} %
    ... \indexedsyntaxvarf{t}{n}))}}


\procpurity{pure}


\procdef{append-tuples}


\startprocsyntax
\begin{codeblock}
  (\code{append-tuples} \indexedprocarg{tuple}{1}
  ... \indexedprocarg{tuple}{n})
\end{codeblock}


\typeparams{\typeparam{tuples}}


\startprocarguments
\begin{arglist}
  \indexedargument{tuple}{k}{\syntaxformulacmd{(\sbuiltin{\tupletype} %
    \indexedsyntaxvar{t}{k,1} %
    ... %
    \indexedsyntaxvar{t}{k,m(k)})}}
  {A tuple to be merged}
\end{arglist}


\procresult{A tuple constructed by appending the arguments}%
{\code{(\builtin{\tupletype} %
\indexedsyntaxvarf{t}{1,1} ... \indexedsyntaxvarf{t}{1,m(1)} %
... %
\indexedsyntaxvarf{t}{n,1} ... \indexedsyntaxvarf{t}{n,m(n)})}}


\procpurity{pure}


\procdef{append-uniform}


\startprocsyntax
\begin{codeblock}
  (\code{append-uniform} list-1 ... list-n)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{list-k}{\code{(:uniform-list \typeparam{type})}}%
  {A list to be merged}
\end{arglist}


\procresult{A list constructed by appending the arguments}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


\procdef{append-uniform0}


\startprocsyntax
\begin{codeblock}
  (\code{append-uniform0} lists)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{lists}{\code{(:uniform-list (:uniform-list \typeparam{type}))}}%
  {Lists to be merged}
\end{arglist}


\procresult{A list constructed by appending the component lists of the argument}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


\procdef{append-uniform2}


\startprocsyntax
\begin{codeblock}
  (\code{append-uniform2} lst1 lst2)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{lst1}{\code{(:uniform-list \typeparam{type})}}%
  {A list to be merged}
  \argument{lst2}{\code{(:uniform-list \typeparam{type})}}%
  {A list to be merged}
\end{arglist}


\procresult{A list constructed by appending the arguments}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


\procdef{reverse}


\startprocsyntax
\begin{codeblock}
  (\code{reverse} lst)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}%
  {A list to be reversed}
\end{arglist}


\procresult{A list constructed by reversing the argument list}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


\procdef{uniform-list-ref}


\startprocsyntax
\begin{codeblock}
  (uniform-list-ref \procarg{lst} \procarg{index})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(\builtin{:uniform-list} \typeparam{type})}}{A uniform list}
  \argument{index}{\builtin{<integer>}}{Index to the list}
\end{arglist}


\procresult{Element of \procarg{lst} at position \procarg{index}}%
{\code{\typeparam{type}}}


\procpurity{pure}


The indices start from zero.


\procdef{filter}


\startprocsyntax
\begin{codeblock}
(filter \code{pred} \code{lst})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure (\typeparam{type}) %
      <boolean> pure)}}%
    {the predicate used for picking the elements}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}%
  {The list to be searched}
\end{arglist}


\procresult{The list computed by picking all the elements in %
  \procarg{lst} for which \procarg{pred} returns \code{\#t}}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


\procdef{distinct-elements?}


\startprocsyntax
\begin{codeblock}
(distinct-elements? \code{lst} \code{my-eq?})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list \typeparam{type})}}%
  {The list to be checked}
  \argument{my-eq?}{\code{(:procedure (\typeparam{type} %
      \typeparam{type}) <boolean> pure)}}%
    {the equivalence predicate used for checking the elements}
\end{arglist}


\procresult{\code{\#t} iff no two elements of \procarg{lst} are equal
  by \procarg{my-eq?}}%
{\code{<boolean>}}


\procpurity{pure}


\procdef{find}


\startprocsyntax
\begin{codeblock}
(find \procarg{pred} \procarg{l} \procarg{x-default})
\end{codeblock}


\typeparams{\typeparam{type}, \typeparam{default}}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure (\typeparam{type}) <boolean> pure)}}%
    {the predicate used for the search}
  \argument{l}{\code{(:uniform-list \typeparam{type})}}%
  {The list to be searched}
\end{arglist}


\procresult{The first element satisfying the predicate in the list}%
{\code{(:union \typeparam{type} \typeparam{default})}}


\procpurity{pure}


If no list element satisfies the predicate value \procarg{x-default}
is returned.


\procdef{count}


\startprocsyntax
\begin{codeblock}
(count \procarg{pred} \procarg{l})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure (\typeparam{type}) <boolean> pure)}}%
    {the predicate used for counting}
  \argument{l}{\code{(:uniform-list \typeparam{type})}}%
  {The list to be searched}
\end{arglist}


\procresult{The number of the list elements satisfying the predicate}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{delete-duplicates}


\startprocsyntax
\begin{codeblock}
(delete-duplicates \procarg{l} \procarg{pred-eq})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
    \argument{l}{\code{(:uniform-list \typeparam{type})}}%
    {The list to be processed}
    \argument{pred-eq}{\code{(:procedure (\typeparam{type} \typeparam{type}) <boolean> pure)}}%
    {An equality predicate}
\end{arglist}


\procresult{The argument list with duplicates removed}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


\noindent
Argument \procarg{pred-eq} is used to determine whether the list elements are
equal.


\procdef{list-set-diff}


\startprocsyntax
\begin{codeblock}
(list-set-diff \procarg{l1} \procarg{l2} \procarg{pred-eq})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
    \argument{l1}{\code{(:uniform-list \typeparam{type})}}%
    {A list}
    \argument{l2}{\code{(:uniform-list \typeparam{type})}}%
    {A list}
    \argument{pred-eq}{\code{(:procedure (\typeparam{type} \typeparam{type}) <boolean> pure)}}%
    {An equality predicate}
\end{arglist}


\procresult{A list of elements of \procarg{l1} that do not belong to \procarg{l2}}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


\noindent
Argument \procarg{pred-eq} is used to determine whether the list elements are
equal.


\procdef{union-of-lists}


\startprocsyntax
\begin{codeblock}
(union-of-lists \procarg{l1} \procarg{l2} \procarg{pred-eq})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
    \argument{l1}{\code{(:uniform-list \typeparam{type})}}%
    {A list}
    \argument{l2}{\code{(:uniform-list \typeparam{type})}}%
    {A list}
    \argument{pred-eq}{\code{(:binary-predicate \typeparam{type} \typeparam{type})}}%
    {An equality predicate}
\end{arglist}


\procresult{Union of lists \procarg{l1} and \procarg{l2}}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


\noindent
The result of the method consists of the elements of both of the arguments with
duplicates removed.
Argument \procarg{pred-eq} is used to determine whether the list elements are
equal.


\procdef{union-of-alists}


\startprocsyntax
\begin{codeblock}
(union-of-alists \procarg{al1} \procarg{al2} \procarg{pred-eq})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
    \argument{al1}{\code{(:alist \typeparam{key} \typeparam{value})}}%
    {An association list}
    \argument{l2}{\code{(:alist \typeparam{key} \typeparam{value})}}%
    {An association list}
    \argument{pred-eq}{\code{(:binary-predicate \typeparam{key} \typeparam{key})}}%
    {An equality predicate}
\end{arglist}


\procresult{Union of association lists \procarg{al1} and \procarg{al2}}%
{\code{(:alist \typeparam{key} \typeparam{value})}}


\procpurity{pure}


\noindent
The result of the method consists of the elements of both of the arguments with
duplicate keys removed.
Argument \procarg{pred-eq} is used to determine whether the keys are
equal.


\section{Macros}
\label{sec:list-utilities_macros}


\macrodef{iterate-list}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{iterate-list} \slp \syntaxvar{var} \syntaxvar{type}
  \syntaxvar{list} \srp \;\;
  \indexedsyntaxvar{body}{1} \sldots
  \indexedsyntaxvar{body}{n} \srp
\end{syntaxblock}


Variable \syntaxvar{var} is bound to each element of \syntaxvarf{list}
in order and the \indexedsyntaxvarf{body}{k} are evaluated. The value
\syntaxvarf{list} has to be an instance of type \code{(:uniform-list
  \syntaxvar{type})} and the static type of \syntaxvar{var} is
\syntaxvar{type}.


\macrodef{iterate-list-pure}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{iterate-list-pure} \slp \syntaxvar{var} \syntaxvar{type}
  \syntaxvar{list} \srp \;\;
  \indexedsyntaxvar{body}{1} \sldots
  \indexedsyntaxvar{body}{n} \srp
\end{syntaxblock}


Same as \code{iterate-list} except that the form is a pure
expression. The body expressions have to be pure.


\macrodef{iterate-list-with-break}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{iterate-list-with-break} \slp \syntaxvar{var} \syntaxvar{type}
  \syntaxvar{list} \syntaxvar{condition} \srp \;\;
  \indexedsyntaxvar{body}{1} \sldots
  \indexedsyntaxvar{body}{n} \srp
\end{syntaxblock}


Variable \syntaxvar{var} is bound to each element of \syntaxvarf{list}
in order and the \indexedsyntaxvarf{body}{k} are evaluated.
Expression \syntaxvar{condition} is evaluated before each iteration
step and if it returns \true\ the iteration is stopped.
The value
\syntaxvarf{list} has to be an instance of type \code{(:uniform-list
  \syntaxvar{type})} and the static type of \syntaxvar{var} is
\syntaxvar{type}.


\macrodef{iterate-list-with-break-pure}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{iterate-list-with-break-pure} \slp \syntaxvar{var}
  \syntaxvar{type}
  \syntaxvar{list} \syntaxvar{condition} \srp \;\;
  \indexedsyntaxvar{body}{1} \sldots
  \indexedsyntaxvar{body}{n} \srp
\end{syntaxblock}


Same as \code{iterate-list-with.break} except that the form is a pure
expression. The body expressions have to be pure.


\macrodef{iterate-2-lists}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{iterate-2-lists}
  \slp
  \slp \syntaxvar{var1} \syntaxvar{type1} \syntaxvar{list1} \srp
  \slp \syntaxvar{var2} \syntaxvar{type2} \syntaxvar{list2} \srp
  \srp \;
  \indexedsyntaxvar{body}{1} \sldots
  \indexedsyntaxvar{body}{n} \srp
\end{syntaxblock}


Variables \syntaxvarf{var1} and \syntaxvarf{var2} are bound to each
element of \syntaxvarf{list1} and \syntaxvarf{list2} in order and the
expressions \indexedsyntaxvarf{body}{k} are evaluated.
The value
\syntaxvarf{list1} has to be an instance of type \code{(:uniform-list
  \syntaxvar{type1})} and the static type of \syntaxvarf{var1} is
\syntaxvarf{type1}.
The value
\syntaxvarf{list2} has to be an instance of type \code{(:uniform-list
  \syntaxvar{type2})} and the static type of \syntaxvarf{var2} is
\syntaxvarf{type2}.
If the lengths of \syntaxvarf{list1} and \syntaxvarf{list2} are
different the shorter list determines the number of elements handled.


\macrodef{iterate-2-lists-pure}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{iterate-2-lists-pure}
  \slp
  \slp \syntaxvar{var1} \syntaxvar{type1} \syntaxvar{list1} \srp
  \slp \syntaxvar{var2} \syntaxvar{type2} \syntaxvar{list2} \srp
  \srp \\
  \mbox{\hspace{0.5cm}} \indexedsyntaxvar{body}{1} \sldots
  \indexedsyntaxvar{body}{n} \srp
\end{syntaxblock}


This macro is similar to \macro{iterate-2-lists} except that the
expression is pure and all the body expressions have to be pure.


\macrodef{iterate-2-lists-with-break}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{iterate-2-lists-with-break}
  \slp
  \slp \syntaxvar{var1} \syntaxvar{type1} \syntaxvar{list1} \srp
  \slp \syntaxvar{var2} \syntaxvar{type2} \syntaxvar{list2} \srp
  \srp \\
  \mbox{\hspace{0.5cm}} \syntaxvar{condition}
  \indexedsyntaxvar{body}{1} \sldots
  \indexedsyntaxvar{body}{n} \srp
\end{syntaxblock}


This macro is similar to \macro{iterate-2-lists} except that
\syntaxvarf{condition} is checked at each iteration step and the
iteration is stopped if \syntaxvarf{condition} is \true.


\macrodef{iterate-2-lists-with-break-pure}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{iterate-2-lists-with-break-pure}
  \slp
  \slp \syntaxvar{var1} \syntaxvar{type1} \syntaxvar{list1} \srp
  \slp \syntaxvar{var2} \syntaxvar{type2} \syntaxvar{list2} \srp
  \srp \\
  \mbox{\hspace{0.5cm}} \syntaxvar{condition}
  \indexedsyntaxvar{body}{1} \sldots
  \indexedsyntaxvar{body}{n} \srp
\end{syntaxblock}


This macro is similar to \macro{iterate-2-lists-with-break} except that the
expression is pure and all the body expressions have to be pure.


\chapter{Module \code{(standard-library string-utilities)}}


\section{Data Types}


\begin{datatype}
  \datatypename{<string-match-result>}
  \datatypetype{\builtin{:union}}
  \datatypedesc{Return value of procedure \code{string-match}}
\end{datatype}


\section{Simple Methods}


\procdef{replace-char}


\startprocsyntax
\begin{codeblock}
  (replace-char \procarg{str} \procarg{ch-src} \procarg{ch-dest})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{ch-src}{\builtin{<character>}}{The character to be replaced}
  \argument{ch-dest}{\builtin{<character>}}{The destination character}
\end{arglist}


\procresult{A string obtained by replacing character \procarg{ch-src} with %
  \procarg{ch-dest} in string \procarg{str}}%
{\builtin{<string>}}


\procpurity{pure}


\procdef{replace-char-with-string}


\startprocsyntax
\begin{codeblock}
  (replace-char-with-string \procarg{str} \procarg{ch-src} \procarg{str-dest})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{ch-src}{\builtin{<character>}}{The character to be replaced}
  \argument{str-dest}{\builtin{<string>}}{The destination string}
\end{arglist}


\procresult{A string obtained by replacing characrter \procarg{ch-src} with %
  \procarg{str-dest} in string \procarg{str}}%
{\builtin{<string>}}


\procpurity{pure}


\procdef{join-strings-with-sep}


\startprocsyntax
\begin{codeblock}
  (join-strings-with-sep \procarg{lst} \procarg{str-separator})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list <string>)}}{A list of strings to join}
  \argument{str-separator}{\builtin{<string>}}{The separator}
\end{arglist}


\procresult{A string obtained to join the strings in \procarg{lst} in order}%
{\builtin{<string>}}


\procpurity{pure}


\procdef{search-substring}


\startprocsyntax
\begin{codeblock}
  (search-substring \procarg{str} \procarg{str-match})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{str-match}{\builtin{<string>}}{The string to be searched}
\end{arglist}


\procpurity{pure}


\procresult{Index of the first occurrence of string \procarg{str-match} %
  in string \procarg{str} (-1 if the string is not found)}%
{\builtin{<integer>}}


\procdef{search-substring-from-end}


\startprocsyntax
\begin{codeblock}
  (search-substring-from-end \procarg{str} \procarg{str-match})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{str-match}{\builtin{<string>}}{The string to be searched}
\end{arglist}


\procpurity{pure}


\procresult{Search for string \procarg{str-match} in string %
  \procarg{str} starting from the end of \procarg{str} and %
  return the index of the first match (-1 if the search does not %
  succeed)}%
{\builtin{<integer>}}


\procdef{split-string}


\startprocsyntax
\begin{codeblock}
  (split-string \procarg{str} \procarg{ch})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string to be split}
  \argument{ch}{\builtin{<character>}}{The separator character}
\end{arglist}


\procresult{A list constructed by splitting the string \procarg{str}}%
{\code{(:uniform-list <string>)}}


\procpurity{pure}


The character \procarg{ch} is used as a separator in splitting.


\procdef{string}


\startprocsyntax
\begin{codeblock}
  (string \indexedprocarg{char}{1} ... \indexedprocarg{char}{n})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \indexedargument{char}{k}{\builtin{<character>}}{A character}
\end{arglist}


\procresult{A string consisting of characters \indexedprocarg{char}{1} %
  ... \indexedprocarg{char}{n}}%
{\builtin{<string>}}


\procpurity{pure}


\procdef{string-append}


\startprocsyntax
\begin{codeblock}
  (string-append \indexedprocarg{str}{1} ... \indexedprocarg{str}{n})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \indexedargument{str}{k}{\builtin{<string>}}{A string}
\end{arglist}


\procpurity{pure}


\procresult{A string obtained by concatenating strings %
  \indexedprocarg{str}{1} ... \indexedprocarg{str}{n}}%
{\builtin{<string>}}


\procdef{string-char-index}


\startprocsyntax
\begin{codeblock}
  (string-char-index \procarg{str} \procarg{ch})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{ch}{\builtin{<character>}}{A character to be searched}
\end{arglist}


\procpurity{pure}


\procresult{Index of the first occurrence of character \procarg{ch} %
  in string \procarg{str} (-1 if the character is not found)}%
{\builtin{<integer>}}


\procdef{string-char-index-right}


\startprocsyntax
\begin{codeblock}
  (string-char-index-right \procarg{str} \procarg{ch})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{ch}{\builtin{<character>}}{A character to be searched}
\end{arglist}


\procpurity{pure}


\procresult{Index of the last occurrence of character \procarg{ch} %
  in string \procarg{str} (-1 if the character is not found)}%
{\builtin{<integer>}}


\procdef{string-contains-char?}


\startprocsyntax
\begin{codeblock}
  (string-contains-char? \procarg{str} \procarg{ch})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{ch}{\builtin{<character>}}{A character}
\end{arglist}


\procpurity{pure}


\procresult{\true\ iff string \procarg{str} contains character \procarg{ch}}%
{\builtin{<boolean>}}


\procdef{string-drop}


\startprocsyntax
\begin{codeblock}
  (string-drop \procarg{str} \procarg{count})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{count}{\builtin{<integer>}}{Number of characters to be dropped}
\end{arglist}


\procresult{A string constructed of by dropping away the first %
  \procarg{count} characters of \procarg{str}}%
{\builtin{<string>}}


\procpurity{pure}


If \procarg{count} is larger than the length of \procarg{str} an
exception is raised.


\procdef{string-drop-right}


\startprocsyntax
\begin{codeblock}
  (string-drop-right \procarg{str} \procarg{count})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{count}{\builtin{<integer>}}{Number of characters to be dropped}
\end{arglist}


\procresult{A string constructed of by dropping away the last %
  \procarg{count} characters of \procarg{str}}%
{\builtin{<string>}}


\procpurity{pure}


If \procarg{count} is larger than the length of \procarg{str} an
exception is raised.


\procdef{string-empty?}


\startprocsyntax
\begin{codeblock}
  (string-empty? \procarg{str})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
\end{arglist}


\procresult{\true\ iff the string is empty}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{string-exact-match?}


\startprocsyntax
\begin{codeblock}
  (string-exact-match? \procarg{str-pattern} \procarg{str-source})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str-pattern}{\builtin{<string>}}{A pattern}
  \argument{str-source}{\builtin{<string>}}{The source string for matching}
\end{arglist}


\procresult{\true\ iff the pattern matches the whole source string}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{string-last-char}


\startprocsyntax
\begin{codeblock}
  (string-last-char \procarg{str})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
\end{arglist}


\procresult{The last character of the string \procarg{str}}%
{\builtin{<character>}}


\procpurity{pure}


If \procarg{str} is empty raise an exception.


\procdef{string-length}


\startprocsyntax
\begin{codeblock}
  (string-length \procarg{str})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
\end{arglist}


\procresult{The length of the string \procarg{str}}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{string-match}


\startprocsyntax
\begin{codeblock}
  (string-match \procarg{str-pattern} \procarg{str-source})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str-pattern}{\builtin{<string>}}{A pattern}
  \argument{str-source}{\builtin{<string>}}{The source string for matching}
\end{arglist}


\procresult{The results of the matching}%
{\builtin{<string-match-results>}}


\procpurity{pure}


If the matching fails return \code{null}. Otherwise the result is a
tuple consisting of three elements: the first element is the substring
to which the pattern matched, the second item is the index to the
source string where the matching started, and the third item the
index where the matching stopped.


\procdef{string-ref}


\startprocsyntax
\begin{codeblock}
  (string-ref \procarg{str} \procarg{index})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{index}{\builtin{<integer>}}{An index to the string}
\end{arglist}


\procresult{The character at the indexth position of string \procarg{str}}%
{\builtin{<character>}}


\procpurity{pure}


\procdef{string-take}


\startprocsyntax
\begin{codeblock}
  (string-take \procarg{str} \procarg{count})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{count}{\builtin{<integer>}}{Number of characters to be taken}
\end{arglist}


\procresult{A string consisting of the first \procarg{count} characters %
  of \procarg{str}}%
{\builtin{<string>}}


\procpurity{pure}


If \procarg{count} is larger than the length of \procarg{str} an
exception is raised.


\procdef{string-take-right}


\startprocsyntax
\begin{codeblock}
  (string-take-right \procarg{str} \procarg{count})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{count}{\builtin{<integer>}}{Number of characters to be taken}
\end{arglist}


\procresult{A string consisting of the last \procarg{count} characters %
  of \procarg{str}}%
{\builtin{<string>}}


\procpurity{pure}


If \procarg{count} is larger than the length of \procarg{str} an
exception is raised.


\procdef{substring}


\startprocsyntax
\begin{codeblock}
  (substring \procarg{str} \procarg{i-start} \procarg{i-end})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
  \argument{i-start}{\builtin{<integer>}}%
           {Index from which to start the extraction}
  \argument{i-start}{\builtin{<integer>}}%
           {Index to which to stop the extraction}
\end{arglist}


\procresult{A substring of \procarg{str}}%
{\builtin{<integer>}}


\procpurity{pure}


Note that the character at the position \procarg{i-end} is not
included in the substring.


\chapter{Module \code{(standard-library basic-math)}}


\section{Simple Methods}


\procdef{ceiling}


\startprocsyntax
\begin{codeblock}
  (ceiling \procarg{r})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real number}
\end{arglist}


\procresult{Rounded value}{\builtin{<integer>}}


\procpurity{pure}


This procedure rounds a real number towards infinity.


\procdef{even?}


\startprocsyntax
\begin{codeblock}
  (even? \procarg{i})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer number}
\end{arglist}


\procresult{Return \true\ iff the argument is even}%
           {\builtin{<boolean>}}


\procpurity{pure}


\procdef{factorial}


\startprocsyntax
\begin{codeblock}
  (factorial \procarg{i})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{A nonnegative integer number}
\end{arglist}


\procresult{The factorial of the argument}%
           {\builtin{<integer>}}


\procpurity{pure}


\procdef{finite?}


\startprocsyntax
\begin{codeblock}
  (finite? r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{Returns \true\ iff \code{r} is a finite value}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{floor}


\startprocsyntax
\begin{codeblock}
  (floor \procarg{r})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real number}
\end{arglist}


\procresult{Rounded value}{\builtin{<integer>}}


\procpurity{pure}


This procedure rounds a real number towards minus infinity.


\procdef{gcd}


\startprocsyntax
\begin{codeblock}
  (gcd \procarg{i1} \procarg{i2})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i1}{\builtin{<integer>}}{An integer number}
  \argument{i2}{\builtin{<integer>}}{An integer number}
\end{arglist}


\procresult{The greatest common divisor of the arguments}%
           {\builtin{<integer>}}


\procpurity{pure}


\procdef{i-log10-exact}


\startprocsyntax
\begin{codeblock}
  (i-log10-exact \procarg{i})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{A positive integer number}
\end{arglist}


\procresult{The base 10 logarithm of the argument or \code{null} if %
  the logarithm is not an integer}%
           {\code{(:maybe <integer>)}}


\procpurity{pure}


\procdef{i-log2-exact}


\startprocsyntax
\begin{codeblock}
  (i-log2-exact \procarg{i})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{A positive integer number}
\end{arglist}


\procresult{The base 2 logarithm of the argument or \code{null} if %
  the logarithm is not an integer}%
           {\code{(:maybe <integer>)}}


\procpurity{pure}


\procdef{infinite?}


\startprocsyntax
\begin{codeblock}
  (infinite? r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{Returns \true\ iff \code{r} is an infinite value}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer->real}


\startprocsyntax
\begin{codeblock}
(integer->real int)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{int}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The integer value converted to a real value}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{i-abs}


\startprocsyntax
\begin{codeblock}
  (i-abs n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{n}{\builtin{<integer>}}%
  {An integer number}
\end{arglist}


\procresult{Absolute value of the argument}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{i-nonneg-expt}


\startprocsyntax
\begin{codeblock}
  (i-nonneg-expt i-base i-expt)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i-base}{\builtin{<integer>}}%
  {An integer number}
  \argument{i-expt}{\builtin{<integer>}}%
  {A nonnegative integer number}
\end{arglist}


\procresult{\code{i-base} raised to the power \code{i-expt}}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{i-sign}


\startprocsyntax
\begin{codeblock}
  (i-sign i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}%
  {An integer number}
\end{arglist}


\procresult{Return 0 if \code{i} \(=\) 0, 1 if \code{i} \(>\) 0, and -1
  if \code{i} \(<\) 0}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{i-square}


\startprocsyntax
\begin{codeblock}
  (i-square n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{n}{\builtin{<integer>}}%
  {An integer number}
\end{arglist}


\procresult{Square of the argument}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{inf}


\startprocsyntax
\begin{codeblock}
  (inf)
\end{codeblock}


\noprocarguments


\procresult{The exceptional floating point value inf (positive infinity)}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{integer-float?}


\startprocsyntax
\begin{codeblock}
  (integer-float? r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{\true\ iff \code{r} is an integer value}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{nan}


\startprocsyntax
\begin{codeblock}
  (nan)
\end{codeblock}


\noprocarguments


\procresult{The exceptional floating point value \nan\ (not a number)}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{nan?}


\startprocsyntax
\begin{codeblock}
  (nan? r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{Returns \true\ iff \code{r} is a \nan\ value}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{neg-inf}


\startprocsyntax
\begin{codeblock}
  (neg-inf)
\end{codeblock}


\noprocarguments


\procresult{The exceptional floating point value -inf (negative infinity)}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{odd?}


\startprocsyntax
\begin{codeblock}
  (odd? \procarg{i})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer number}
\end{arglist}


\procresult{Return \true\ iff the argument is odd}%
           {\builtin{<boolean>}}


\procpurity{pure}


\procdef{quotient}


\startprocsyntax
\begin{codeblock}
(quotient int1 int2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{int1}{\builtin{<integer>}}{An integer value}
  \argument{int2}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<integer>}}


\procpurity{pure}


If the second argument is 0 raise exception
\code{numerical-overflow}.
Note that this procedure always returns an integer.


\procdef{r-abs}


\startprocsyntax
\begin{codeblock}
  (r-abs r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{Absolute value of the argument}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{r-ceiling}


\startprocsyntax
\begin{codeblock}
  (r-ceiling \procarg{r})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real number}
\end{arglist}


\procresult{Rounded value}{\builtin{<real>}}


\procpurity{pure}


This procedure rounds a real number towards infinity and returns a
real number.


\procdef{r-floor}


\startprocsyntax
\begin{codeblock}
  (r-floor \procarg{r})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real number}
\end{arglist}


\procresult{Rounded value}{\builtin{<real>}}


\procpurity{pure}


This procedure rounds a real number towards minus infinity and returns
a real number.


\procdef{r-int-expt}


\startprocsyntax
\begin{codeblock}
  (r-int-expt r-base i-expt)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r-base}{\builtin{<real>}}%
  {A real number}
  \argument{i-expt}{\builtin{<integer>}}%
  {An integer number}
\end{arglist}


\procresult{\code{r-base} raised to the power \code{i-expt}}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{r-nonneg-int-expt}


\startprocsyntax
\begin{codeblock}
  (r-nonneg-int-expt r-base i-expt)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r-base}{\builtin{<real>}}%
  {A real number}
  \argument{i-expt}{\builtin{<integer>}}%
  {A nonnegative integer number}
\end{arglist}


\procresult{\code{r-base} raised to the power \code{i-expt}}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{r-round}


\startprocsyntax
\begin{codeblock}
  (r-round \procarg{r})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real number}
\end{arglist}


\procresult{Rounded value}{\builtin{<real>}}


\procpurity{pure}


This procedure rounds a real number and return a real number.


\procdef{r-sign}


\startprocsyntax
\begin{codeblock}
  (r-sign r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{Return 0 if \code{r} \(=\) 0.0, 1 if \code{r} \(>\) 0.0, and -1
  if \code{r} \(<\) 0.0}%
{\builtin{<integer>}}


\procpurity{pure}


Return 0 for the exceptional value \nan.


\procdef{r-square}


\startprocsyntax
\begin{codeblock}
  (r-square r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{Square of the argument}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{r-truncate}


\startprocsyntax
\begin{codeblock}
  (r-truncate \procarg{r})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real number}
\end{arglist}


\procresult{Rounded value}{\builtin{<real>}}


\procpurity{pure}


This procedure rounds a real number towards zero and returns a real number.


\procdef{remainder}


\startprocsyntax
\begin{codeblock}
  (remainder \procarg{dividend} \procarg{divisor})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{dividend}{\builtin{<integer>}}{The dividend}
  \argument{divisor}{\builtin{<integer>}}{The divisor}
\end{arglist}


\procresult{The remainder obtained by dividing the dividend with the %
  divisor}{\builtin{<integer>}}


\procpurity{pure}


The semantics of \code{remainder} is the same as the semantics of
procedure \code{remainder} in Scheme (R6RS).


\procdef{round}


\startprocsyntax
\begin{codeblock}
  (round \procarg{r})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real number}
\end{arglist}


\procresult{Rounded value}{\builtin{<integer>}}


\procpurity{pure}


This procedure rounds a real number and returns an integer.


\procdef{truncate}


\startprocsyntax
\begin{codeblock}
  (truncate \procarg{r})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real number}
\end{arglist}


\procresult{Rounded value}{\builtin{<integer>}}


\procpurity{pure}


This procedure rounds a real number towards zero.


\section{Parametrized Methods}


\procdef{min}


\startprocsyntax
\begin{codeblock}
  (min \procarg{nr1} \procarg{nr2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{nr1}{\code{\typeparam{number}}}{A number}
  \argument{nr2}{\code{\typeparam{number}}}{A number}
\end{arglist}


\procresult{The minimum of the arguments}{\code{\typeparam{number}}}


\procpurity{pure}


The type \code{\typeparam{number}} has to define a boolean-valued
two-argument predicate \code{<=}.


\procdef{max}


\startprocsyntax
\begin{codeblock}
  (max \procarg{nr1} \procarg{nr2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{nr1}{\code{\typeparam{number}}}{A number}
  \argument{nr2}{\code{\typeparam{number}}}{A number}
\end{arglist}


\procresult{The maximum of the arguments}{\code{\typeparam{number}}}


\procpurity{pure}


The type \code{\typeparam{number}} has to define a boolean-valued
two-argument predicate \code{>=}.


\section{Virtual Methods}


\indexmethod{abs}
\indexmethod{square}
\indexmethod{sign}

\noindent
\puremethoddefwithvalue{abs}{<integer>}{<integer>}{i-abs}
\puremethoddefwithvalue{abs}{<real>}{<real>}{r-abs}
\puremethoddefwithvalue{square}{<integer>}{<integer>}{i-square}
\puremethoddefwithvalue{square}{<real>}{<real>}{r-square}
\puremethoddefwithvalue{sign}{<integer>}{<integer>}{i-sign}
\puremethoddefwithvalue{sign}{<real>}{<integer>}{r-sign}


\chapter{Module \code{(standard-library bitwise-arithmetic)}}


\section{Simple Methods}


\procdef{bitwise-not}


\startprocsyntax
\begin{codeblock}
  (bitwise-not i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}%
  {An integer number}
\end{arglist}


\procresult{The ones-complement of the argument}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{bitwise-and}


\startprocsyntax
\begin{codeblock}
  (bitwise-and i1 i2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i1}{\builtin{<integer>}}{An integer number}
  \argument{i2}{\builtin{<integer>}}{An integer number}
\end{arglist}


\procresult{The bitwise AND between the arguments}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{bitwise-ior}


\startprocsyntax
\begin{codeblock}
  (bitwise-ior i1 i2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i1}{\builtin{<integer>}}{An integer number}
  \argument{i2}{\builtin{<integer>}}{An integer number}
\end{arglist}


\procresult{The bitwise OR between the arguments}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{bitwise-xor}


\startprocsyntax
\begin{codeblock}
  (bitwise-xor i1 i2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i1}{\builtin{<integer>}}{An integer number}
  \argument{i2}{\builtin{<integer>}}{An integer number}
\end{arglist}


\procresult{The bitwise XOR between the arguments}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{bitwise-arithmetic-shift}
\index{\code{ash}}


\startprocsyntax
\begin{codeblock}
  (bitwise-arithmetic-shift i i-shift)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer number}
  \argument{i-shift}{\builtin{<integer>}}{The number of bits to be %
    shifted (maybe negative)}
\end{arglist}


\procresult{Value of \procarg{i} with bits shifted by %
  \procarg{i-shift} positions}%
{\builtin{<integer>}}


\procpurity{pure}


Positive values of \procarg{i-shift} mean shifting bits left and negative
values shifting right. Name \code{ash} is an alias for
\code{bitwise-arithmetic-shift}.


\procdef{bitwise-arithmetic-shift-right}


\startprocsyntax
\begin{codeblock}
  (bitwise-arithmetic-shift-right i i-shift)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer number}
  \argument{i-shift}{\builtin{<integer>}}{The number of bits to be %
    shifted (maybe negative)}
\end{arglist}


\procresult{Value of \procarg{i} with bits shifted right by %
  \procarg{i-shift} positions}%
{\builtin{<integer>}}


\procpurity{pure}


Negative values of \procarg{i-shift} shift bit to the left.


\procdef{bitwise-arithmetic-shift-left}


\startprocsyntax
\begin{codeblock}
  (bitwise-arithmetic-shift-left i i-shift)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer number}
  \argument{i-shift}{\builtin{<integer>}}{The number of bits to be %
    shifted (maybe negative)}
\end{arglist}


\procresult{Value of \procarg{i} with bits shifted left by %
  \procarg{i-shift} positions}%
{\builtin{<integer>}}


\procpurity{pure}


Negative values of \procarg{i-shift} shift bit to the right.


\chapter{Module \code{(standard-library promise)}}


This module implements delayed evaluation with the promise objects.
The promises resemble Scheme promises, see \cite{shinn2017}.


\section{Data Types}


\begin{datatype}
  \datatypename{:promise}
  \datatypetype{\builtin{:procedure}}
  \datatypenrparams{1}
  \datatypedesc{A promise object}
\end{datatype}


\begin{datatype}
  \datatypename{:nonpure-promise}
  \datatypetype{\builtin{:procedure}}
  \datatypenrparams{1}
  \datatypedesc{A promise object that can have side effects}
\end{datatype}


\section{Macros}


\macrodef{delay}
\label{subsec:delay}


\startmacrosyntax
\begin{syntaxblock}
  \slp
  \skeyword{delay}
  \syntaxvar{expression}
  \srp
\end{syntaxblock}


This macro creates a promise that delays the evaluation of the given
expression. This is a frontend to the procedure \code{make-promise}.
The argument expression has to be pure.


\macrodef{delay-nonpure}
\label{subsec:delay-nonpure}


\startmacrosyntax
\begin{syntaxblock}
  \slp
  \skeyword{delay-nonpure}
  \syntaxvar{expression}
  \srp
\end{syntaxblock}


This macro creates a promise that delays the evaluation of the given
expression. This is a frontend to the procedure \code{make-promise}.
The argument expression may be nonpure.


\section{Parametrized Methods}


\procdef{force}


\startprocsyntax
\begin{codeblock}
  (force promise)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{promise}{\code{(:promise \typeparam{type})}}%
  {A promise}
\end{arglist}


\procresult{The value of the promise}%
{\code{\typeparam{type}}}


\procpurity{pure}


This procedure evaluates the promise if it has not already been done
and returns the value.


\procdef{force-nonpure}


\startprocsyntax
\begin{codeblock}
  (force-nonpure promise)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{promise}{\code{(:nonpure-promise \typeparam{type})}}%
  {A nonpure promise}
\end{arglist}


\procresult{The value of the promise}%
{\code{\typeparam{type}}}


\procpurity{nonpure}


This procedure evaluates the promise if it has not already been done
and returns the value.


\procdef{make-nonpure-promise}


\startprocsyntax
\begin{codeblock}
  (make-nonpure-promise proc)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure () \typeparam{type} nonpure)}}%
  {A procedure}
\end{arglist}


\procresult{A promise}%
{\code{(:nonpure-promise \typeparam{type})}}


\procpurity{pure}


This procedure creates a promise that delays the evaluation of the
given procedure.


\procdef{make-promise}


\startprocsyntax
\begin{codeblock}
  (make-promise proc)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure () \typeparam{type} pure)}}%
  {A procedure}
\end{arglist}


\procresult{A promise}%
{\code{(:promise \typeparam{type})}}


\procpurity{pure}


This procedure creates a promise that delays the evaluation of the
given procedure. The procedure has to be pure.


\chapter{Module \code{(standard-library stream)}}


Streams are kind of abstract sequences. A stream is defined by the
following operations:
\begin{itemize}
\item \textit{stream-value:} Return the current value of the stream.
\item \textit{stream-next:} Read one stream element forward and return
  the stream with the new element as its current value.
\item \textit{stream-empty?:} Return true iff the stream is empty.
\end{itemize}
See programs \code{test451.thp}, \code{test452.thp}, and
\code{test453.thp} in directory \code{theme-d-code/tests} for
examples.


\section{Data Types}


\begin{datatype}
  \datatypename{:stream}
  \datatypetype{\builtin{:union}}
  \datatypenrparams{1}
  \datatypedesc{A stream}
\end{datatype}


\begin{datatype}
  \datatypename{:nonempty-stream}
  \datatypetype{\builtin{:pair}}
  \datatypenrparams{1}
  \datatypedesc{A nonempty stream}
\end{datatype}


\begin{datatype}
  \datatypename{:nonpure-stream}
  \datatypetype{\builtin{:union}}
  \datatypenrparams{1}
  \datatypedesc{A nonpure stream}
\end{datatype}


\begin{datatype}
  \datatypename{:nonempty-nonpure-stream}
  \datatypetype{\builtin{:pair}}
  \datatypenrparams{1}
  \datatypedesc{A nonempty nonpure stream}
\end{datatype}


\section{Simple Methods}


\procdef{make-input-expr-stream}


\startprocsyntax
\begin{codeblock}
(make-input-expr-stream ip)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{ip}{\builtin{<input-port>}}{An input port}
\end{arglist}


\procresult{A nonpure stream that reads from the given input port}%
{\code{(:nonpure-stream <object>)}}


\procpurity{pure}


\section{Parametrized Methods}


\procdef{stream-value}


\startprocsyntax
\begin{codeblock}
  (stream-value \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{stm}{\code{(:stream \typeparam{type})}}%
  {A stream}
\end{arglist}


\procresult{The current value of the stream}%
{\cbuiltin{\typeparam{type}}}


\procpurity{pure}


If the stream \code{stm} in empty this procedure raises an exception.


\procdef{stream-next}


\startprocsyntax
\begin{codeblock}
  (stream-next \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{stm}{\code{(:stream \typeparam{type})}}%
  {A stream}
\end{arglist}


\procresult{A stream located one step forward from the given stream}%
{\cbuiltin{(:stream \typeparam{type})}}


\procpurity{pure}


If the stream \code{stm} in empty this procedure raises an exception.


\procdef{stream-empty?}


\startprocsyntax
\begin{codeblock}
  (stream-empty? \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{stm}{\code{(:stream \typeparam{type})}}%
  {A stream}
\end{arglist}


\procresult{\true\ iff the stream is empty}%
{\cbuiltin{<boolean>}}


\procpurity{pure}


\procdef{stream->list}


\startprocsyntax
\begin{codeblock}
  (stream->list \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{stm}{\code{(:stream \typeparam{type})}}%
  {A stream}
\end{arglist}


\procresult{A list}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


\noindent
This procedure constructs a list by reading the stream until it is
empty.


\procdef{list->stream}


\startprocsyntax
\begin{codeblock}
  (list->stream \procarg{l})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{stm}{\code{(:uniform-list \typeparam{type})}}%
  {A list}
\end{arglist}


\procresult{A stream that processes the given list}%
{\code{(:stream \typeparam{type})}}


\procpurity{pure}


\procdef{nonpure-stream-value}


\startprocsyntax
\begin{codeblock}
  (nonpure-stream-value \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{stm}{\code{(:nonpure-stream \typeparam{type})}}%
  {A nonpure stream}
\end{arglist}


\procresult{The current value of the stream}%
{\cbuiltin{\typeparam{type}}}


\procpurity{pure}


If the stream \code{stm} in empty this procedure raises an exception.


\procdef{nonpure-stream-next}


\startprocsyntax
\begin{codeblock}
  (nonpure-stream-next \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{stm}{\code{(:nonpure-stream \typeparam{type})}}%
  {A nonpure stream}
\end{arglist}


\procresult{A nonpure stream located one step forward from the given %
nonpure-stream}%
{\cbuiltin{(:nonpure-stream \typeparam{type})}}


\procpurity{nonpure}


If the stream \code{stm} in empty this procedure raises an exception.


\procdef{nonpure-stream-empty?}


\startprocsyntax
\begin{codeblock}
  (nonpure-stream-empty? \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{stm}{\code{(:nonpure-stream \typeparam{type})}}%
  {A nonpure stream}
\end{arglist}


\procresult{\true\ iff the stream is empty}%
{\cbuiltin{<boolean>}}


\procpurity{pure}


\procdef{nonpure-stream->list}


\startprocsyntax
\begin{codeblock}
  (nonpure-stream->list \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{stm}{\code{(:nonpure-stream \typeparam{type})}}%
  {A nonpure stream}
\end{arglist}


\procresult{A list}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{nonpure}


\noindent
This procedure constructs a list by reading the stream until it is
empty.


\procdef{stream-map}


\startprocsyntax
\begin{codeblock}
  (stream-map \procarg{proc} \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{type1}) \typeparam{type2} %
      pure)}}{The procedure to be applied}
  \argument{stm}{\code{(:stream \typeparam{type1})}}%
  {The source stream}
\end{arglist}


\procresult{The target stream}%
{\code{(:stream \typeparam{type2})}}


\procpurity{pure}


\noindent
This procedure applies the argument procedure to the source stream
elements with delayed evaluation. Another stream is returned.


\procdef{stream-map-nonpure}


\startprocsyntax
\begin{codeblock}
  (stream-map-nonpure \procarg{proc} \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{type1}) \typeparam{type2} %
      nonpure)}}{The procedure to be applied}
  \argument{stm}{\code{(:stream \typeparam{type1})}}%
  {The source stream}
\end{arglist}


\procresult{The target stream}%
{\code{(:nonpure-stream \typeparam{type2})}}


\procpurity{nonpure}


\noindent
This procedure applies the argument procedure to the source stream
elements with delayed evaluation. Another stream is returned.
The applied procedure may have side effects and the result is a
nonpure stream.


\procdef{stream-for-each}


\startprocsyntax
\begin{codeblock}
  (stream-for-each \procarg{proc} \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type1}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{type1}) <none> %
      nonpure)}}{The procedure to be applied}
  \argument{stm}{\code{(:stream \typeparam{type1})}}%
  {A stream}
\end{arglist}


\noprocresult


\procpurity{nonpure}


\noindent
This procedure applies the argument procedure to the source stream
elements. The evaluation is not delayed and no value is returned.


\procdef{nonpure-stream-map}


\startprocsyntax
\begin{codeblock}
  (nonpure-stream-map \procarg{proc} \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{type1}) \typeparam{type2} %
      nonpure)}}{The procedure to be applied}
  \argument{stm}{\code{(:nonpure-stream \typeparam{type1})}}%
  {The source stream}
\end{arglist}


\procresult{The target stream}%
{\code{(:nonpure-stream \typeparam{type2})}}


\procpurity{nonpure}


\noindent
This procedure applies the argument procedure to the source nonpure
stream elements with delayed evaluation. Another stream is returned.
The applied procedure may have side effects and the result is a
nonpure stream.


\procdef{nonpure-stream-for-each}


\startprocsyntax
\begin{codeblock}
  (nonpure-stream-for-each \procarg{proc} \procarg{stm})
\end{codeblock}


\typeparams{\typeparam{type1}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{type1}) <none> %
      nonpure)}}{The procedure to be applied}
  \argument{stm}{\code{(:nonpure-stream \typeparam{type1})}}%
  {A nonpure stream}
\end{arglist}


\noprocresult


\procpurity{nonpure}


\noindent
This procedure applies the argument procedure to the source nonpure
stream elements. The evaluation is not delayed and no value is
returned.


\chapter{Module \code{(standard-library iterator)}}


This module implements purely functional iterators, see \cite{baker1993}.


\section{Data Types}


\begin{datatype}
  \datatypename{:iterator}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{1}
  \datatypedef{(:param-proc (\%target) ((:consumer \%source \%target)) %
    \%target pure)}
  \datatypedesc{An iterator}
\end{datatype}


\begin{datatype}
  \datatypename{:iterator-inst}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{2}
  \datatypedef{(:procedure ((:consumer \%source \%target)) \%target pure)}
  \datatypedesc{An instance of an iterator for which the target type %
  or the iteration is fixed}
\end{datatype}


\begin{datatype}
  \datatypename{:consumer}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{2}
  \datatypedef{(:procedure ((:maybe \%source) <boolean> %
    (:maybe (:iterator-inst \%source \%target))) \%target pure)}
  \datatypedesc{A procedure that ``consumes'' values yielded by %
  an iterator}
\end{datatype}


\section{Parametrized Methods}


\procdef{end-iter}


\startprocsyntax
\begin{codeblock}
  (end-iter consumer)
\end{codeblock}


\typeparams{\typeparam{source}, \typeparam{target}}


\startprocarguments
\begin{arglist}
  \argument{consumer}{\code{(:consumer \typeparam{source} \typeparam{target})}}%
  {A consumer procedure}
\end{arglist}


\procresult{Target object}%
{\code{\typeparam{target}}}


\procpurity{pure}


\noindent
This procedure is used when the iterator reaches its end.


\procdef{gen-list}


\startprocsyntax
\begin{codeblock}
  (gen-list l consumer iterator-inst)
\end{codeblock}


\typeparams{\typeparam{source}, \typeparam{target}}


\startprocarguments
\begin{arglist}
  \argument{l}{\code{(:uniform-list \typeparam{source})}}%
  {A list for which to create an iterator}
  \argument{consumer}{\code{(:consumer \typeparam{source} \typeparam{target})}}%
  {A consumer procedure}
  \argument{iterator-inst}{\code{(:iterator-inst \typeparam{source} %
      \typeparam{target})}}{An iterator instance}
\end{arglist}


\procresult{Target object}%
{\code{\typeparam{target}}}


\procpurity{pure}


\noindent
This procedure is used internally to create a list iterator.


\procdef{get-list-iterator}


\startprocsyntax
\begin{codeblock}
  (get-list-iterator l)
\end{codeblock}


\typeparams{\typeparam{source}}


\startprocarguments
\begin{arglist}
  \argument{l}{\code{(:uniform-list \typeparam{source})}}%
  {A list for which to create an iterator}
\end{arglist}


\procresult{An iterator for the given list}%
{\code{(:iterator \typeparam{source})}}


\procpurity{pure}


\noindent
This procedure is used to create a list iterator.


\procdef{gen-mutable-vector}


\startprocsyntax
\begin{codeblock}
  (gen-mutable-vector v consumer iterator-inst)
\end{codeblock}


\typeparams{\typeparam{source}, \typeparam{target}}


\startprocarguments
\begin{arglist}
  \argument{v}{\code{(:mutable-vector \typeparam{source})}}%
  {A mutable vector for which to create an iterator}
  \argument{consumer}{\code{(:consumer \typeparam{source} \typeparam{target})}}%
  {A consumer procedure}
  \argument{iterator-inst}{\code{(:iterator-inst \typeparam{source} %
      \typeparam{target})}}{An iterator instance}
\end{arglist}


\procresult{Target object}%
{\code{\typeparam{target}}}


\procpurity{pure}


\noindent
This procedure is used internally to create a mutable vector iterator.


\procdef{get-mutable-vector-iterator}


\startprocsyntax
\begin{codeblock}
  (get-mutable-vector-iterator v)
\end{codeblock}


\typeparams{\typeparam{source}}


\startprocarguments
\begin{arglist}
  \argument{v}{\code{(:mutable-vector \typeparam{source})}}%
  {A mutable vector for which to create an iterator}
\end{arglist}


\procresult{An iterator for the given mutable vector}%
{\code{(:iterator \typeparam{source})}}


\procpurity{pure}


\noindent
This procedure is used to create an iterator for a mutable vector.


\procdef{iter-map1}


\startprocsyntax
\begin{codeblock}
  (iter-map1 proc iterator)
\end{codeblock}


\typeparams{\typeparam{source}, \typeparam{component}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{source}) %
    \typeparam{component} pure)}}%
  {A procedure to apply to the given iterator}
  \argument{iterator}{\code{(:iterator \typeparam{source})}}%
  {An iterator to iterate the given procedure}
\end{arglist}


\procresult{A list constructed by applying the given procedure to the %
values yielded by the iterator}%
{\code{(:uniform-list \typeparam{component})}}


\procpurity{pure}


\noindent
This procedure maps the given procedure to each element yielded by the
iterator and constructs a list from the result values.


\procdef{iter-map2}


\startprocsyntax
\begin{codeblock}
  (iter-map2 proc iterator1 iterator2)
\end{codeblock}


\typeparams{\typeparam{source1}, \typeparam{source2}, %
  \typeparam{component}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{source1} %
      \typeparam{source2}) %
    \typeparam{component} pure)}}%
  {A procedure to apply to the given iterator}
  \argument{iterator1}{\code{(:iterator \typeparam{source1})}}%
  {An iterator to iterate the given procedure}
  \argument{iterator2}{\code{(:iterator \typeparam{source2})}}%
  {Another iterator to iterate the given procedure}
\end{arglist}


\procresult{A list constructed by applying the given procedure to the %
values yielded by the iterators}%
{\code{(:uniform-list \typeparam{component})}}


\procpurity{pure}


\noindent
This procedure maps pairwise the given procedure to all the elements
yielded by the iterators and constructs a list from the result values.


\procdef{iter-every1}


\startprocsyntax
\begin{codeblock}
  (iter-every1 proc iterator)
\end{codeblock}


\typeparams{\typeparam{source}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{source}) %
    <boolean> pure)}}%
  {A procedure to apply to the given iterator}
  \argument{iterator}{\code{(:iterator \typeparam{source})}}%
  {An iterator to iterate the given procedure}
\end{arglist}


\procresult{\true\ iff the procedure is returns true for all iterated values}%
{\code{<boolean>}}


\procpurity{pure}


\noindent
This procedure maps the given procedure to each element yielded by the
iterator and returns \true\ iff all the results are \true. If some
application returns \false\ the application is terminated and
\false\ returned.


\procdef{iter-every2}


\startprocsyntax
\begin{codeblock}
  (iter-every2 proc iterator1 iterator2)
\end{codeblock}


\typeparams{\typeparam{source1}, \typeparam{source2}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{source1} %
      \typeparam{source2}) %
    <boolean> pure)}}%
  {A procedure to apply to the given iterator}
  \argument{iterator1}{\code{(:iterator \typeparam{source1})}}%
  {An iterator to iterate the given procedure}
  \argument{iterator2}{\code{(:iterator \typeparam{source2})}}%
  {Another iterator to iterate the given procedure}
\end{arglist}


\procresult{\true\ iff the procedure is returns true for all iterated values}%
{\code{<boolean>}}


\procpurity{pure}


\noindent
This procedure maps pairwise the given procedure to all the elements
yielded by the iterators and returns \true\ iff all the results are
\true. If some application returns \false\ the application is
terminated and \false\ returned.


\chapter{Module \code{(standard-library nonpure-iterator)}}


This module nonpure implements nonpure iterators analogous to the
purely functional ones presented in the previous section.
Nonpure iterators are needed in following cases:
\begin{itemize}
  \item The operation done to the values yielded by iterators has side
    effects, e.g. printing.
  \item The generation of values for an iterator has side effects,
    e.g. reading values from a file.
\end{itemize}


\section{Data Types}


\begin{datatype}
  \datatypename{:nonpure-iterator}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{1}
  \datatypedef{(:param-proc (\%target) ((:nonpure-consumer \%source \%target)) %
    \%target nonpure)}
  \datatypedesc{An iterator}
\end{datatype}


\begin{datatype}
  \datatypename{:nonpure-iterator-inst}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{2}
  \datatypedef{(:procedure ((:nonpure-consumer \%source \%target)) %
    \%target nonpure)}
  \datatypedesc{An instance of an iterator for which the target type %
  or the iteration is fixed}
\end{datatype}


\begin{datatype}
  \datatypename{:nonpure-consumer}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{2}
  \datatypedef{(:procedure ((:maybe \%source) <boolean> %
    (:maybe (:nonpure-iterator-inst \%source \%target))) \%target nonpure)}
  \datatypedesc{A procedure that ``consumes'' values yielded by %
  an iterator}
\end{datatype}


\section{Parametrized Methods}


\procdef{nonpure-end-iter}


\startprocsyntax
\begin{codeblock}
  (nonpure-end-iter consumer)
\end{codeblock}


\typeparams{\typeparam{source}, \typeparam{target}}


\startprocarguments
\begin{arglist}
  \argument{consumer}{\code{(:nonpure-consumer \typeparam{source} \typeparam{target})}}%
  {A consumer procedure}
\end{arglist}


\procresult{Target object}%
{\code{\typeparam{target}}}


\procpurity{nonpure}


\noindent
This procedure is used when the iterator reaches its end.


\procdef{gen-list-nonpure}


\startprocsyntax
\begin{codeblock}
  (gen-list-nonpure l consumer iterator-inst)
\end{codeblock}


\typeparams{\typeparam{source}, \typeparam{target}}


\startprocarguments
\begin{arglist}
  \argument{l}{\code{(:uniform-list \typeparam{source})}}%
  {A list for which to create an iterator}
  \argument{consumer}{\code{(:nonpure-consumer \typeparam{source} \typeparam{target})}}%
  {A consumer procedure}
  \argument{iterator-inst}{\code{(:nonpure-iterator-inst \typeparam{source} %
      \typeparam{target})}}{An iterator instance}
\end{arglist}


\procresult{Target object}%
{\code{\typeparam{target}}}


\procpurity{nonpure}


\noindent
This procedure is used internally to create a list iterator.


\procdef{get-list-nonpure-iterator}


\startprocsyntax
\begin{codeblock}
  (get-list-nonpure-iterator l)
\end{codeblock}


\typeparams{\typeparam{source}}


\startprocarguments
\begin{arglist}
  \argument{l}{\code{(:uniform-list \typeparam{source})}}%
  {A list for which to create an iterator}
\end{arglist}


\procresult{An iterator for the given list}%
{\code{(:nonpure-iterator \typeparam{source})}}


\procpurity{nonpure}


\noindent
This procedure is used to create a list iterator.


\procdef{gen-mutable-vector-nonpure}


\startprocsyntax
\begin{codeblock}
  (gen-mutable-vector-nonpure v consumer iterator-inst)
\end{codeblock}


\typeparams{\typeparam{source}, \typeparam{target}}


\startprocarguments
\begin{arglist}
  \argument{v}{\code{(:mutable-vector \typeparam{source})}}%
  {A mutable vector for which to create an iterator}
  \argument{consumer}{\code{(:nonpure-consumer \typeparam{source} \typeparam{target})}}%
  {A consumer procedure}
  \argument{iterator-inst}{\code{(:nonpure-iterator-inst \typeparam{source} %
      \typeparam{target})}}{An iterator instance}
\end{arglist}


\procresult{Target object}%
{\code{\typeparam{target}}}


\procpurity{nonpure}


\noindent
This procedure is used internally to create a mutable vector iterator.


\procdef{get-mutable-vector-nonpure-iterator}


\startprocsyntax
\begin{codeblock}
  (get-mutable-vector-nonpure-iterator v)
\end{codeblock}


\typeparams{\typeparam{source}}


\startprocarguments
\begin{arglist}
  \argument{v}{\code{(:mutable-vector \typeparam{source})}}%
  {A mutable vector for which to create an iterator}
\end{arglist}


\procresult{An iterator for the given mutable vector}%
{\code{(:nonpure-iterator \typeparam{source})}}


\procpurity{nonpure}


\noindent
This procedure is used to create an iterator for a mutable vector.


\procdef{nonpure-iter-map1}


\startprocsyntax
\begin{codeblock}
  (nonpure-iter-map1 proc iterator)
\end{codeblock}


\typeparams{\typeparam{source}, \typeparam{component}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{source}) %
    \typeparam{component} nonpure)}}%
  {A procedure to apply to the given iterator}
  \argument{iterator}{\code{(:nonpure-iterator \typeparam{source})}}%
  {An iterator to iterate the given procedure}
\end{arglist}


\procresult{A list constructed by applying the given procedure to the %
values yielded by the iterator}%
{\code{(:uniform-list \typeparam{component})}}


\procpurity{nonpure}


\noindent
This procedure maps the given procedure to each element yielded by the
iterator and constructs a list from the result values.


\procdef{nonpure-iter-map2}


\startprocsyntax
\begin{codeblock}
  (nonpure-iter-map2 proc iterator1 iterator2)
\end{codeblock}


\typeparams{\typeparam{source1}, \typeparam{source2}, %
  \typeparam{component}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{source1} %
      \typeparam{source2}) %
    \typeparam{component} nonpure)}}%
  {A procedure to apply to the given iterator}
  \argument{iterator1}{\code{(:nonpure-iterator \typeparam{source1})}}%
  {An iterator to iterate the given procedure}
  \argument{iterator2}{\code{(:nonpure-iterator \typeparam{source2})}}%
  {Another iterator to iterate the given procedure}
\end{arglist}


\procresult{A list constructed by applying the given procedure to the %
values yielded by the iterators}%
{\code{(:uniform-list \typeparam{component})}}


\procpurity{nonpure}


\noindent
This procedure maps pairwise the given procedure to all the elements
yielded by the iterators and constructs a list from the result values.


\procdef{nonpure-iter-every1}


\startprocsyntax
\begin{codeblock}
  (nonpure-iter-every1 proc iterator)
\end{codeblock}


\typeparams{\typeparam{source}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{source}) %
    <boolean> nonpure)}}%
  {A procedure to apply to the given iterator}
  \argument{iterator}{\code{(:nonpure-iterator \typeparam{source})}}%
  {An iterator to iterate the given procedure}
\end{arglist}


\procresult{\true\ iff the procedure is returns true for all iterated values}%
{\code{<boolean>}}


\procpurity{nonpure}


\noindent
This procedure maps the given procedure to each element yielded by the
iterator and returns \true\ iff all the results are \true. If some
application returns \false\ the application is terminated and
\false\ returned.


\procdef{nonpure-iter-every2}


\startprocsyntax
\begin{codeblock}
  (nonpure-iter-every2 proc iterator1 iterator2)
\end{codeblock}


\typeparams{\typeparam{source1}, \typeparam{source2}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{source1} %
      \typeparam{source2}) %
    <boolean> nonpure)}}%
  {A procedure to apply to the given iterator}
  \argument{iterator1}{\code{(:nonpure-iterator \typeparam{source1})}}%
  {An iterator to iterate the given procedure}
  \argument{iterator2}{\code{(:nonpure-iterator \typeparam{source2})}}%
  {Another iterator to iterate the given procedure}
\end{arglist}


\procresult{\true\ iff the procedure is returns true for all iterated values}%
{\code{<boolean>}}


\procpurity{nonpure}


\noindent
This procedure maps pairwise the given procedure to all the elements
yielded by the iterators and returns \true\ iff all the results are
\true. If some application returns \false\ the application is
terminated and \false\ returned.


\procdef{nonpure-iter-for-each1}


\startprocsyntax
\begin{codeblock}
  (nonpure-iter-for-each1 proc iterator)
\end{codeblock}


\typeparams{\typeparam{source}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{source}) %
    <none> nonpure)}}%
  {A procedure to apply to the given iterator}
  \argument{iterator}{\code{(:nonpure-iterator \typeparam{source})}}%
  {An iterator to iterate the given procedure}
\end{arglist}


\noprocresult


\procpurity{nonpure}


\noindent
This procedure maps the given procedure to each element yielded by the
iterator.


\procdef{nonpure-iter-for-each2}


\startprocsyntax
\begin{codeblock}
  (nonpure-iter-for-each2 proc iterator1 iterator2)
\end{codeblock}


\typeparams{\typeparam{source1}, \typeparam{source2}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{source1} %
      \typeparam{source2}) %
    <none> nonpure)}}%
  {A procedure to apply to the given iterator}
  \argument{iterator1}{\code{(:nonpure-iterator \typeparam{source1})}}%
  {An iterator to iterate the given procedure}
  \argument{iterator2}{\code{(:nonpure-iterator \typeparam{source2})}}%
  {Another iterator to iterate the given procedure}
\end{arglist}


\noprocresult


\procpurity{nonpure}


\noindent
This procedure maps pairwise the given procedure to all the elements
yielded by the iterators.


\procdef{gen-generator}


\startprocsyntax
\begin{codeblock}
  (gen-generator generator terminate? consumer iterator-inst)
\end{codeblock}


\typeparams{\typeparam{source}, \typeparam{target}}


\startprocarguments
\begin{arglist}
  \argument{generator}{\code{(:procedure () \typeparam{source} nonpure)}}%
  {A generator from which to create an iterator}
  \argument{terminate?}{\code{(:procedure (\typeparam{source}) %
      <boolean> pure)}}%
  {A procedure that determines when to end the iteration}
  \argument{consumer}{\code{(:nonpure-consumer \typeparam{source} \typeparam{target})}}%
  {A consumer procedure}
  \argument{iterator-inst}{\code{(:nonpure-iterator-inst \typeparam{source} %
      \typeparam{target})}}{An iterator instance}
\end{arglist}


\procresult{Target object}%
{\code{\typeparam{target}}}


\procpurity{nonpure}


\noindent
This procedure is used internally to create an iterator from a generator.


\procdef{generator->iterator}


\startprocsyntax
\begin{codeblock}
  (generator->iterator generator terminate?)
\end{codeblock}


\typeparams{\typeparam{source}}


\startprocarguments
\begin{arglist}
  \argument{generator}{\code{(:procedure () \typeparam{source} nonpure)}}%
  {A generator from which to create an iterator}
  \argument{terminate?}{\code{(:procedure (\typeparam{source}) %
      <boolean> pure)}}%
  {A procedure that determines when to end the iteration}
\end{arglist}


\procresult{An iterator for the given generator}%
{\code{(:nonpure-iterator \typeparam{source})}}


\procpurity{nonpure}


\noindent
This procedure is used to create an iterator that obtains its values
from a generator.


\chapter{Module \code{(standard-library object-string-conversion)}}


This module contains procedures to compute string output for different
objects.


\section{Simple Methods}


\procdef{general-object->string}


\startprocsyntax
\begin{codeblock}
(general-object->string obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<object>}}{Any object}
\end{arglist}


\procresult{The name of the class of the object enclosed in square brackets}%
{\code{<string>}}


\procpurity{pure}


This procedure is used as the default implementation of generic
procedure \code{object->string} in case no explicit method is defined.


\procdef{boolean->string}


\startprocsyntax
\begin{codeblock}
(boolean->string obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<boolean>}}{A boolean value}
\end{arglist}


\procresult{\code{"\#t"} or \code{"\#f"}}%
{\code{<string>}}


\procpurity{pure}


\procdef{character->string}


\startprocsyntax
\begin{codeblock}
(character->string obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<character>}}{A character value}
\end{arglist}


\procresult{Return a string consisting of the given character}%
{\code{<string>}}


\procpurity{pure}


\procdef{integer->string}


\startprocsyntax
\begin{codeblock}
(integer->string obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{Output string for the given value}%
{\code{<string>}}


\procpurity{pure}


\procdef{null->string}


\startprocsyntax
\begin{codeblock}
(null->string obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<null>}}{\builtin{null}}
\end{arglist}


\procresult{\code{()}}%
{\code{<string>}}


\procpurity{pure}


\procdef{real->string}


\startprocsyntax
\begin{codeblock}
(real->string obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{Output string for the given value}%
{\code{<string>}}


\procpurity{pure}


\procdef{string->string}


\startprocsyntax
\begin{codeblock}
(string->string obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<string>}}{A string}
\end{arglist}


\procresult{The same string as the argument}%
{\code{<string>}}


\procpurity{pure}


\procdef{symbol->string}


\startprocsyntax
\begin{codeblock}
(symbol->string obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<symbol>}}{A symbol}
\end{arglist}


\procresult{Output string for the given value}%
{\code{<string>}}


\procpurity{pure}


\procdef{pair->string}


\startprocsyntax
\begin{codeblock}
(pair->string obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{p}{\builtin{<pair>}}{A pair}
\end{arglist}


\procresult{Output string for the given value}%
{\code{<string>}}


\procpurity{pure}


This procedure converts pairs, lists and tree structures implemented with
pairs to strings.  Method \code{object->string} is called recursively
for the contents.  This procedure should be safe for cyclic structures.


\procdef{string->symbol}


\startprocsyntax
\begin{codeblock}
  (string->symbol \procarg{str})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
\end{arglist}


\procresult{The argument string converted to a symbol}%
{\builtin{<symbol>}}


\procpurity{pure}


\procdef{string->integer}


\startprocsyntax
\begin{codeblock}
  (string->integer \procarg{str})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
\end{arglist}


\procresult{The argument string converted to an integer}%
{\builtin{<integer>}}


\procpurity{pure}


If the string cannot be converted to an integer an RTE exception is
raised.

\procdef{string->real}


\startprocsyntax
\begin{codeblock}
  (string->real \procarg{str})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
\end{arglist}


\procresult{The argument string converted to a real}%
{\builtin{<real>}}


\procpurity{pure}


If the string cannot be converted to a real an RTE exception is
raised.


\section{Virtual Methods}

\indexmethod{object->string}

\noindent
\puremethoddefwithvalue{object->string}{<object>}{<string>}%
                   {general-object->string}
\puremethoddefwithvalue{object->string}{<integer>}{<string>}%
                   {integer->string}
\puremethoddefwithvalue{object->string}{<real>}{<string>}%
                   {real->string}
\puremethoddefwithvalue{object->string}{<string>}{<string>}%
                   {string->string}
\puremethoddefwithvalue{object->string}{<symbol>}{<string>}%
                   {symbol->string}
\puremethoddefwithvalue{object->string}{<null>}{<string>}%
                   {null->string}
\puremethoddefwithvalue{object->string}{<character>}{<string>}%
                   {character->string}
\puremethoddefwithvalue{object->string}{<boolean>}{<string>}%
                   {boolean->string}
\puremethoddefwithvalue{object->string}{<pair>}{<string>}%
                   {pair->string}


\chapter{Module \code{(standard-library bytevector)}}


\section{Data Types}


\begin{datatype}
  \datatypename{<bytevector>}
  \datatypetype{\builtin{<class>}}
  \datatypedesc{A vector of bytes}
\end{datatype}


\section{Simple Methods}


\procdef{make-bytevector}


\startprocsyntax
\begin{codeblock}
(make-bytevector length fill)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{length}{\builtin{<integer>}}{The length of the new %
    bytevector}
  \argument{fill}{\builtin{<integer>}}{The value to fill the %
    bytevector}
\end{arglist}


\procresult{A new bytevector}%
{\code{<bytevector>}}


\procpurity{pure}


Argument \code{fill} has to be in range -128 ... 255.


\procdef{bytevector}


\startprocsyntax
\begin{codeblock}
(bytevector byte-1 ... byte-n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{byte-k}{\builtin{<integer>}}{The contents of the new %
    bytevector}
\end{arglist}


\procresult{A new bytevector}%
{\code{<bytevector>}}


\procpurity{pure}


Arguments \code{byte-k} have to be in range 0 ... 255.


\procdef{native-endianness}


\startprocsyntax
\begin{codeblock}
(native-endianness)
\end{codeblock}


\noprocarguments


\procresult{The native endianness of the system}%
{\code{<symbol>}}


\procpurity{pure}


This procedure returns a symbol describing the native endianness of
the system. The value can be e.g. \code{little} or \code{big}.


\procdef{bytevector-copy}


\startprocsyntax
\begin{codeblock}
(bytevector-copy bytevector)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\builtin{<bytevector>}}{The bytevector to copy}
\end{arglist}


\procresult{A new bytevector}%
{\code{<bytevector>}}


\procpurity{pure}


This procedure creates a copy of the given bytevector.


\procdef{bytevector-length}


\startprocsyntax
\begin{codeblock}
(bytevector-length bytevector)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\builtin{<bytevector>}}{A bytevector}
\end{arglist}


\procresult{The length of the bytevector}%
{\code{<integer>}}


\procpurity{pure}


\procdefexcl{bytevector-fill!}{bytevector-fill{"!}}


\startprocsyntax
\begin{codeblock}
(bytevector-fill! bytevector value)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\builtin{<bytevector>}}{A bytevector}
  \argument{value}{\builtin{<integer>}}{An integer}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure fills the bytevector with the given byte.


\procdefexcl{bytevector-copy!}{bytevector-copy{"!}}


\startprocsyntax
\begin{codeblock}
(bytevector-copy! source source-start target target-start count)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{source}{\builtin{<bytevector>}}{A bytevector to copy from}
  \argument{source-start}{\builtin{<integer>}}{Source index to start copying}
  \argument{target}{\builtin{<bytevector>}}{A bytevector where to copy}
  \argument{target-start}{\builtin{<integer>}}{Target index to start copying}
  \argument{count}{\builtin{<integer>}}{Number of bytes to copy}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure copies \code{count} bytes from the source into the
target. The source and the target may overlap.


\procdef{u8-list->bytevector}


\startprocsyntax
\begin{codeblock}
(u8-list->bytevector lst)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list <integer>)}}{A list of bytes}
\end{arglist}


\procresult{A bytevector}%
{\code{<bytevector>}}


\procpurity{pure}


This procedure creates the bytevector consisting of the elements of
the list. The values of the list have to be in range 0 ... 255.


\procdef{bytevector->u8-list}


\startprocsyntax
\begin{codeblock}
(bytevector->u8-list bytevector)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector}
\end{arglist}


\procresult{A list of integers}%
{\code{(:uniform-list <integer>)}}


\procpurity{pure}


This procedure creates a list consisting of the elements of the bytevector.


\procdef{bytevector-u8-ref}


\startprocsyntax
\begin{codeblock}
(bytevector-u8-ref bytevector index)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector}
  \argument{index}{\code{<integer>}}{The index where to fetch the value}
\end{arglist}


\procresult{The element at position \code{index} interpreted as %
  an unsigned value}%
{\code{<integer>}}


\procpurity{pure}


\procdef{bytevector-s8-ref}


\startprocsyntax
\begin{codeblock}
(bytevector-s8-ref bytevector index)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector}
  \argument{index}{\code{<integer>}}{The index where to fetch the value}
\end{arglist}


\procresult{The element at position \code{index} interpreted as %
  a signed value}%
{\code{<integer>}}


\procpurity{pure}


\procdefa{bytevector-u16-ref}

\procdefa{bytevector-s16-ref}

\procdefa{bytevector-u32-ref}

\procdefa{bytevector-s32-ref}

\procdefa{bytevector-u64-ref}

\procdefa{bytevector-s64-ref}

\startprocsyntax
\begin{codeblock}
(bytevector-xxx-ref bytevector index endianness)
\end{codeblock}

\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector}
  \argument{index}{\code{<integer>}}{The index where to fetch the %
    value}
  \argument{endianness}{\code{<symbol>}}{The endianness of the %
    bytevector}
\end{arglist}


\procresult{The element at position \code{index} interpreted as %
  an integer value}%
{\code{<integer>}}


\procpurity{pure}


These procedures fetch unsigned or signed integer values from a
bytevector.


\procdefexcl{bytevector-u8-set!}{bytevector-u8-set{"!}}


\startprocsyntax
\begin{codeblock}
(bytevector-u8-set! bytevector index value)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector}
  \argument{index}{\code{<integer>}}{The index where to set the value}
  \argument{value}{\code{<integer>}}{The value to set}
\end{arglist}


\noprocresult


\procpurity{nonpure}


The value has to be in range 0 ... 255.


\procdefexcl{bytevector-s8-set!}{bytevector-s8-set{"!}}


\startprocsyntax
\begin{codeblock}
(bytevector-s8-set! bytevector index value)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector}
  \argument{index}{\code{<integer>}}{The index where to set the value}
  \argument{value}{\code{<integer>}}{The value to set}
\end{arglist}


\noprocresult


\procpurity{nonpure}


The value has to be in range -128 ... 127.

\vspace{0.5cm}

\procdefexcla{bytevector-u16-set!}{bytevector-u16-set{"!}}

\procdefexcla{bytevector-s16-set!}{bytevector-s16-set{"!}}

\procdefexcla{bytevector-u32-set!}{bytevector-u32-set{"!}}

\procdefexcla{bytevector-s32-set!}{bytevector-s32-set{"!}}

\procdefexcla{bytevector-u64-set!}{bytevector-u64-set{"!}}

\procdefexcla{bytevector-s64-set!}{bytevector-s64-set{"!}}


\startprocsyntax
\begin{codeblock}
(bytevector-xxx-set! bytevector index value endianness)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector}
  \argument{index}{\code{<integer>}}{The index where to set the value}
  \argument{value}{\code{<integer>}}{The value to set}
  \argument{endianness}{\code{<symbol>}}{The endianness of the bytevector}
\end{arglist}


\noprocresult


\procpurity{nonpure}


\procdef{bytevector-ieee-single-ref}


\startprocsyntax
\begin{codeblock}
(bytevector-ieee-single-ref bytevector index endianness)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector}
  \argument{index}{\code{<integer>}}{The index where to fetch the %
    value}
  \argument{endianness}{\code{<symbol>}}{The endianness of the %
    bytevector}
\end{arglist}


\procresult{The element at position \code{index} interpreted as %
  an IEEE single real value}%
{\code{<real>}}


\procpurity{pure}


\procdef{bytevector-ieee-double-ref}


\startprocsyntax
\begin{codeblock}
(bytevector-ieee-double-ref bytevector index endianness)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector}
  \argument{index}{\code{<integer>}}{The index where to fetch the %
    value}
  \argument{endianness}{\code{<symbol>}}{The endianness of the %
    bytevector}
\end{arglist}


\procresult{The element at position \code{index} interpreted as %
  an IEEE double real value}%
{\code{<real>}}


\procpurity{pure}


\procdefexcl{bytevector-ieee-single-set!}{bytevector-ieee-single-set{"!}}


\startprocsyntax
\begin{codeblock}
(bytevector-ieee-single-set! bytevector index value endianness)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector}
  \argument{index}{\code{<integer>}}{The index where to set the %
    value}
  \argument{value}{\code{<real>}}{The value to set}
  \argument{endianness}{\code{<symbol>}}{The endianness of the %
    bytevector}
\end{arglist}


\noprocresult


\procpurity{nonpure}


\procdefexcl{bytevector-ieee-double-set!}{bytevector-ieee-double-set{"!}}


\startprocsyntax
\begin{codeblock}
(bytevector-ieee-double-set! bytevector index value endianness)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector}
  \argument{index}{\code{<integer>}}{The index where to set the %
    value}
  \argument{value}{\code{<real>}}{The value to set}
  \argument{endianness}{\code{<symbol>}}{The endianness of the %
    bytevector}
\end{arglist}


\noprocresult


\procpurity{nonpure}


\procdef{string->utf8}


\startprocsyntax
\begin{codeblock}
(string->utf8 str)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\code{<string>}}{A string}
\end{arglist}


\procresult{The string converted to UTF-8}{\code{<bytevector>}}


\procpurity{pure}


\procdef{string->utf16}


\startprocsyntax
\begin{codeblock}
(string->utf16 str endianness)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\code{<string>}}{A string}
  \argument{endianness}{\code{<symbol>}}{The endianness of the string}
\end{arglist}


\procresult{The string converted to UTF-16}{\code{<bytevector>}}


\procpurity{pure}


\procdef{string->utf32}


\startprocsyntax
\begin{codeblock}
(string->utf32 str endianness)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\code{<string>}}{A string}
  \argument{endianness}{\code{<symbol>}}{The endianness of the string}
\end{arglist}


\procresult{The string converted to UTF-32}{\code{<bytevector>}}


\procpurity{pure}


\procdef{utf8->string}


\startprocsyntax
\begin{codeblock}
(utf8->string bytevector)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector containing UTF-8 data}
\end{arglist}


\procresult{The UTF-8 data converted to string}{\code{<string>}}


\procpurity{pure}


\procdef{utf16->string}


\startprocsyntax
\begin{codeblock}
(utf16->string bytevector endiannedd)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector containing UTF-16 %
    data}
  \argument{endianness}{\code{<symbol>}}{The endianness of the bytevector}
\end{arglist}


\procresult{The UTF-16 data converted to string}{\code{<string>}}


\procpurity{pure}


\procdef{utf32->string}


\startprocsyntax
\begin{codeblock}
(utf16->string bytevector endiannedd)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{bytevector}{\code{<bytevector>}}{A bytevector containing UTF-32 %
    data}
  \argument{endianness}{\code{<symbol>}}{The endianness of the bytevector}
\end{arglist}


\procresult{The UTF-32 data converted to string}{\code{<string>}}


\procpurity{pure}


\chapter{Module \code{(standard-library files)}}


\section{Data Types}


\begin{datatype}
  \datatypename{<eof>}
  \datatypetype{\builtin{<class>}}
  \datatypedesc{The class of an end-of-file object. %
  The behaviour of end-of-file objects follows R7RS \cite{shinn2017}.}
\end{datatype}


\begin{datatype}
  \datatypename{<input-port>}
  \datatypetype{\builtin{<class>}}
  \datatypedesc{An input port (input file)}
\end{datatype}


\begin{datatype}
  \datatypename{<output-port>}
  \datatypetype{\builtin{<class>}}
  \datatypedesc{An output port (output file)}
\end{datatype}


\section{Simple Methods}


\procdef{make-eof}


\startprocsyntax
\begin{codeblock}
  \noindent
  \slp
  make-eof
  \srp
\end{codeblock}


\noprocarguments


\procresult{And end-of-file object}{\code{<eof>}}


\procpurity{nonpure}


This procedure returns an end-of-file object. See the start of this
section.  This procedure is not pure since R7RS \cite{shinn2017} does
not guarantee the purity of the Scheme procedure \code{eof-object}.


\procdef{eof?}


\startprocsyntax
\begin{codeblock}
(eof? obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<object>}}{An arbitrary object}
\end{arglist}


\procresult{\true\ iff \code{obj} is an eof object}%
{\code{<boolean>}}


\procpurity{pure}


\procdef{open-input-file}


\startprocsyntax
\begin{codeblock}
(open-input-file filename)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{filename}{\builtin{<string>}}{Name of the file to be opened}
\end{arglist}


\procresult{An object representing the opened file}%
{\code{<input-port>}}


This procedures opens an input file. If the operations fails an
exception \code{(io-error error-opening-input-file
  \textrm{\textit{filename}})} is raised.


\procdef{open-output-file}


\startprocsyntax
\begin{codeblock}
(open-output-file filename)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{filename}{\builtin{<string>}}{Name of the file to be opened}
\end{arglist}


\procresult{An object representing the opened file}%
{\code{<output-port>}}


This procedures opens an output file. If the operations fails an
exception \code{(io-error error-opening-output-file
  \textrm{\textit{filename}})} is raised.


\procdef{close-input-port}


\startprocsyntax
\begin{codeblock}
(close-input-port input-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\builtin{<input-port>}}{The input port to be closed}
\end{arglist}


\noprocresult


\procdef{close-output-port}


\startprocsyntax
\begin{codeblock}
(close-output-port output-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{output-port}{\builtin{<output-port>}}{The output port to be closed}
\end{arglist}


\noprocresult


\procdef{flush-all-ports}


\startprocsyntax
\begin{codeblock}
  \noindent
  \slp
  flush-all-ports
  \srp
\end{codeblock}


\noprocarguments


\noprocresult


\procpurity{nonpure}


Flush all ports.


\chapter{Module \code{(standard-library text-file-io)}}


This module implements input and output for text files.  This module
also reexports module \code{(standard-library files)}.


\section{Simple Methods}


\procdef{character-ready?}


\startprocsyntax
\begin{codeblock}
(character-ready? input-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\builtin{<input-port>}}{The input port to check}
\end{arglist}


\procresult{\true\ iff there is a character ready in the given input port}%
{\builtin{<boolean>}}


On i/o error exception
\code{(io-error character-ready?:runtime-error \textrm{\textit{filename}})}
is raised.


\procdef{current-input-port}


\startprocsyntax
\begin{codeblock}
(current-input-port)
\end{codeblock}


\noprocarguments


\procresult{The current input port}%
{\builtin{<input-port>}}


\procdef{current-output-port}


\startprocsyntax
\begin{codeblock}
(current-output-port)
\end{codeblock}


\noprocarguments


\procresult{The current output port}%
{\builtin{<output-port>}}


\procdef{write-character}


\startprocsyntax
\begin{codeblock}
(write-character output-port ch)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{output-port}{\builtin{<output-port>}}{An output port where
    to write}
  \argument{ch}{\builtin{<character>}}{A character to be written}
\end{arglist}


\noprocresult


This procedure writes the external representation of a charactor in
the specified output port.
If the
operation fails an exception
\code{(io-error error-displaying-object
  \textrm{\textit{filename}})}
is raised.


\procdef{write-string}


\startprocsyntax
\begin{codeblock}
(write-string output-port str)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{output-port}{\builtin{<output-port>}}{An output port where
    to write}
  \argument{str}{\builtin{<string>}}{A string to be written}
\end{arglist}


\noprocresult


This procedure writes the external representation of a string into the
specified output port.
If the
operation fails an exception
\code{(io-error error-displaying-object
  \textrm{\textit{filename}})}
is raised.


\procdef{write-line}


\startprocsyntax
\begin{codeblock}
(write-line output-port obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{output-port}{\builtin{<output-port>}}{An output port where
    to write}
  \argument{obj}{\builtin{<object>}}{An object to be written}
\end{arglist}


\noprocresult


This function uses the generic procedure \code{write} to to write the
object and prints a newline after that.


\procdef{display-character}


\startprocsyntax
\begin{codeblock}
(display-character output-port ch)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{output-port}{\builtin{<output-port>}}{An output port where
    to display}
  \argument{ch}{\builtin{<character>}}{A character to be displayed}
\end{arglist}


\noprocresult


This procedure displays a character into the given output port.
If the
operation fails an exception
\code{(io-error error-displaying-object
  \textrm{\textit{filename}})}
is raised.


\procdef{display-string}


\startprocsyntax
\begin{codeblock}
(display-string output-port str)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{output-port}{\builtin{<output-port>}}{An output port where
    to display}
  \argument{str}{\builtin{<string>}}{A string to be displayed}
\end{arglist}


\noprocresult


This procedure displays a string into the given output port. If the
operation fails an exception
\code{(io-error error-displaying-object
  \textrm{\textit{filename}})}
is raised.


\procdef{display-line}


\startprocsyntax
\begin{codeblock}
(display-line output-port obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{output-port}{\builtin{<output-port>}}{An output port where
    to display}
  \argument{obj}{\builtin{<object>}}{An object to be displayed}
\end{arglist}


\noprocresult


This function uses the generic procedure \code{display} to display the
object and prints a newline.


\procdef{newline}


\startprocsyntax
\begin{codeblock}
(newline output-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{output-port}{\builtin{<output-port>}}{An output port where to print}
\end{arglist}


\noprocresult


This procedure prints a newline to the given output port. If the
operation fails an exception \code{(io-error
  error-displaying-newline \textrm{\textit{filename}})}
is raised.


\procdef{peek-character}


\startprocsyntax
\begin{codeblock}
(peek-character input-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\builtin{<input-port>}}%
           {An input port where to read from}
\end{arglist}


\procresult{The read character or an eof object}%
{\code{(\cbuiltin{:union} \cbuiltin{<character>} \cbuiltin{<eof>})}}


This procedure peeks a character from an input port. On i/o error an
exception \code{(io-error peek-character:io-error
  \textrm{\textit{filename}})} is raised.


\procdef{read}


\startprocsyntax
\begin{codeblock}
(read input-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\builtin{<input-port>}}{An input port where to read from}
\end{arglist}


\procresult{The object read or an eof object}%
{\builtin{<object>}}


This procedure reads a \theme\ expression from an input port.  The
\theme\ runtime environment checks that the result object does not
contain any data types unknown to \theme.  On i/o error an exception
\code{(io-error read:io-error \textrm{\textit{filename}})} is
raised.  If a Scheme vector constant is encountered in the data raise
exception \code{(io-error io:illegal-vector
  \textrm{\textit{filename}})}.  If a Scheme complex number is
encountered in the data raise exception \code{(io-error
  io:illegal-complex-number \textrm{\textit{filename}})}.  On some
other Scheme object whose data type is not known by \theme\ raise
exception \code{(io-error io:illegal-data-type
  \textrm{\textit{filename}})}.


\procdef{read-all}


\startprocsyntax
\begin{codeblock}
(read-all input-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\builtin{<input-port>}}%
           {An input port where to read from}
\end{arglist}


\procresult{The objects read}%
{\builtin{<object>}}


This procedure uses procedure \code{read} to read all the expressions
from the given input-port.


\procdef{read-character}


\startprocsyntax
\begin{codeblock}
(read-character input-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\builtin{<input-port>}}{An input port where to read from}
\end{arglist}


\procresult{The read character or an eof object}%
{\code{(\cbuiltin{:union} \cbuiltin{<character>} \cbuiltin{<eof>})}}


This procedure reads a character from an input port.
On i/o error an
exception \code{(io-error read-character:io-error
  \textrm{\textit{filename}})} is raised.


\procdef{read-line}


\startprocsyntax
\begin{codeblock}
(read-line input-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\builtin{<input-port>}}%
           {An input port where to read from}
\end{arglist}


\procresult{Contents of a line}%
{\builtin{<string>}}


This procedure reads s single line from the given input port as a string.
On i/o error an
exception \code{(io-error read-character:io-error
  \textrm{\textit{filename}})} is raised.


\procdef{read-string}


\startprocsyntax
\begin{codeblock}
(read-string input-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\builtin{<input-port>}}%
           {An input port where to read from}
\end{arglist}


\procresult{The contents of the file}%
{\builtin{<string>}}


This procedure reads the contents of the given input port as a single
string.


\procdef{call-with-input-string}


\startprocsyntax
\begin{codeblock}
(call-with-input-string str proc)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string where to read from}
  \argument{proc}{\code{(:procedure (<input-port>) <object>
      nonpure)}}%
  {A procedure to call}
\end{arglist}


\procresult{The object returned by the procedure}%
{\builtin{<object>}}


This procedure creates an input port whose input comes from the
argument string and passes it to the given procedure.


\procdef{call-with-output-string}


\startprocsyntax
\begin{codeblock}
(call-with-output-string proc)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<output-port>) <none> %
      nonpure)}}%
  {A procedure to call}
\end{arglist}


\procresult{A string consisting of the output of the procedure}%
{\builtin{<string>}}


This procedure creates an output port and passes it to the given
procedure. A string consisting of the output of the procedure into the
port is returned.


\section{Virtual Methods}

\indexmethod{display}

\noindent
\methoddef{display}{<output-port> <object>}{<none>}
\methoddef{display}{<output-port> <null>}{<none>}
\methoddef{display}{<output-port> <boolean>}{<none>}
\methoddef{display}{<output-port> <integer>}{<none>}
\methoddef{display}{<output-port> <real>}{<none>}
\methoddef{display}{<output-port> <string>}{<none>}
\methoddef{display}{<output-port> <character>}{<none>}
\methoddef{display}{<output-port> <symbol>}{<none>}
\methoddef{display}{<output-port> <pair>}{<none>}

These methods display an object as a string in the specified port.

\indexmethod{write}

\noindent
\methoddef{write}{<output-port> <object>}{<none>}
\methoddef{write}{<output-port> <null>}{<none>}
\methoddef{write}{<output-port> <boolean>}{<none>}
\methoddef{write}{<output-port> <integer>}{<none>}
\methoddef{write}{<output-port> <real>}{<none>}
\methoddef{write}{<output-port> <string>}{<none>}
\methoddef{write}{<output-port> <character>}{<none>}
\methoddef{write}{<output-port> <symbol>}{<none>}
\methoddef{write}{<output-port> <pair>}{<none>}

These methods write the external representation of an object to the
specified port for primitive objects.


You may define methods \code{write} and \code{display} for your own
classes. It is usually better to define method \code{object->string}
instead of method \code{display}.  Note that generic procedure
\code{write} calls \code{display} by default.


\chapter{Module \code{(standard-library console-io)}}


This module implements input and output for the standard input and
standard output.


\section{Simple Methods}


\procdef{console-character-ready?}


\startprocsyntax
\begin{codeblock}
(console-character-ready?)
\end{codeblock}


\noprocarguments


\procresult{\true\ iff there is a character ready in the standard input}%
{\builtin{<boolean>}}


\procdef{console-display}


\startprocsyntax
\begin{codeblock}
(console-display obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<object>}}{An object to be displayed}
\end{arglist}


\noprocresult


This function uses the procedure \code{atom-to-string} to
obtain the string representation of the object and displays the
string with procedure \code{console-display-string}.


\procdef{console-display-character}


\startprocsyntax
\begin{codeblock}
(console-display-character ch)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{ch}{\builtin{<character>}}{A character to be displayed}
\end{arglist}


\noprocresult


\procdef{console-display-line}


\startprocsyntax
\begin{codeblock}
(console-display-line obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<object>}}{An object to be displayed}
\end{arglist}


\noprocresult


This function uses the procedure \code{atom-to-string} to
obtain the string representation of the object and displays the
string with procedure \code{console-display-string}.
A newline is displayed after the object.


\procdef{console-display-string}


\startprocsyntax
\begin{codeblock}
(console-display-string str)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string to be displayed}
\end{arglist}


\noprocresult


\procdef{console-newline}


\startprocsyntax
\begin{codeblock}
(console-newline)
\end{codeblock}


\noprocarguments


\noprocresult


This procedure prints a newline to the standard output.


\procdef{console-read}


\startprocsyntax
\begin{codeblock}
(console-read)
\end{codeblock}


\noprocarguments


\procresult{The object read or an eof object}%
{\builtin{<object>}}


The \theme\ runtime environment checks that the result object does not
contain any data types unknown to \theme.


\procdef{console-read-character}


\startprocsyntax
\begin{codeblock}
(console-read-character)
\end{codeblock}


\noprocarguments


\procresult{The read character or an eof object}%
{\code{(\cbuiltin{:union} \cbuiltin{<character>} \cbuiltin{<eof>})}}


This procedure reads a character from the standard input.


\procdef{console-write}


\startprocsyntax
\begin{codeblock}
(console-write obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<object>}}{An object to be written}
\end{arglist}


\noprocresult


This function uses the procedure \code{atom-to-string} to
obtain the source code representation of the object and displays the
string with procedure \code{console-display-string}.


\procdef{console-write-line}


\startprocsyntax
\begin{codeblock}
(console-write-line obj)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<object>}}{An object to be written}
\end{arglist}


\noprocresult


This function uses the procedure \code{atom-to-string} to
obtain the source code representation of the object and displays the
string with procedure \code{console-display-string}.
A newline is written after the object.


\chapter{Module \code{(standard-library binary-file-io)}}


This module implements input and output for binary files.  This module
also reexports module \code{(standard-library files)}. The input
procedures return generally an EOF if there is nothing to read in the
input port.


\section{Simple Methods}


\procdef{get-u8}


\startprocsyntax
\begin{codeblock}
  (get-u8 input-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\code{<input-port>}}%
  {The input port to read}
\end{arglist}


\procresult{A byte read from the input port}%
{\code{(:union <integer> <eof>)}}


\procpurity{nonpure}


\procdef{lookahead-u8}


\startprocsyntax
\begin{codeblock}
  (lookahead-u8 input-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\code{<input-port>}}%
  {The input port to read}
\end{arglist}


\procresult{A byte read from the input port}%
{\code{(:union <integer> <eof>)}}


\procpurity{nonpure}


This procedure reads a byte from the input stream without advancing
the file position.


\procdef{get-bytevector-n}


\startprocsyntax
\begin{codeblock}
  (get-bytevector-n input-port count)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\code{<input-port>}}%
           {The input port to read}
  \argument{count}{\code{<integer>}}{number of bytes to read}
\end{arglist}


\procresult{A bytevector read from the input port}%
{\code{(:union <bytevector> <eof>)}}


\procpurity{nonpure}


This procedure reads at most \code{count} bytes from the input port.


\procdefexcl{get-bytevector-n!}{get-bytevector-n{"!}}


\startprocsyntax
\begin{codeblock}
  (get-bytevector-n! input-port bytevector start count)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\code{<input-port>}}%
           {The input port to read}
  \argument{bytevector}{\code{<bytevector>}}%
  {bytevector where to read}
  \argument{start}{\code{<integer>}}{index where to start reading bytes}
  \argument{count}{\code{<integer>}}{number of bytes to read}
\end{arglist}


\procresult{The number of bytes read or EOF}%
{\code{(:union <integer> <eof>)}}


\procpurity{nonpure}


This procedure reads at most \code{count} bytes from the input port.


\procdef{get-bytevector-some}


\startprocsyntax
\begin{codeblock}
  (get-bytevector-some input-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\code{<input-port>}}%
           {The input port to read}
\end{arglist}


\procresult{A bytevector read from the input port}%
{\code{(:union <bytevector> <eof>)}}


\procpurity{nonpure}


This procedure reads some bytes from the input port.


\procdefexcl{get-bytevector-some!}{get-bytevector-some{"!}}


\startprocsyntax
\begin{codeblock}
  (get-bytevector-some! input-port bytevector start count)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\code{<input-port>}}%
           {The input port to read}
  \argument{bytevector}{\code{<bytevector>}}%
  {bytevector where to read}
  \argument{start}{\code{<integer>}}{index where to start reading bytes}
  \argument{count}{\code{<integer>}}{number of bytes to read}
\end{arglist}


\procresult{The number of bytes read or EOF}%
{\code{(:union <integer> <eof>)}}


\procpurity{nonpure}


This procedure reads at most \code{count} bytes from the input port.


\procdef{get-bytevector-all}


\startprocsyntax
\begin{codeblock}
  (get-bytevector-all input-port)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\code{<input-port>}}%
           {The input port to read}
\end{arglist}


\procresult{A bytevector read from the input port}%
{\code{(:union <bytevector> <eof>)}}


\procpurity{nonpure}


This procedure reads all the bytes from the input port unti
end-of-file is reached. If no data is available EOF is returned.


\procdef{unget-bytevector}


\startprocsyntax
\begin{codeblock}
  (unget-bytevector input-port bytevector start count)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{input-port}{\code{<input-port>}}%
           {The input port to read}
  \argument{bytevector}{\code{<bytevector>}}%
  {bytevector to unget}
  \argument{start}{\code{<integer>}}{index where to start reading bytes}
  \argument{count}{\code{<integer>}}{number of bytes to read}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure puts \code{count} bytes from \code{bytevector} starting from
index \code{start} into the input port so that the inserted bytes are
available for the subsequent read operations.


\procdef{put-u8}


\startprocsyntax
\begin{codeblock}
  (put-u8 output-port octet)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{output-port}{\code{<output-port>}}%
           {The output port to write}
  \argument{octet}{\code{<integer>}}%
  {octet to write}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure writes the octet into the output port.


\procdef{put-bytevector}


\startprocsyntax
\begin{codeblock}
  (put-bytevector output-port bytevector start count)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{output-port}{\code{<output-port>}}%
           {The output port to write}
  \argument{bytevector}{\code{<bytevector>}}%
  {bytevector where to take the octets}
  \argument{start}{\code{<integer>}}{index where to start}
  \argument{count}{\code{<integer>}}{number of bytes to write}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure writes \code{count} bytes starting from index
\code{start} into the output port.


\procdef{put-whole-bytevector}


\startprocsyntax
\begin{codeblock}
  (put-whole-bytevector output-port bytevector)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{output-port}{\code{<output-port>}}%
           {The output port to write}
  \argument{bytevector}{\code{<bytevector>}}%
  {bytevector where to take the octets}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure writes the contents of the bytevector into the output
port.


\chapter{Module \code{(standard-library system)}}


\section{Simple Methods}


\procdef{delete-file}


\startprocsyntax
\begin{codeblock}
  (delete-file str-filename)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str-filename}{\builtin{<string>}}%
  {The name of the file to be deleted}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure deletes the named file. If the file does not exist an
exception in raised.


\procdef{file-exists?}


\startprocsyntax
\begin{codeblock}
  (file-exists? str-filename)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str-filename}{\builtin{<string>}}%
  {The name of the file}
\end{arglist}


\procresult{Returns \true\ iff the file exists}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{getenv}


\startprocsyntax
\begin{codeblock}
  (getenv str-var-name)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str-var-name}{\builtin{<string>}}%
  {The name of the environment variable}
\end{arglist}


\procresult{The value of the given environment variable}%
{\code{(:alt-maybe <string>)}}


\procpurity{pure}


If the environment variable does not exist return \code{\#f}.


\procdef{setenv}


\startprocsyntax
\begin{codeblock}
  (setenv str-var-name str-value)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str-var-name}{\builtin{<string>}}%
  {The name of the environment variable}
  \argument{str-value}{\builtin{(:alt-maybe <string>)}}%
  {The new value of the environment variable}
\end{arglist}


\noprocresult


\procpurity{nonpure}


If \code{str-value} is \code{\#f} remove the variable from the current
environment.


\chapter{Module \code{(standard-library rational)}}


\section{Data Types}


\begin{datatype}
  \datatypename{<rational>}
  \datatypetype{\builtin{<class>}}
  \datatypedesc{A rational number}
\end{datatype}

\vspace{0.5cm}
Class \code{<rational>} is immutable, equal by value, and not
inheritable.

\begin{datatype}
  \datatypename{<rational-number>}
  \datatypetype{\builtin{:union}}
  \datatypedesc{A rational valued number}
\end{datatype}

\vspace{0.5cm}
Type \code{<rational-number>} is equal to the union of
\code{<rational>} and \code{<integer>}.


\section{Simple Methods}


\procdef{rational}


\startprocsyntax
\begin{codeblock}
(rational i-numer i-denom)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i-numer}{\builtin{<integer>}}{The numerator}
  \argument{i-denom}{\builtin{<integer>}}{The denominator}
\end{arglist}


\procresult{The quotient of \code{i-numer} and \code{i-denom}}%
{\builtin{<rational>}}


\procpurity{pure}


This procedure returns the rational number in simplified form. If the
denominator is zero a numerical overflow exception is raised.


\procdef{numerator}


\startprocsyntax
\begin{codeblock}
(numerator rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational number}
\end{arglist}


\procresult{The numerator of the argument}{\builtin{<integer>}}


\procpurity{pure}


\procdef{denominator}


\startprocsyntax
\begin{codeblock}
(denominator rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational number}
\end{arglist}


\procresult{The denominator of the argument}{\builtin{<integer>}}


\procpurity{pure}


\procdef{rational=?}


\startprocsyntax
\begin{codeblock}
(rational=? rat1 rat2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat1}{\code{<rational>}}{A rational value to be compared}
  \argument{rat2}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat1} is equal to \code{rat2}}%
{\builtin{<boolean>}}


\procpurity{pure}


Rational numbers \(a/b\) and \(c/d\) are equal iff \(ad = bc\).


\procdef{rational=}


\startprocsyntax
\begin{codeblock}
(rational= rat1 rat2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat1}{\code{<rational>}}{A rational value to be compared}
  \argument{rat2}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat1} is numerically equal to \code{rat2}}%
{\builtin{<boolean>}}


\procpurity{pure}


Rational numbers \(a/b\) and \(c/d\) are equal iff \(ad = bc\).


\procdef{rational-integer=}


\startprocsyntax
\begin{codeblock}
(rational-integer= rat i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
  \argument{i}{\code{<integer>}}{An integer value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat} is numerically equal to \code{i}}%
{\builtin{<boolean>}}


Rational number \(a/b\) and integer \(c\) are equal iff \(a = bc\).


\procpurity{pure}


\procdef{integer-rational=}


\startprocsyntax
\begin{codeblock}
(integer-rational= i rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\code{<integer>}}{An integer value to be compared}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{i} is numerically equal to \code{rat}}%
{\builtin{<boolean>}}


\procdef{rational<}


\startprocsyntax
\begin{codeblock}
(rational< rat1 rat2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat1}{\code{<rational>}}{A rational value to be compared}
  \argument{rat2}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat1} is less than \code{rat2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{rational-integer<}


\startprocsyntax
\begin{codeblock}
(rational-integer< rat i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
  \argument{i}{\code{<integer>}}{An integer value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat} is less than \code{i}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer-rational<}


\startprocsyntax
\begin{codeblock}
(integer-rational< i rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\code{<integer>}}{An integer value to be compared}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{i} is less than \code{rat}}%
{\builtin{<boolean>}}


\procdef{rational<=}


\startprocsyntax
\begin{codeblock}
(rational<= rat1 rat2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat1}{\code{<rational>}}{A rational value to be compared}
  \argument{rat2}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat1} is less than or equal to \code{rat2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{rational-integer<=}


\startprocsyntax
\begin{codeblock}
(rational-integer<= rat i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
  \argument{i}{\code{<integer>}}{An integer value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat} is less than or equal to \code{i}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer-rational<=}


\startprocsyntax
\begin{codeblock}
(integer-rational<= i rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\code{<integer>}}{An integer value to be compared}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{i} is less than or equal to \code{rat}}%
{\builtin{<boolean>}}


\procdef{rational>}


\startprocsyntax
\begin{codeblock}
(rational> rat1 rat2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat1}{\code{<rational>}}{A rational value to be compared}
  \argument{rat2}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat1} is greater than \code{rat2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{rational-integer>}


\startprocsyntax
\begin{codeblock}
(rational-integer> rat i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
  \argument{i}{\code{<integer>}}{An integer value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat} is greater than \code{i}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer-rational>}


\startprocsyntax
\begin{codeblock}
(integer-rational> i rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\code{<integer>}}{An integer value to be compared}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{i} is greater than \code{rat}}%
{\builtin{<boolean>}}


\procdef{rational>=}


\startprocsyntax
\begin{codeblock}
(rational>= rat1 rat2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat1}{\code{<rational>}}{A rational value to be compared}
  \argument{rat2}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat1} is greater than or equal to \code{rat2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{rational-integer>=}


\startprocsyntax
\begin{codeblock}
(rational-integer>= rat i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
  \argument{i}{\code{<integer>}}{An integer value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat} is greater than or equal to \code{i}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer-rational>=}


\startprocsyntax
\begin{codeblock}
(integer-rational>= i rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\code{<integer>}}{An integer value to be compared}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{i} is greater than or equal to \code{rat}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{simplify-rational}


\startprocsyntax
\begin{codeblock}
(simplify-rational rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The argument in the simplified form}%
{\code{<rational>}}


\procpurity{pure}


This procedures simplifies the rational number so that its numerator
and denominator don't have a common divisor. See chapter
\ref{ch:numerical-tower}.


\procdef{simplify-rational2}


\startprocsyntax
\begin{codeblock}
(simplify-rational2 rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The argument in the simplified form}%
{\code{<rational-number>}}


\procpurity{pure}


This procedure is similar to \code{simplify-rational} except when the
argument is integer valued. In that case this procedure returns an
integer. See chapter \ref{ch:numerical-tower}.


\procdef{rat-integer-valued?}


\startprocsyntax
\begin{codeblock}
(rat-integer-valued? rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{\true\ iff the argument is integer valued}%
{\builtin{<boolean>}}


\procpurity{pure}


A rational number is integer valued iff its denominator is 1 in the
simplified form.


\procdef{rat-sign}


\startprocsyntax
\begin{codeblock}
(rat-sign rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The sign of the argument}%
{\builtin{<integer>}}


\procpurity{pure}


Return 0 if \procarg{rat} \(=\) 0, 1 if \procarg{rat} \(>\) 0, and -1 if
\procarg{rat} \(<\) 0.


\procdef{integer->rational}


\startprocsyntax
\begin{codeblock}
(integer->rational i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\code{<integer>}}{An integer value}
\end{arglist}


\procresult{The argument converted to a rational number}%
{\code{<rational>}}


\procpurity{pure}


The numerator of the result is \code{i} and the denominator 1.


\procdef{rational->integer}


\startprocsyntax
\begin{codeblock}
(rational->integer rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The argument converted to an integer number}%
{\code{<integer>}}


\procpurity{pure}


If the argument is not integer valued an exception
\code{rational->integer:not-an-integer} is raised.


\procdef{rat-zero}


\startprocsyntax
\begin{codeblock}
(rat-zero)
\end{codeblock}


\noprocarguments


\procresult{The rational number 0}{\code{<rational>}}


\procpurity{pure}


The numerator of the result is 0 and the denominator 1.


\procdef{rat-one}


\startprocsyntax
\begin{codeblock}
(rat-one)
\end{codeblock}


\noprocarguments


\procresult{The rational number 1}{\code{<rational>}}


\procpurity{pure}


The numerator and the denominator of the result are 1.


\procdef{rat-zero?}


\startprocsyntax
\begin{codeblock}
(rat-zero? rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{\true\ iff the argument is equal to 0}{\builtin{<boolean>}}


\procpurity{pure}


A numerical overflow exception is raised if the denominator of the
argument is 0.


\procdef{rat-one?}


\startprocsyntax
\begin{codeblock}
(rat-one? rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{\true\ iff the argument is equal to 1}{\builtin{<boolean>}}


\procpurity{pure}


A numerical overflow exception is raised if the denominator of the
argument is 0.


\procdef{rational+}


\startprocsyntax
\begin{codeblock}
(rational+ rat1 rat2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat1}{\code{<rational>}}{A rational value}
  \argument{rat2}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The sum of the arguments in the simplified form}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{rational-integer+}


\startprocsyntax
\begin{codeblock}
(rational-integer+ rat i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
  \argument{i}{\code{<integer>}}{An integer value}
\end{arglist}


\procresult{The sum of the arguments in the simplified form}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{integer-rational+}


\startprocsyntax
\begin{codeblock}
(integer-rational+ i rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\code{<integer>}}{An integer value}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The sum of the arguments in the simplified form}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{rational-}


\startprocsyntax
\begin{codeblock}
(rational- rat1 rat2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat1}{\code{<rational>}}{A rational value}
  \argument{rat2}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The difference of the arguments in the simplified form}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{rational-integer-}


\startprocsyntax
\begin{codeblock}
(rational-integer- rat i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
  \argument{i}{\code{<integer>}}{An integer value}
\end{arglist}


\procresult{The difference of the arguments in the simplified form}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{integer-rational-}


\startprocsyntax
\begin{codeblock}
(integer-rational- i rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\code{<integer>}}{An integer value}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The difference of the arguments in the simplified form}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{rational*}


\startprocsyntax
\begin{codeblock}
(rational* rat1 rat2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat1}{\code{<rational>}}{A rational value}
  \argument{rat2}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The product of the arguments in the simplified form}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{rational-integer*}


\startprocsyntax
\begin{codeblock}
(rational-integer* rat i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
  \argument{i}{\code{<integer>}}{An integer value}
\end{arglist}


\procresult{The product of the arguments in the simplified form}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{integer-rational*}


\startprocsyntax
\begin{codeblock}
(integer-rational* i rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\code{<integer>}}{An integer value}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The product of the arguments in the simplified form}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{rational/}


\startprocsyntax
\begin{codeblock}
(rational/ rat1 rat2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat1}{\code{<rational>}}{A rational value}
  \argument{rat2}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The quotient of the arguments in the simplified form}%
{\builtin{<rational>}}


\procpurity{pure}


If the divisor is equal to 0 raise a numerical overflow exception.


\procdef{rational-integer/}


\startprocsyntax
\begin{codeblock}
(rational-integer/ rat i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
  \argument{i}{\code{<integer>}}{An integer value}
\end{arglist}


\procresult{The quotient of the arguments in the simplified form}%
{\builtin{<rational>}}


\procpurity{pure}


If the divisor is equal to 0 raise a numerical overflow exception.


\procdef{integer-rational/}


\startprocsyntax
\begin{codeblock}
(integer-rational/ i rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\code{<integer>}}{An integer value}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The quotient of the arguments in the simplified form}%
{\builtin{<rational>}}


\procpurity{pure}


If the divisor is equal to 0 raise a numerical overflow exception.


\procdef{rat-neg}


\startprocsyntax
\begin{codeblock}
(rat-neg rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The opposite of the argument}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{rat-abs}


\startprocsyntax
\begin{codeblock}
(rat-abs rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The absolute value of the argument}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{rat-square}


\startprocsyntax
\begin{codeblock}
(rat-square rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The square of the argument}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{rat-inverse}


\startprocsyntax
\begin{codeblock}
(rat-inverse rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The inverse of the argument}%
{\builtin{<rational>}}


\procpurity{pure}


If the argument is equal to 0 a numerical overflow exception is
raised.


\procdef{rat-nonneg-int-expt}


\startprocsyntax
\begin{codeblock}
(rat-nonneg-int-expt rat-base i-exponent)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat-base}{\code{<rational>}}{A rational value}
  \argument{i-exponent}{\builtin{<integer>}}{A nonnegative integer value}
\end{arglist}


\procresult{\procarg{rat-base} raised to the power \procarg{i-exponent}}%
{\builtin{<rational>}}


\procpurity{pure}


\procdef{rat-int-expt}


\startprocsyntax
\begin{codeblock}
(rat-int-expt rat-base i-exponent)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat-base}{\code{<rational>}}{A rational value}
  \argument{i-exponent}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{\procarg{rat-base} raised to the power \procarg{i-exponent}}%
{\builtin{<rational>}}


\procpurity{pure}


If \procarg{rat-base} is equal to 0 and \procarg{i-exponent} is
negative raise a numerical overflow exception.


\procdef{i-expt}


\startprocsyntax
\begin{codeblock}
  (i-expt i-base i-exponent)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i-base}{\builtin{<integer>}}%
  {An integer number}
  \argument{i-exponent}{\builtin{<integer>}}%
  {An integer number}
\end{arglist}


\procresult{\code{i-base} raised to the power \code{i-exponent}}%
{\builtin{<rational-number>}}


\procpurity{pure}


If the base is 0 and the exponent is negative raise a numerical
overflow exception. If the exponent is nonnegative the result is
always an \builtin{<integer>}.


\procdef{rat-log10-exact}


\startprocsyntax
\begin{codeblock}
  (rat-log10-exact rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\builtin{<rational>}}%
  {A rational number}
\end{arglist}


\procresult{The base 10 logarithm of the argument or \code{null} if %
  the logarithm is not an integer}
{\code{(:maybe <integer>)}}


\procpurity{pure}


This procedure is able compute logarithms of the negative integer
powers of 10, too.


\procdef{rat-log2-exact}


\startprocsyntax
\begin{codeblock}
  (rat-log2-exact rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\builtin{<rational>}}%
  {A rational number}
\end{arglist}


\procresult{The base 2 logarithm of the argument or \code{null} if %
  the logarithm is not an integer}
{\code{(:maybe <integer>)}}


\procpurity{pure}


This procedure is able compute logarithms of the negative integer
powers of 2, too.


\procdef{rational-to-string}


\startprocsyntax
\begin{codeblock}
(rational-to-string rat repr?)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
  \argument{repr?}{\builtin{<boolean>}}{Should we write a representation or a %
    user-friendly value}
\end{arglist}


\procresult{The argument value converted to a string}
           {\builtin{<string>}}


\procpurity{pure}


\section{Virtual Methods}

\indexmethod{equal?}

\noindent
\puremethoddefwithvalue{equal?}{<rational>
  <rational>}{<boolean>}{rational=?}

\indexmethod{=}

\noindent
\puremethoddefwithvalue{=}{<rational> <rational>}{<boolean>}{rational=}
\puremethoddefwithvalue{=}{<rational> <integer>}{<boolean>}{rational-integer=}
\puremethoddefwithvalue{=}{<integer> <rational>}{<boolean>}{integer-rational=}

\indexmethod{<}

\noindent
\abstpuremethoddef{<}{<rational-number> <rational-number>}{<boolean>}
\puremethoddefwithvalue{<}{<rational> <rational>}{<boolean>}{rational<}
\puremethoddefwithvalue{<}{<rational> <integer>}{<boolean>}{rational-integer<}
\puremethoddefwithvalue{<}{<integer> <rational>}{<boolean>}{integer-rational<}

\indexmethod{<=}

\noindent
\abstpuremethoddef{<=}{<rational-number> <rational-number>}{<boolean>}
\puremethoddefwithvalue{<=}{<rational> <rational>}{<boolean>}{rational<=}
\puremethoddefwithvalue{<=}{<rational> <integer>}{<boolean>}{rational-integer<=}
\puremethoddefwithvalue{<=}{<integer> <rational>}{<boolean>}{integer-rational<=}

\indexmethod{>}

\noindent
\abstpuremethoddef{>}{<rational-number> <rational-number>}{<boolean>}
\puremethoddefwithvalue{>}{<rational> <rational>}{<boolean>}{rational>}
\puremethoddefwithvalue{>}{<rational> <integer>}{<boolean>}{rational-integer>}
\puremethoddefwithvalue{>}{<integer> <rational>}{<boolean>}{integer-rational>}

\indexmethod{>=}

\noindent
\abstpuremethoddef{>=}{<rational-number> <rational-number>}{<boolean>}
\puremethoddefwithvalue{>=}{<rational> <rational>}{<boolean>}{rational>=}
\puremethoddefwithvalue{>=}{<rational> <integer>}{<boolean>}{rational-integer>=}
\puremethoddefwithvalue{>=}{<integer> <rational>}{<boolean>}{integer-rational>=}

\indexmethod{+}

\noindent
\abstpuremethoddef{+}{<rational-number> <rational-number>}{<rational-number>}
\puremethoddefwithvalue{+}{<rational> <rational>}{<rational>}{rational+}
\puremethoddefwithvalue{+}{<rational> <integer>}{<rational>}{rational-integer+}
\puremethoddefwithvalue{+}{<integer> <rational>}{<rational>}{integer-rational+}

\indexmethod{-}

\noindent
\abstpuremethoddef{-}{<rational-number> <rational-number>}{<rational-number>}
\puremethoddefwithvalue{-}{<rational> <rational>}{<rational>}{rational-}
\puremethoddefwithvalue{-}{<rational> <integer>}{<rational>}{rational-integer-}
\puremethoddefwithvalue{-}{<integer> <rational>}{<rational>}{integer-rational-}

\indexmethod{*}

\noindent
\abstpuremethoddef{*}{<rational-number> <rational-number>}{<rational-number>}
\puremethoddefwithvalue{*}{<rational> <rational>}{<rational>}{rational*}
\puremethoddefwithvalue{*}{<rational> <integer>}{<rational>}{rational-integer*}
\puremethoddefwithvalue{*}{<integer> <rational>}{<rational>}{integer-rational*}

\indexmethod{/}

\noindent
\abstpuremethoddef{/}{<rational-number> <rational-number>}{<rational-number>}
\puremethoddefwithvalue{/}{<rational> <rational>}{<rational>}{rational/}
\puremethoddefwithvalue{/}{<rational> <integer>}{<rational>}{rational-integer/}
\puremethoddefwithvalue{/}{<integer> <rational>}{<rational>}{integer-rational/}

\indexmethod{-}

\noindent
\abstpuremethoddef{-}{<rational-number>}{<rational-number>}
\puremethoddefwithvalue{-}{<rational>}{<rational>}{rat-neg}

\indexmethod{abc}

\noindent
\abstpuremethoddef{abs}{<rational-number>}{<rational-number>}
\puremethoddefwithvalue{abs}{<rational>}{<rational>}{rat-abs}

\indexmethod{square}

\noindent
\abstpuremethoddef{square}{<rational-number>}{<rational-number>}
\puremethoddefwithvalue{square}{<rational>}{<rational>}{rat-square}

\indexmethod{sign}

\noindent
\abstpuremethoddef{sign}{<rational-number>}{<rational-number>}
\puremethoddefwithvalue{sign}{<rational>}{<integer>}{rat-sign}

\indexmethod{atom-to-string}

\noindent
\puremethoddefwithvalue{atom-to-string}{<rational> <boolean>}{<string>}%
                   {rational-to-string}


\chapter{Module \code{(standard-library real-math)}}


\section{Data Types}


\begin{datatype}
  \datatypename{<real-number>}
  \datatypetype{\builtin{:union}}
  \datatypedesc{A real valued number}
\end{datatype}

\vspace{0.5cm}
Type \code{<real-number>} is equal to the union of \code{<real>},
\code{<rational>}, and \code{<integer>}.


\section{Constants}


The following constants are defined:
\begin{itemize}
  \item \code{gl-r-pi}: The value \(\pi\)
  \item \code{gl-r-pi/2}: The value \(\pi/2\)
  \item \code{gl-r-pi/4}: The value \(\pi/4\)
  \item \code{gl-r-1/pi}: The value \(1/\pi\)
  \item \code{gl-r-2/pi}: The value \(2/\pi\)
  \item \code{gl-r-2/sqrtpi}: The value \(1/\sqrt{\pi}\)
  \item \code{gl-r-sqrt2}: The value \(\sqrt{2}\)
  \item \code{gl-r-1/sqrt2}: The value \(1/\sqrt{2}\)
  \item \code{gl-r-e}: The value \(e\) (Napier's constant)
  \item \code{gl-r-log2e}: The value \(\log_2 e\)
  \item \code{gl-r-log10e}: The value \(\log_{10} e\)
  \item \code{gl-r-ln2}: The value \(\myln 2\)
  \item \code{gl-r-ln10}: The value \(\myln 10\)
  \item \code{gl-r-pi/ln2}: The value \(\pi / \myln 2\)
  \item \code{gl-r-pi/ln10}: The value \(\pi / \myln 10\)
\end{itemize}


\section{Simple Methods}


\procdef{rational->real}


\startprocsyntax
\begin{codeblock}
(rational->real rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The rational value converted to a real value}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real-rational=}


\startprocsyntax
\begin{codeblock}
(real-rational= r rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value to be compared}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{r} is numerically equal to \code{rat}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{rational-real=}


\startprocsyntax
\begin{codeblock}
(rational-real= rat r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
  \argument{r}{\builtin{<real>}}{A real value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat} is numerically equal to \code{r}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real-rational<}


\startprocsyntax
\begin{codeblock}
(real-rational< r rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value to be compared}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{r} is less than \code{rat}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{rational-real<}


\startprocsyntax
\begin{codeblock}
(rational-real< rat r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
  \argument{r}{\builtin{<real>}}{A real value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat} is less than \code{r}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real-rational<=}


\startprocsyntax
\begin{codeblock}
(real-rational<= r rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value to be compared}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{r} is less than or equal to \code{rat}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{rational-real<=}


\startprocsyntax
\begin{codeblock}
(rational-real<= rat r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
  \argument{r}{\builtin{<real>}}{A real value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat} is less than or equal to \code{r}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real-rational>}


\startprocsyntax
\begin{codeblock}
(real-rational> r rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value to be compared}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{r} is greater than \code{rat}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{rational-real>}


\startprocsyntax
\begin{codeblock}
(rational-real> rat r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
  \argument{r}{\builtin{<real>}}{A real value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat} is greater than \code{r}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real-rational>=}


\startprocsyntax
\begin{codeblock}
(real-rational>= r rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value to be compared}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{r} is greater than or equal to \code{rat}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{rational-real>=}


\startprocsyntax
\begin{codeblock}
(rational-real>= rat r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
  \argument{r}{\builtin{<real>}}{A real value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat} is greater than or equal to \code{r}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real-rational+}


\startprocsyntax
\begin{codeblock}
(real-rational+ r rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{rational-real+}


\startprocsyntax
\begin{codeblock}
(rational-real+ rat r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real-rational-}


\startprocsyntax
\begin{codeblock}
(real-rational- r rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{rational-real-}


\startprocsyntax
\begin{codeblock}
(rational-real- rat r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real-rational*}


\startprocsyntax
\begin{codeblock}
(real-rational* r rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{rational-real*}


\startprocsyntax
\begin{codeblock}
(rational-real* rat r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{real-rational/}


\startprocsyntax
\begin{codeblock}
(real-rational/ r rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


In case \code{rat} is equal to 0 return
\begin{itemize}
  \item inf, if \code{rat} \(> 0\)
  \item -inf, if \code{rat} \(< 0\)
  \item \nan, if \code{rat} \(= 0\)
\end{itemize}


\procdef{rational-real/}


\startprocsyntax
\begin{codeblock}
(rational-real/ rat r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<real>}}


\procpurity{pure}


In case \code{r} is equal to 0 return
\begin{itemize}
  \item inf, if \code{r} \(> 0\)
  \item -inf, if \code{r} \(< 0\)
  \item \nan, if \code{r} \(= 0\)
\end{itemize}


\procdef{r-sqrt}


\startprocsyntax
\begin{codeblock}
  (r-sqrt r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{Square root of the argument}%
{\builtin{<real>}}


\procpurity{pure}


If the argument is negative return \nan.


\procdef{r-expt}


\startprocsyntax
\begin{codeblock}
  (r-expt x y)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\builtin{<real>}}%
  {A real number}
  \argument{y}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{\code{x} to the power of \code{y}}%
{\builtin{<real>}}


\procpurity{pure}


If \code{x} is less than 0 return \nan. If \code{x} is equal to 0 return 1.0.


\procdef{r-exp}


\startprocsyntax
\begin{codeblock}
  (r-exp r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{\(e\) to the power of \code{r}}%
{\builtin{<real>}}


\procpurity{pure}


Number \(e\) is the base of natural logarithms (approx. 2.718).


\procdef{r-log}


\startprocsyntax
\begin{codeblock}
  (r-log r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The natural logarithm of \code{r}}%
{\builtin{<real>}}


\procpurity{pure}


If the argument is 0.0 return -inf. If the argument is less than 0.0
return \nan.


\procdef{r-log10}


\startprocsyntax
\begin{codeblock}
  (r-log10 r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The base 10 logarithm of \code{r}}%
{\builtin{<real>}}


\procpurity{pure}


If the argument is 0.0 return -inf. If the argument is less than 0.0
return \nan.


\procdef{r-sin}


\startprocsyntax
\begin{codeblock}
  (r-sin r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The sine of the argument}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{r-cos}


\startprocsyntax
\begin{codeblock}
  (r-cos r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The cosine of the argument}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{r-tan}


\startprocsyntax
\begin{codeblock}
  (r-tan r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The tangent of the argument}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{r-asin}


\startprocsyntax
\begin{codeblock}
  (r-asin r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The arcsine of the argument}%
{\builtin{<real>}}


\procpurity{pure}


If the result is not real return \nan.


\procdef{r-acos}


\startprocsyntax
\begin{codeblock}
  (r-acos r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The arccosine of the argument}%
{\builtin{<real>}}


\procpurity{pure}


If the result is not real return \nan.


\procdef{r-atan}


\startprocsyntax
\begin{codeblock}
  (r-atan r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The arctangent of the argument}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{r-sinh}


\startprocsyntax
\begin{codeblock}
  (r-sinh r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The hyperbolic sine of the argument}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{r-cosh}


\startprocsyntax
\begin{codeblock}
  (r-cosh r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The hyperbolic cosine of the argument}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{r-tanh}


\startprocsyntax
\begin{codeblock}
  (r-tanh r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The hyperbolic tangent of the argument}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{r-asinh}


\startprocsyntax
\begin{codeblock}
  (r-asinh r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The hyperbolic arcsine of the argument}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{r-acosh}


\startprocsyntax
\begin{codeblock}
  (r-acosh r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The hyperbolic arccosine of the argument}%
{\builtin{<real>}}


\procpurity{pure}


If the result is not real return \nan.


\procdef{r-atanh}


\startprocsyntax
\begin{codeblock}
  (r-atanh r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The hyperbolic arctangent of the argument}%
{\builtin{<real>}}


\procpurity{pure}


If the result is not real return \nan.


\procdef{r-atan2}


\startprocsyntax
\begin{codeblock}
  (r-atan2 y x)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{y}{\builtin{<real>}}%
  {A real number}
  \argument{x}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The angle between point (\procarg{x}, \procarg{y}) and the %
positive x axis (in radians)}%
{\builtin{<real>}}


\procpurity{pure}


\procdef{i-sqrt}


\startprocsyntax
\begin{codeblock}
  (i-sqrt i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}%
  {An integer number}
\end{arglist}


\procresult{Square root of the argument}%
{\code{(:union <real> <integer>)}}


\procpurity{pure}


If the square root is integer valued it is converted to class
\builtin{<integer>}.


\procdef{rat-sqrt}


\startprocsyntax
\begin{codeblock}
  (rat-sqrt rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}%
  {A rational number}
\end{arglist}


\procresult{Square root of the argument}%
{\code{(:union <real> <rational> <integer>)}}


\procpurity{pure}


If the square root is rational or integer valued it is converted to class
\code{<rational>} or \builtin{<integer>}, respectively.


\procdef{string->real-number}


\startprocsyntax
\begin{codeblock}
  (string->real-number \procarg{str})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{A string}
\end{arglist}


\procresult{The argument string converted to a real number}%
{\builtin{<real-number>}}


\procpurity{pure}


If the string cannot be converted to a real number an RTE exception is
raised.


\section{Virtual Methods}


\indexmethod{=}

\noindent
\abstpuremethoddef{=}{<real-number> <real-number>}{<boolean>}
\puremethoddefwithvalue{=}{<real> <rational>}{<boolean>}{real-rational=}
\puremethoddefwithvalue{=}{<rational> <real>}{<boolean>}{rational-real=}

\indexmethod{<}
\indexmethod{<=}
\indexmethod{>}
\indexmethod{>=}

\noindent
\abstpuremethoddef{<}{<real-number> <real-number>}{<boolean>}
\puremethoddefwithvalue{<}{<real> <rational>}{<boolean>}{real-rational<}
\puremethoddefwithvalue{<}{<rational> <real>}{<boolean>}{rational-real<}
\abstpuremethoddef{<=}{<real-number> <real-number>}{<boolean>}
\puremethoddefwithvalue{<=}{<real> <rational>}{<boolean>}{real-rational<=}
\puremethoddefwithvalue{<=}{<rational> <real>}{<boolean>}{rational-real<=}
\abstpuremethoddef{>}{<real-number> <real-number>}{<boolean>}
\puremethoddefwithvalue{>}{<real> <rational>}{<boolean>}{real-rational>}
\puremethoddefwithvalue{>}{<rational> <real>}{<boolean>}{rational-real>}
\abstpuremethoddef{>=}{<real-number> <real-number>}{<boolean>}
\puremethoddefwithvalue{>=}{<real> <rational>}{<boolean>}{real-rational>=}
\puremethoddefwithvalue{>=}{<rational> <real>}{<boolean>}{rational-real>=}

\indexmethod{+}
\indexmethod{-}
\indexmethod{*}
\indexmethod{/}

\noindent
\abstpuremethoddef{+}{<real-number> <real-number>}{<real-number>}
\puremethoddefwithvalue{+}{<real> <rational>}{<real>}{real-rational+}
\puremethoddefwithvalue{+}{<rational> <real>}{<real>}{rational-real+}
\abstpuremethoddef{-}{<real-number> <real-number>}{<real-number>}
\puremethoddefwithvalue{-}{<real> <rational>}{<real>}{real-rational-}
\puremethoddefwithvalue{-}{<rational> <real>}{<real>}{rational-real-}
\abstpuremethoddef{*}{<real-number> <real-number>}{<real-number>}
\puremethoddefwithvalue{*}{<real> <rational>}{<real>}{real-rational*}
\puremethoddefwithvalue{*}{<rational> <real>}{<real>}{rational-real*}
\abstpuremethoddef{/}{<real-number> <real-number>}{<real-number>}
\puremethoddefwithvalue{/}{<real> <rational>}{<real>}{real-rational/}
\puremethoddefwithvalue{/}{<rational> <real>}{<real>}{rational-real/}

\indexmethod{-}
\indexmethod{abs}
\indexmethod{square}
\indexmethod{sign}

\noindent
\abstpuremethoddef{-}{<real-number>}{<real-number>}
\abstpuremethoddef{abs}{<real-number>}{<real-number>}
\abstpuremethoddef{square}{<real-number>}{<real-number>}
\abstpuremethoddef{sign}{<real-number>}{<integer>}


\chapter{Module \code{(standard-library complex)}}


\section{Data Types}


\begin{datatype}
  \datatypename{<complex>}
  \datatypetype{\builtin{<class>}}
  \datatypedesc{A complex number}
\end{datatype}

\vspace{0.5cm}
Class \code{<complex>} is immutable, equal by value, and not
inheritable.


\section{Simple Methods}


\procdef{real->complex}


\startprocsyntax
\begin{codeblock}
  (real->complex r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The complex number corresponding to the given real number}%
{\code{<complex>}}


\procpurity{pure}


\procdef{integer->complex}


\startprocsyntax
\begin{codeblock}
  (integer->complex n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{n}{\builtin{<integer>}}%
  {An integer number}
\end{arglist}


\procresult{The complex number corresponding to the given integer number}%
{\code{<complex>}}


\procpurity{pure}


\procdef{rational->complex}


\startprocsyntax
\begin{codeblock}
  (rational->complex rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}%
  {An integer number}
\end{arglist}


\procresult{The complex number corresponding to the given rational number}%
{\code{<complex>}}


\procpurity{pure}


\procdef{complex=?}


\startprocsyntax
\begin{codeblock}
(complex=? cx1 cx2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx1}{\code{<complex>}}{A complex value to be compared}
  \argument{cx2}{\code{<complex>}}{A complex value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{cx1} is equal to \code{cx2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{complex=}


\startprocsyntax
\begin{codeblock}
(complex= cx1 cx2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx1}{\code{<complex>}}{A complex value to be compared}
  \argument{cx2}{\code{<complex>}}{A complex value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{cx1} is numerically equal to \code{cx2}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{complex-integer=}


\startprocsyntax
\begin{codeblock}
(complex-integer= cx i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value to be compared}
  \argument{i}{\builtin{<integer>}}{An integer value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{cx} is numerically equal to \code{i}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{integer-complex=}


\startprocsyntax
\begin{codeblock}
(integer-complex= i cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value to be compared}
  \argument{cx}{\code{<complex>}}{A complex value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{i} is numerically equal to \code{cx}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{complex-real=}


\startprocsyntax
\begin{codeblock}
(complex-real= cx r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value to be compared}
  \argument{r}{\builtin{<real>}}{A real value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{cx} is numerically equal to \code{r}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{real-complex=}


\startprocsyntax
\begin{codeblock}
(real-complex= r cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value to be compared}
  \argument{cx}{\code{<complex>}}{A complex value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{r} is numerically equal to \code{cx}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{complex-rational=}


\startprocsyntax
\begin{codeblock}
(complex-rational= cx rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value to be compared}
  \argument{rat}{\code{<rational>}}{A rational value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{cx} is numerically equal to \code{rat}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{rational-complex=}


\startprocsyntax
\begin{codeblock}
(rational-complex= rat cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{An rational value to be compared}
  \argument{cx}{\code{<complex>}}{A complex value to be compared}
\end{arglist}


\procresult{\code{\#t} iff \code{rat} is numerically equal to \code{cx}}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{complex+}


\startprocsyntax
\begin{codeblock}
(complex+ cx1 cx2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx1}{\code{<complex>}}{A complex value}
  \argument{cx2}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-integer+}


\startprocsyntax
\begin{codeblock}
(complex-integer+ cx i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value}
  \argument{i}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{integer-complex+}


\startprocsyntax
\begin{codeblock}
(integer-complex+ i cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value}
  \argument{cx}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-real+}


\startprocsyntax
\begin{codeblock}
(complex-real+ cx r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{real-complex+}


\startprocsyntax
\begin{codeblock}
(real-complex+ r cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{cx}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-rational+}


\startprocsyntax
\begin{codeblock}
(complex-rational+ cx rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{rational-complex+}


\startprocsyntax
\begin{codeblock}
(rational-complex+ rat cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{An rational value}
  \argument{cx}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The sum of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-}


\startprocsyntax
\begin{codeblock}
(complex- cx1 cx2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx1}{\code{<complex>}}{A complex value}
  \argument{cx2}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-integer-}


\startprocsyntax
\begin{codeblock}
(complex-integer- cx i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value}
  \argument{i}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{integer-complex-}


\startprocsyntax
\begin{codeblock}
(integer-complex- i cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value}
  \argument{cx}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-real-}


\startprocsyntax
\begin{codeblock}
(complex-real- cx r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{real-complex-}


\startprocsyntax
\begin{codeblock}
(real-complex- r cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{cx}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-rational-}


\startprocsyntax
\begin{codeblock}
(complex-rational- cx rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{rational-complex-}


\startprocsyntax
\begin{codeblock}
(rational-complex- rat cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{An rational value}
  \argument{cx}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The difference of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex*}


\startprocsyntax
\begin{codeblock}
(complex* cx1 cx2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx1}{\code{<complex>}}{A complex value}
  \argument{cx2}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-integer*}


\startprocsyntax
\begin{codeblock}
(complex-integer* cx i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value}
  \argument{i}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{integer-complex*}


\startprocsyntax
\begin{codeblock}
(integer-complex* i cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value}
  \argument{cx}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-real*}


\startprocsyntax
\begin{codeblock}
(complex-real* cx r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{real-complex*}


\startprocsyntax
\begin{codeblock}
(real-complex* r cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{cx}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-rational*}


\startprocsyntax
\begin{codeblock}
(complex-rational* cx rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{rational-complex*}


\startprocsyntax
\begin{codeblock}
(rational-complex* rat cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{An rational value}
  \argument{cx}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The product of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex/}


\startprocsyntax
\begin{codeblock}
(complex/ cx1 cx2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx1}{\code{<complex>}}{A complex value}
  \argument{cx2}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-integer/}


\startprocsyntax
\begin{codeblock}
(complex-integer/ cx i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value}
  \argument{i}{\builtin{<integer>}}{An integer value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{integer-complex/}


\startprocsyntax
\begin{codeblock}
(integer-complex/ i cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\builtin{<integer>}}{An integer value}
  \argument{cx}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-real/}


\startprocsyntax
\begin{codeblock}
(complex-real/ cx r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value}
  \argument{r}{\builtin{<real>}}{A real value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{real-complex/}


\startprocsyntax
\begin{codeblock}
(real-complex/ r cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}{A real value}
  \argument{cx}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{complex-rational/}


\startprocsyntax
\begin{codeblock}
(complex-rational/ cx rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex value}
  \argument{rat}{\code{<rational>}}{A rational value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{rational-complex/}


\startprocsyntax
\begin{codeblock}
(rational-complex/ rat cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{An rational value}
  \argument{cx}{\code{<complex>}}{A complex value}
\end{arglist}


\procresult{The quotient of the arguments}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-neg}


\startprocsyntax
\begin{codeblock}
  (c-neg c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The opposite number of the given complex number}
{\code{<complex>}}


\procpurity{pure}


\procdef{c-abs}


\startprocsyntax
\begin{codeblock}
  (c-abs c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The absolute value of the given complex number}
{\code{<real>}}


\procpurity{pure}


\procdef{c-square}


\startprocsyntax
\begin{codeblock}
  (c-square c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The square of the given complex number}
{\code{<complex>}}


\procpurity{pure}


\procdef{real-part}


\startprocsyntax
\begin{codeblock}
  (real-part c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The real part of the given complex number}
{\code{<real>}}


\procpurity{pure}


\procdef{imag-part}


\startprocsyntax
\begin{codeblock}
  (imag-part c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The imaginary part of the given complex number}
{\code{<real>}}


\procpurity{pure}


\procdef{simplify-complex}


\startprocsyntax
\begin{codeblock}
  (simplify-complex c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The argument in simplified form}
{\code{(:union <complex> <real>)}}


\procpurity{pure}


If the real part of the argument is zero this procedure returns the
real part as \code{<real>}. Otherwise the argument is returned.


\procdef{make-polar}


\startprocsyntax
\begin{codeblock}
  (make-polar magnitude angle)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argumentnodesc{magnitude}{\builtin{<real>}}{}
  \argumentnodesc{angle}{\builtin{<real>}}{}
\end{arglist}


\procresult{The complex number having the given magnitude and angle}
{\code{<complex>}}


\procpurity{pure}


\procdef{c-angle}


\startprocsyntax
\begin{codeblock}
  (c-angle c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The angle of the given complex number}
{\code{<real>}}


\procpurity{pure}


\procdef{r-complex-log}


\startprocsyntax
\begin{codeblock}
  (r-complex-log r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\code{<real>}}{A real number}
\end{arglist}


\procresult{The natural logarithm of \procarg{r}}%
{\code{<complex>}}


\procpurity{pure}


The result is computed correctly for the negative values of
\procarg{r}, too.


\procdef{r-log-neg}


\startprocsyntax
\begin{codeblock}
  (r-log-neg r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\code{<real>}}{A negative real number}
\end{arglist}


\procresult{The natural logarithm of \procarg{r}}%
{\code{<complex>}}


\procpurity{pure}


The natural logarithm of a negative real number \(r\) is
\begin{math}
  \myln r = \myln \left\vert r \right\vert + \textsf{i} \pi
\end{math}.


\procdef{r-log10-neg}


\startprocsyntax
\begin{codeblock}
  (r-log10-neg r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\code{<real>}}{A negative real number}
\end{arglist}


\procresult{The base 10 logarithm of \procarg{r}}%
{\code{<complex>}}


\procpurity{pure}


The base 10 logarithm of a negative real number \(r\) is
\begin{math}
  \log_{10} r = \log_{10} \left\vert r \right\vert + \textsf{i} \pi /
  \myln 10
\end{math}.


\procdef{r-complex-expt}


\startprocsyntax
\begin{codeblock}
  (r-complex-expt r-base r-exponent)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r-base}{\code{<real>}}{A real number}
  \argument{r-exponent}{\code{<real>}}{A real number}
\end{arglist}


\procresult{\procarg{r-base} raised to the power of \procarg{r-exponent}}%
{\code{<complex>}}


\procpurity{pure}


The result is computed correctly for the negative values of
\procarg{r-base}, too.


\procdef{complex-real-expt}


\startprocsyntax
\begin{codeblock}
  (complex-real-expt cx-base r-exponent)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx-base}{\code{<complex>}}{A complex number}
  \argument{r-exponent}{\code{<real>}}{A real number}
\end{arglist}


\procresult{\procarg{cx-base} raised to the power of \procarg{r-exponent}}%
{\code{<complex>}}


\procpurity{pure}


\procdef{real-complex-expt}


\startprocsyntax
\begin{codeblock}
  (real-complex-expt r-base cx-exponent)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r-base}{\code{<real>}}{A real number}
  \argument{cx-exponent}{\code{<complex>}}{A complex number}
\end{arglist}


\procresult{\procarg{r-base} raised to the power of \procarg{cx-exponent}}%
{\code{<complex>}}


\procpurity{pure}


This procedure works for negative values of \procarg{r-base}, too.


\procdef{c-exp2}


\startprocsyntax
\begin{codeblock}
  (c-exp2 cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}{A complex number}
\end{arglist}


\procresult{2 raised to the power of \procarg{cx-exponent}}%
{\code{<complex>}}


\procpurity{pure}


\procdef{c-nonneg-int-expt}


\startprocsyntax
\begin{codeblock}
  (c-nonneg-int-expt cx-base i-expt)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx-base}{\code{<complex>}}%
  {A complex number}
  \argument{i-expt}{\builtin{<integer>}}%
  {A nonnegative integer number}
\end{arglist}


\procresult{\code{cx-base} raised to the power \code{i-expt}}%
{\code{<complex>}}


\procpurity{pure}


\procdef{c-int-expt}


\startprocsyntax
\begin{codeblock}
  (c-int-expt cx-base i-expt)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx-base}{\code{<complex>}}%
  {A complex number}
  \argument{i-expt}{\builtin{<integer>}}%
  {An integer number}
\end{arglist}


\procresult{\code{cx-base} raised to the power \code{i-expt}}%
{\code{<complex>}}


\procpurity{pure}


\procdef{c-sqrt}


\startprocsyntax
\begin{codeblock}
  (c-sqrt c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{Square root of the argument}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-expt}


\startprocsyntax
\begin{codeblock}
  (c-expt x y)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\builtin{<complex>}}%
  {A complex number}
  \argument{y}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{\code{x} to the power of \code{y}}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-exp}


\startprocsyntax
\begin{codeblock}
  (c-exp c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{\(e\) to the power of \code{r}}%
{\builtin{<complex>}}


\procpurity{pure}


Number \(e\) is the base of natural logarithms (approx. 2.718).


\procdef{c-log}


\startprocsyntax
\begin{codeblock}
  (c-log c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The natural logarithm of \code{r}}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-log10}


\startprocsyntax
\begin{codeblock}
  (c-log10 c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The base 10 logarithm of \code{r}}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-sin}


\startprocsyntax
\begin{codeblock}
  (c-sin c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The sine of the argument}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-cos}


\startprocsyntax
\begin{codeblock}
  (c-cos c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The cosine of the argument}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-tan}


\startprocsyntax
\begin{codeblock}
  (c-tan c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The tangent of the argument}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-asin}


\startprocsyntax
\begin{codeblock}
  (c-asin c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The arcsine of the argument}%
{\builtin{<complex>}}


\procpurity{pure}


This procedure sometimes returns a value from a different branch
compared to guile (2.2.2) \code{asin}. Our convention is similar to
Octave (version 3.8.1).


\procdef{c-acos}


\startprocsyntax
\begin{codeblock}
  (c-acos c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The arccosine of the argument}%
{\builtin{<complex>}}


This procedure sometimes returns a value from a different branch
compared to guile (2.2.2) \code{acos}. Our convention is similar to
Octave (version 3.8.1).


\procpurity{pure}


\procdef{c-atan}


\startprocsyntax
\begin{codeblock}
  (c-atan c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The arctangent of the argument}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-sinh}


\startprocsyntax
\begin{codeblock}
  (c-sinh c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The hyperbolic sine of the argument}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-cosh}


\startprocsyntax
\begin{codeblock}
  (c-cosh c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The hyperbolic cosine of the argument}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-tanh}


\startprocsyntax
\begin{codeblock}
  (c-tanh c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The hyperbolic tangent of the argument}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-asinh}


\startprocsyntax
\begin{codeblock}
  (c-asinh c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The hyperbolic arcsine of the argument}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-acosh}


\startprocsyntax
\begin{codeblock}
  (c-acosh c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The hyperbolic arccosine of the argument}%
{\builtin{<complex>}}


\procpurity{pure}


\procdef{c-atanh}


\startprocsyntax
\begin{codeblock}
  (c-atanh c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The hyperbolic arctangent of the argument}%
{\builtin{<complex>}}


\procpurity{pure}


This procedure sometimes returns a value from a different branch
compared to guile (2.2.2) \code{atanh}. Our convention is similar to
Octave (version 3.8.1).


\procdef{complex-to-string}


\startprocsyntax
\begin{codeblock}
  (complex-to-string c)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{c}{\builtin{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The complex number as a string}
{\code{<string>}}


\procpurity{pure}


\section{Virtual Methods}


\indexmethod{complex}

\noindent
\abstpuremethoddef{complex}{<real-number> <real-number>}{<complex>}
\puremethoddef{complex}{<real> <real>}{<complex>}
\puremethoddef{complex}{<real> <integer>}{<complex>}
\puremethoddef{complex}{<real> <rational>}{<complex>}
\puremethoddef{complex}{<integer> <real>}{<complex>}
\puremethoddef{complex}{<integer> <integer>}{<complex>}
\puremethoddef{complex}{<integer> <rational>}{<complex>}
\puremethoddef{complex}{<rational> <real>}{<complex>}
\puremethoddef{complex}{<rational> <integer>}{<complex>}
\puremethoddef{complex}{<rational> <rational>}{<complex>}

These methods construct a complex number from the real and imaginary
parts given as arguments. The arguments are converted to \code{<real>}
if necessary.

\indexmethod{equal?}

\vspace{0.3cm}
\noindent
\puremethoddefwithvalue{equal?}{<complex> <complex>}{<boolean>}{complex=?}

\indexmethod{=}

\noindent
\puremethoddefwithvalue{=}{<complex> <complex>}{<boolean>}{complex=}
\puremethoddefwithvalue{=}{<complex> <integer>}{<boolean>}{complex-integer=}
\puremethoddefwithvalue{=}{<integer> <complex>}{<boolean>}{integer-complex=}
\puremethoddefwithvalue{=}{<complex> <real>}{<boolean>}{complex-real=}
\puremethoddefwithvalue{=}{<real> <complex>}{<boolean>}{real-complex=}
\puremethoddefwithvalue{=}{<complex> <rational>}{<boolean>}{complex-rational=}
\puremethoddefwithvalue{=}{<rational> <complex>}{<boolean>}{rational-complex=}

\indexmethod{+}

\noindent
\puremethoddefwithvalue{+}{<complex> <complex>}{<complex>}{complex+}
\puremethoddefwithvalue{+}{<complex> <integer>}{<complex>}{complex-integer+}
\puremethoddefwithvalue{+}{<integer> <complex>}{<complex>}{integer-complex+}
\puremethoddefwithvalue{+}{<complex> <real>}{<complex>}{complex-real+}
\puremethoddefwithvalue{+}{<real> <complex>}{<complex>}{real-complex+}
\puremethoddefwithvalue{+}{<complex> <rational>}{<complex>}{complex-rational+}
\puremethoddefwithvalue{+}{<rational> <complex>}{<complex>}{rational-complex+}

\indexmethod{-}

\noindent
\puremethoddefwithvalue{-}{<complex> <complex>}{<complex>}{complex-}
\puremethoddefwithvalue{-}{<complex> <integer>}{<complex>}{complex-integer-}
\puremethoddefwithvalue{-}{<integer> <complex>}{<complex>}{integer-complex-}
\puremethoddefwithvalue{-}{<complex> <real>}{<complex>}{complex-real-}
\puremethoddefwithvalue{-}{<real> <complex>}{<complex>}{real-complex-}
\puremethoddefwithvalue{-}{<complex> <rational>}{<complex>}{complex-rational-}
\puremethoddefwithvalue{-}{<rational> <complex>}{<complex>}{rational-complex-}

\indexmethod{*}

\noindent
\puremethoddefwithvalue{*}{<complex> <complex>}{<complex>}{complex*}
\puremethoddefwithvalue{*}{<complex> <integer>}{<complex>}{complex-integer*}
\puremethoddefwithvalue{*}{<integer> <complex>}{<complex>}{integer-complex*}
\puremethoddefwithvalue{*}{<complex> <real>}{<complex>}{complex-real*}
\puremethoddefwithvalue{*}{<real> <complex>}{<complex>}{real-complex*}
\puremethoddefwithvalue{*}{<complex> <rational>}{<complex>}{complex-rational*}
\puremethoddefwithvalue{*}{<rational> <complex>}{<complex>}{rational-complex*}

\indexmethod{/}

\noindent
\puremethoddefwithvalue{/}{<complex> <complex>}{<complex>}{complex/}
\puremethoddefwithvalue{/}{<complex> <integer>}{<complex>}{complex-integer/}
\puremethoddefwithvalue{/}{<integer> <complex>}{<complex>}{integer-complex/}
\puremethoddefwithvalue{/}{<complex> <real>}{<complex>}{complex-real/}
\puremethoddefwithvalue{/}{<real> <complex>}{<complex>}{real-complex/}
\puremethoddefwithvalue{/}{<complex> <rational>}{<complex>}{complex-rational/}
\puremethoddefwithvalue{/}{<rational> <complex>}{<complex>}{rational-complex/}

\indexmethod{-}
\indexmethod{square}
\indexmethod{abs}

\noindent
\puremethoddefwithvalue{-}{<complex>}{<complex>}{c-neg}
\puremethoddefwithvalue{square}{<complex>}{<complex>}{c-square}
\puremethoddefwithvalue{abs}{<complex>}{<real>}{c-abs}

\indexmethod{atom-to-string}

\noindent
\puremethoddefwithvalue{atom-to-string}{<complex> <boolean>}{<string>}%
                   {complex-to-string}


\chapter{Module \code{(standard-library math)}}


This module reexports modules \code{rational}, \code{real-math}, and
\code{complex}.


\section{Data Types}


\begin{datatype}
  \datatypename{<number>}
  \datatypetype{\builtin{:union}}
  \datatypedesc{A number}
\end{datatype}


\vspace{0.5cm}
Type \code{<number>} is equal to the union of \code{<complex>},
\code{<real>}, \code{<rational>}, and \code{<integer>}.


\section{Simple Methods}


\procdef{integer-valued?}


\startprocsyntax
\begin{codeblock}
  (integer-valued? x)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\builtin{<object>}}%
  {An object}
\end{arglist}


\procresult{\true\ iff the argument is integer valued}%
{\builtin{<boolean>}}


\procpurity{pure}


An object is integer valued if one of the following holds:
\begin{itemize}
  \item It is an \builtin{<integer>}
  \item It is an integer valued \code{<rational>}
  \item It is an integer valued \builtin{<real>}
  \item It is a \code{<complex>} whose imaginary part is 0.0 and real
    part is integer valued
\end{itemize}


\procdef{real-valued?}


\startprocsyntax
\begin{codeblock}
  (real-valued? x)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\builtin{<object>}}%
  {An object}
\end{arglist}


\procresult{\true\ iff the argument is real valued}%
{\builtin{<boolean>}}


\procpurity{pure}


An object is real valued if
\begin{itemize}
  \item It is an \builtin{<integer>},
  \item It is a \code{<rational>},
  \item It is a \builtin{<real>}, or
  \item It is a \code{<complex>} whose imaginary part is 0.0
\end{itemize}


\procdef{rational-valued?}


\startprocsyntax
\begin{codeblock}
  (rational-valued? x)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\builtin{<object>}}%
  {An object}
\end{arglist}


\procresult{\true\ iff the argument is rational valued}%
{\builtin{<boolean>}}


\procpurity{pure}


An object is rational valued if
\begin{itemize}
  \item It is an \builtin{<integer>},
  \item It is a \code{<rational>},
  \item It is an integer valued \builtin{<real>}, or
  \item It is a \code{<complex>} whose imaginary part is 0.0 and real
    part is integer valued
\end{itemize}


\procdef{exact?}


\startprocsyntax
\begin{codeblock}
  (exact? nr)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{nr}{\code{<number>}}%
  {A number}
\end{arglist}


\procresult{\true\ iff the argument is exact}%
{\builtin{<boolean>}}


\procpurity{pure}


A number is exact iff it is an \builtin{<integer>} or a
\code{<rational>}.


\procdef{inexact?}


\startprocsyntax
\begin{codeblock}
  (inexact? nr)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{nr}{\code{<number>}}%
  {A number}
\end{arglist}


\procresult{\true\ iff the argument is inexact}%
{\builtin{<boolean>}}


\procpurity{pure}


A number is exact iff it is not exact, i,e, it is an
\builtin{<real>} or a \code{<complex>}.


\procdef{real->exact}


\startprocsyntax
\begin{codeblock}
  (real->exact r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The argument converted to a rational or an integer}%
{\code{<rational-number>}}


\procpurity{pure}


\procdef{complex->exact}


\startprocsyntax
\begin{codeblock}
  (complex->exact cx)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{cx}{\code{<complex>}}%
  {A complex number}
\end{arglist}


\procresult{The argument converted to a rational or an integer}%
{\code{<rational-number>}}


\procpurity{pure}


\procdef{real->exact}


\startprocsyntax
\begin{codeblock}
  (real->exact r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\builtin{<real>}}%
  {A real number}
\end{arglist}


\procresult{The argument converted to a rational or an integer}%
{\code{<rational-number>}}


\procpurity{pure}


If the imaginary part of the argument is not 0.0 exception
\code{complex->exact:invalid-argument} is raised.


\section{Virtual Methods}


\indexmethod{exact->inexact}

\noindent
\abstpuremethoddef{exact->inexact}{<number>}{<number>}
\abstpuremethoddef{exact->inexact}{<real-number>}{<real-number>}
\puremethoddefwithvalue{exact->inexact}{<integer>}{<real>}{integer->real}
\puremethoddefwithvalue{exact->inexact}{<rational>}{<real>}{rational->real}

\noindent
\puremethoddef{exact->inexact}{<real>}{<real>}

Returns the argument.

\vspace{0.3cm}

\noindent
\puremethoddef{exact->inexact}{<complex>}{<complex>}

Returns the argument.

\vspace{0.3cm}

\indexmethod{inexact->exact}

\noindent
\abstpuremethoddef{inexact->exact}{<number>}{<rational-number>}
\puremethoddefwithvalue{inexact->exact}{<complex>}{<rational-number>}%
                   {complex->exact}
\puremethoddefwithvalue{inexact->exact}{<real>}{<rational-number>}{real->exact}

\noindent
\puremethoddef{inexact->exact}{<rational>}{<rational>}

Returns the argument.

\vspace{0.3cm}

\noindent
\puremethoddef{inexact->exact}{<integer>}{<integer>}

Returns the argument.

\vspace{0.3cm}

\indexmethod{+}
\indexmethod{-}
\indexmethod{*}
\indexmethod{/}

\noindent
\abstpuremethoddef{+}{<number> <number>}{<number>}
\abstpuremethoddef{-}{<number> <number>}{<number>}
\abstpuremethoddef{*}{<number> <number>}{<number>}
\abstpuremethoddef{/}{<number> <number>}{<number>}

\indexmethod{-}
\indexmethod{abs}
\indexmethod{square}

\noindent
\abstpuremethoddef{-}{<number>}{<number>}
\abstpuremethoddef{abs}{<number>}{<real-number>}
\abstpuremethoddef{square}{<number>}{<number>}

\indexmethod{sqrt}

\noindent
\abstpuremethoddef{sqrt}{<number>}{<number>}
\puremethoddef{sqrt}{<integer>}{<number>}
\puremethoddef{sqrt}{<rational>}{<number>}
\puremethoddef{sqrt}{<real>}{(:union <real> <complex>)}
\puremethoddefwithvalue{sqrt}{<complex>}{<complex>}{c-sqrt}

These methods compute the square root of the argument. They return
exact 0 when the argument is exact 0.

\vspace{0.3cm}

\indexmethod{expt}

\noindent
\abstpuremethoddef{expt}{<number> <number>}{<number>}
\puremethoddef{expt}{<integer> <integer>}{<rational-number>}
\puremethoddef{expt}{<integer> <real>}{(:union <real> <complex>)}
\puremethoddef{expt}{<integer> <rational>}{<number>}
\puremethoddef{expt}{<integer> <complex>}{<complex>}
\puremethoddef{expt}{<real> <integer>}{(:union <real> <integer>)}
\puremethoddef{expt}{<real> <real>}{(:union <real> <complex>)}
\puremethoddef{expt}{<real> <rational>}{(:union <integer> <real> <complex>)}
\puremethoddef{expt}{<real> <complex>}{<complex>}
\puremethoddefwithvalue{expt}{<rational> <integer>}{<rational>}{rat-int-expt}
\puremethoddef{expt}{<rational> <real>}{(:union <integer> <real> <complex>)}
\puremethoddef{expt}{<rational> <rational>}{<number>}
\puremethoddef{expt}{<rational> <complex>}{<complex>}
\puremethoddef{expt}{<complex> <integer>}{(:union <complex> <integer>)}
\puremethoddef{expt}{<complex> <real>}{<complex>}
\puremethoddef{expt}{<complex> <rational>}{<complex>}
\puremethoddefwithvalue{expt}{<complex> <complex>}{<complex>}{c-expt}

These methods raise the first argument to the power of the
second argument. If any of the arguments is equal to exact 0 the value
0 or 1 is returned in many cases.

\vspace{0.3cm}

\indexmethod{exp}

\noindent
\abstpuremethoddef{exp}{<number>}{<number>}
\abstpuremethoddef{exp}{<real-number>}{(:union <real> <integer>)}
\puremethoddef{exp}{<integer>}{(:union <real> <integer>)}
\puremethoddef{exp}{<rational>}{(:union <real> <integer>)}
\puremethoddefwithvalue{exp}{<real>}{<real>}{r-exp}
\puremethoddefwithvalue{exp}{<complex>}{<complex>}{c-exp}

These methods compute the exponential of the argument. They return
exact 1 when the argument is exact 0.

\vspace{0.3cm}

\indexmethod{log}

\noindent
\abstpuremethoddef{log}{<number>}{<number>}
\puremethoddef{log}{<integer>}{(:union <integer> <real> <complex>)}
\puremethoddef{log}{<rational>}{(:union <integer> <real> <complex>)}
\puremethoddef{log}{<real>}{(:union <real> <complex>)}
\puremethoddefwithvalue{log}{<complex>}{<complex>}{c-log}

These methods compute the natural logarithm of the argument. They
return exact 0 when the argument is exact 1.

\vspace{0.3cm}

\indexmethod{log10}

\noindent
\abstpuremethoddef{log10}{<number>}{<number>}
\puremethoddef{log10}{<integer>}{(:union <integer> <real> <complex>)}
\puremethoddef{log10}{<rational>}{(:union <integer> <real> <complex>)}
\puremethoddef{log10}{<real>}{(:union <real> <complex>)}
\puremethoddefwithvalue{log10}{<complex>}{<complex>}{c-log10}

These methods compute the logarithm with base 10 of the argument. They
return exact 0 when the argument is exact 1.

\vspace{0.3cm}

\indexmethod{sin}

\noindent
\abstpuremethoddef{sin}{<number>}{<number>}
\abstpuremethoddef{sin}{<real-number>}{(:union <real> <integer>)}
\puremethoddef{sin}{<integer>}{(:union <real> <integer>)}
\puremethoddef{sin}{<rational>}{(:union <real> <integer>)}
\puremethoddefwithvalue{sin}{<real>}{<real>}{r-sin}
\puremethoddefwithvalue{sin}{<complex>}{<complex>}{c-sin}

These methods compute the sine of the argument. They return
exact 0 when the argument is exact 0.

\vspace{0.3cm}

\indexmethod{cos}

\noindent
\abstpuremethoddef{cos}{<number>}{<number>}
\abstpuremethoddef{cos}{<real-number>}{(:union <real> <integer>)}
\puremethoddef{cos}{<integer>}{(:union <real> <integer>)}
\puremethoddef{cos}{<rational>}{(:union <real> <integer>)}
\puremethoddefwithvalue{cos}{<real>}{<real>}{r-cos}
\puremethoddefwithvalue{cos}{<complex>}{<complex>}{c-cos}

These methods compute the cosine of the argument. They return
exact 1 when the argument is exact 0.

\vspace{0.3cm}

\indexmethod{tan}

\noindent
\abstpuremethoddef{tan}{<number>}{<number>}
\abstpuremethoddef{tan}{<real-number>}{(:union <real> <integer>)}
\puremethoddef{tan}{<integer>}{(:union <real> <integer>)}
\puremethoddef{tan}{<rational>}{(:union <real> <integer>)}
\puremethoddefwithvalue{tan}{<real>}{<real>}{r-tan}
\puremethoddefwithvalue{tan}{<complex>}{<complex>}{c-tan}

These methods compute the tangent of the argument. They return
exact 0 when the argument is exact 0.

\vspace{0.3cm}

\indexmethod{asin}

\noindent
\abstpuremethoddef{asin}{<number>}{<number>}
\puremethoddef{asin}{<integer>}{(:union <integer> <real> <complex>)}
\puremethoddef{asin}{<rational>}{(:union <integer> <real> <complex>)}
\puremethoddef{asin}{<real>}{(:union <real> <complex>)}
\puremethoddefwithvalue{asin}{<complex>}{<complex>}{c-asin}

These methods compute the arcsine of the argument. They return exact 0
when the argument is exact 0. See the note for \code{c-asin}, which
may also apply when the argument is real.

\vspace{0.3cm}

\indexmethod{acos}

\noindent
\abstpuremethoddef{acos}{<number>}{<number>}
\puremethoddef{acos}{<integer>}{(:union <integer> <real> <complex>)}
\puremethoddef{acos}{<rational>}{(:union <integer> <real> <complex>)}
\puremethoddef{acos}{<real>}{(:union <real> <complex>)}
\puremethoddefwithvalue{acos}{<complex>}{<complex>}{c-acos}

These methods compute the arccosine of the argument. They return exact 0
when the argument is exact 1. See the note for \code{c-acos}, which
may also apply when the argument is real.

\vspace{0.3cm}

\indexmethod{atan}

\noindent
\abstpuremethoddef{atan}{<number>}{<number>}
\abstpuremethoddef{atan}{<real-number>}{<real-number>}
\puremethoddef{atan}{<integer>}{(:union <real> <integer>)}
\puremethoddef{atan}{<rational>}{(:union <real> <integer>)}
\puremethoddefwithvalue{atan}{<real>}{<real>}{r-atan}
\puremethoddefwithvalue{atan}{<complex>}{<complex>}{c-atan}

These methods compute the arctangent of the argument. They return
exact 0 when the argument is exact 0.

\vspace{0.3cm}

\indexmethod{sinh}

\noindent
\abstpuremethoddef{sinh}{<number>}{<number>}
\abstpuremethoddef{sinh}{<real-number>}{(:union <real> <integer>)}
\puremethoddef{sinh}{<integer>}{(:union <real> <integer>)}
\puremethoddef{sinh}{<rational>}{(:union <real> <integer>)}
\puremethoddefwithvalue{sinh}{<real>}{<real>}{r-sinh}
\puremethoddefwithvalue{sinh}{<complex>}{<complex>}{c-sinh}

These methods compute the hyperbolic sine of the argument. They return
exact 0 when the argument is exact 0.

\vspace{0.3cm}

\indexmethod{cosh}

\noindent
\abstpuremethoddef{cosh}{<number>}{<number>}
\abstpuremethoddef{cosh}{<real-number>}{(:union <real> <integer>)}
\puremethoddef{cosh}{<integer>}{(:union <real> <integer>)}
\puremethoddef{cosh}{<rational>}{(:union <real> <integer>)}
\puremethoddefwithvalue{cosh}{<real>}{<real>}{r-cosh}
\puremethoddefwithvalue{cosh}{<complex>}{<complex>}{c-cosh}

These methods compute the hyperbolic cosine of the argument. They return
exact 1 when the argument is exact 0.

\vspace{0.3cm}

\indexmethod{tanh}

\noindent
\abstpuremethoddef{tanh}{<number>}{<number>}
\abstpuremethoddef{tanh}{<real-number>}{(:union <real> <integer>)}
\puremethoddef{tanh}{<integer>}{(:union <real> <integer>)}
\puremethoddef{tanh}{<rational>}{(:union <real> <integer>)}
\puremethoddefwithvalue{tanh}{<real>}{<real>}{r-tanh}
\puremethoddefwithvalue{tanh}{<complex>}{<complex>}{c-tanh}

These methods compute the hyperbolic tangent of the argument. They return
exact 0 when the argument is exact 0.

\vspace{0.3cm}

\indexmethod{asinh}

\noindent
\abstpuremethoddef{asinh}{<number>}{<number>}
\abstpuremethoddef{asinh}{<real-number>}{(:union <real> <integer>)}
\puremethoddef{asinh}{<integer>}{(:union <real> <integer>)}
\puremethoddef{asinh}{<rational>}{(:union <real> <integer>)}
\puremethoddefwithvalue{asinh}{<real>}{<real>}{r-asinh}
\puremethoddefwithvalue{asinh}{<complex>}{<complex>}{c-asinh}

These methods compute the inverse hyperbolic sine of the argument. They return
exact 0 when the argument is exact 0.

\vspace{0.3cm}

\indexmethod{acosh}

\noindent
\abstpuremethoddef{acosh}{<number>}{<number>}
\puremethoddef{acosh}{<integer>}{(:union <integer> <real> <complex>)}
\puremethoddef{acosh}{<rational>}{(:union <integer> <real> <complex>)}
\puremethoddef{acosh}{<real>}{(:union <real> <complex>)}
\puremethoddefwithvalue{acosh}{<complex>}{<complex>}{c-acosh}

These methods compute the inverse hyperbolic cosine of the argument. They return
exact 0 when the argument is exact 1.

\vspace{0.3cm}

\indexmethod{atanh}

\noindent
\abstpuremethoddef{atanh}{<number>}{<number>}
\puremethoddef{atanh}{<integer>}{(:union <integer> <real> <complex>)}
\puremethoddef{atanh}{<rational>}{(:union <integer> <real> <complex>)}
\puremethoddef{atanh}{<real>}{(:union <real> <complex>)}
\puremethoddefwithvalue{atanh}{<complex>}{<complex>}{c-atanh}

These methods compute the inverse hyperbolic tangent of the
argument. They return exact 0 when the argument is exact 0.
See the note for \code{c-atanh}, which
may also apply when the argument is real.


\chapter{Module \code{(standard-library extra-math)}}


This module implements wrapper procedures to many of the mathematical
functions in standard C. Additionally, some helper procedures and
methods are defined.  This module works only for the target platform
Guile.


\section{Wrapper Procedures for Standard C Functions}


The following procedures are wrappers to the corresponding functions
in the standard C (without the prefix ``\code{r-}''):

\vspace{0.3cm}

\noindent
\shortpureprocdef{fmod}{<real> <real>}{<real>}
\shortpureprocdef{r-remainder}{<real> <real>}{<real>}
\shortpureprocdef{r-fma}{<real> <real> <real>}{<real>}
\shortpureprocdef{fmin}{<real> <real>}{<real>}
\shortpureprocdef{fmax}{<real> <real>}{<real>}
\shortpureprocdef{fdim}{<real> <real>}{<real>}
\shortpureprocdef{r-exp2}{<real>}{<real>}
\shortpureprocdef{r-expm1}{<real>}{<real>}
\shortpureprocdef{r-log2}{<real>}{<real>}
\shortpureprocdef{r-log1p}{<real>}{<real>}
\shortpureprocdef{logb}{<real>}{<real>}
\shortpureprocdef{ilogb}{<real>}{<integer>}
\shortpureprocdef{r-cbrt}{<real>}{<real>}
\shortpureprocdef{r-hypot}{<real> <real>}{<real>}
\shortpureprocdef{r-erf}{<real>}{<real>}
\shortpureprocdef{r-erfc}{<real>}{<real>}
\shortpureprocdef{r-lgamma}{<real>}{<real>}
\shortpureprocdef{r-tgamma}{<real>}{<real>}
\shortpureprocdef{r-nearbyint}{<real>}{<real>}
\shortpureprocdef{rint}{<real>}{<real>}
\shortpureprocdef{frexp}{<real>}{(:pair <real> <integer>)}
\shortpureprocdef{ldexp}{<real> <integer>}{<real>}
\shortpureprocdef{modf}{<real>}{(:pair <real> <real>)}
\shortpureprocdef{r-nextafter}{<real> <real>}{<real>}
\shortpureprocdef{r-copysign}{<real> <real>}{<real>}
\shortpureprocdef{fpclassify}{<real>}{<integer>}
\shortpureprocdef{r-isnormal?}{<real>}{<boolean>}
\shortpureprocdef{r-signbit}{<real>}{<integer>}


Procedure \code{frexp} returns the fraction of its argument in the
head of the result and the exponent in the tail. Procedure \code{modf}
returns the fractional part of its argument in the head of the result
and the integer part in the tail. There are no wrappers for
\code{isinf} and \code{isnan} since similar functions are defined
in the core module.
See e.g.

\vspace{0.3cm}

https://en.wikipedia.org/wiki/C\_mathematical\_functions

\vspace{0.3cm}
\noindent
and the GNU libc Reference for further documentation.


\section{Other Simple Methods}


\procdef{r-log2-neg}


\startprocsyntax
\begin{codeblock}
  (r-log2-neg r)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{r}{\code{<real>}}{A negative real number}
\end{arglist}


\procresult{The base 2 logarithm of \procarg{r}}%
{\code{<complex>}}


\procpurity{pure}


The base 2 logarithm of a negative real number \(r\) is
\begin{math}
  \log_2 r = \log_2 \left\vert r \right\vert + \textsf{i} \pi /
  \myln 2
\end{math}.


\procdef{i-cbrt}


\startprocsyntax
\begin{codeblock}
  (i-cbrt i)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{i}{\code{<integer>}}{An integer number}
\end{arglist}


\procresult{The cubic root of the argument}%
{\code{(:union <real> <integer>)}}


\procpurity{pure}


It seems that this procedure can't always detect integer valued
results because of floating point errors.


\procdef{rat-cbrt}


\startprocsyntax
\begin{codeblock}
  (rat-cbrt rat)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{rat}{\code{<rational>}}{A rational number}
\end{arglist}


\procresult{The cubic root of the argument}%
{\code{(:union <real> <rational> <integer>)}}


\procpurity{pure}


It seems that this procedure can't always detect integer or rational
valued results because of floating point errors.


\section{Virtual Methods}

\indexmethod{exp2}

\noindent
\abstpuremethoddef{exp2}{<number>}{<number>}
\abstpuremethoddef{exp2}{<real-number>}{<real-number>}
\puremethoddef{exp2}{<complex>}{<complex>}
\puremethoddefwithvalue{exp2}{<real>}{<real>}{r-exp2}
\puremethoddef{exp2}{<rational>}{<real-number>}
\puremethoddef{exp2}{<integer>}{<rational-number>}

These methods compute \(2^x\).

\vspace{0.3cm}

\indexmethod{expm1}

\noindent
\abstpuremethoddef{expm1}{<number>}{<number>}
\abstpuremethoddef{expm1}{<real-number>}{<real-number>}
\puremethoddef{expm1}{<complex>}{<complex>}
\puremethoddefwithvalue{expm1}{<real>}{<real>}{r-expm1}
\puremethoddef{expm1}{<rational>}{(:union <real> <integer>)}
\puremethoddef{expm1}{<integer>}{(:union <real> <integer>)}

These methods compute \(\exp x - 1\).

\vspace{0.3cm}

\indexmethod{log2}

\noindent
\abstpuremethoddef{log2}{<number>}{<number>}
\puremethoddef{log2}{<complex>}{<complex>}
\puremethoddef{log2}{<real>}{(:union <real> <complex>)}
\puremethoddef{log2}{<rational>}{(:union <integer> <real> <complex>)}
\puremethoddef{log2}{<integer>}{(:union <integer> <real> <complex>)}

These methods compute \(\log_2 x\).

\vspace{0.3cm}

\indexmethod{log1p}

\noindent
\abstpuremethoddef{log1p}{<number>}{<number>}
\puremethoddef{log1p}{<complex>}{<complex>}
\puremethoddef{log1p}{<real>}{(:union <complex> <real>)}
\puremethoddef{log1p}{<rational>}{(:union <complex> <real> <integer>)}
\puremethoddef{log1p}{<integer>}{(:union <complex> <real> <integer>)}

These methods compute \(\myln ( 1 + x )\).

\vspace{0.3cm}

\indexmethod{cbrt}

\noindent
\abstpuremethoddef{cbrt}{<number>}{<number>}
\abstpuremethoddef{cbrt}{<real-number>}{<real-number>}
\puremethoddef{cbrt}{<complex>}{<complex>}
\puremethoddefwithvalue{cbrt}{<real>}{<real>}{r-cbrt}
\puremethoddef{cbrt}{<rational>}{(:union <real> <rational> <integer>)}
\puremethoddef{cbrt}{<integer>}{(:union <real> <integer>)}

These methods compute the cubic root of \(x\). They are defined for
negative arguments, too.

\vspace{0.3cm}

\indexmethod{hypot}

\noindent
\abstpuremethoddef{hypot}{<real-number> <real-number>}{<real-number>}
\puremethoddefwithvalue{hypot}{<real> <real>}{<real>}{r-hypot}
\puremethoddef{hypot}{<real> <rational>}{<real>}
\puremethoddef{hypot}{<real> <integer>}{<real>}
\puremethoddef{hypot}{<rational> <real>}{<real>}
\puremethoddef{hypot}{<rational> <rational>}{<real-number>}
\puremethoddef{hypot}{<rational> <integer>}{<real-number>}
\puremethoddef{hypot}{<integer> <real>}{<real>}
\puremethoddef{hypot}{<integer> <rational>}{<real-number>}
\puremethoddef{hypot}{<integer> <integer>}{(:union <real> <integer>)}

These methods compute \(\sqrt{x^2+y^2}\).

\vspace{0.3cm}

\indexmethod{erf}

\noindent
\abstpuremethoddef{erf}{<real-number>}{(:union <real> <integer>)}
\puremethoddefwithvalue{erf}{<real>}{<real>}{r-erf}
\puremethoddef{erf}{<rational>}{(:union <real> <integer>)}
\puremethoddef{erf}{<integer>}{(:union <real> <integer>)}

These methods compute \(\erf x\) (the error function).

\vspace{0.3cm}

\indexmethod{erfc}

\noindent
\abstpuremethoddef{erfc}{<real-number>}{(:union <real> <integer>)}
\puremethoddefwithvalue{erfc}{<real>}{<real>}{r-erfc}
\puremethoddef{erfc}{<rational>}{(:union <real> <integer>)}
\puremethoddef{erfc}{<integer>}{(:union <real> <integer>)}

These methods compute \(\erfc x = 1 - \erf x\) (the complementary
error function).

\vspace{0.3cm}

\indexmethod{lgamma}

\noindent
\abstpuremethoddef{lgamma}{<real-number>}{(:union <real> <integer>)}
\puremethoddefwithvalue{lgamma}{<real>}{<real>}{r-lgamma}
\puremethoddef{lgamma}{<rational>}{(:union <real> <integer>)}
\puremethoddef{lgamma}{<integer>>}{(:union <real> <integer>)}

These methods compute \(\myln \left\vert \Gamma(x) \right\vert\).

\vspace{0.3cm}

\indexmethod{tgamma}

\noindent
\abstpuremethoddef{tgamma}{<real-number>}{(:union <real> <integer>)}
\puremethoddefwithvalue{tgamma}{<real>}{<real>}{r-tgamma}
\puremethoddef{tgamma}{<rational>}{(:union <real> <integer>)}
\puremethoddef{tgamma}{<integer>>}{(:union <real> <integer>)}

These methods compute \(\Gamma(x)\) (the gamma function). For positive
integers the exact value is computed as a factorial.


\chapter{Module \code{(standard-library posix-math)}}


This module implements wrapper procedures to many of the mathematical
functions in POSIX C not belonging to the C standard. Additionally,
some methods are defined.  This module works only for the target
platform Guile.

See e.g.

\vspace{0.3cm}

https://en.wikipedia.org/wiki/C\_POSIX\_library

\vspace{0.3cm}
\noindent
and the GNU libc Reference for further documentation.


\section{Wrapper Procedures for POSIX C Functions}

\noindent
\shortpureprocdef{r-j0}{<real>}{<real>}
\shortpureprocdef{r-j1}{<real>}{<real>}
\shortpureprocdef{r-jn}{<integer> <real>}{<real>}

\noindent
\shortpureprocdef{r-y0}{<real>}{<real>}
\shortpureprocdef{r-y1}{<real>}{<real>}
\shortpureprocdef{r-yn}{<integer> <real>}{<real>}


\section{Virtual Methods}

\indexmethod{j0}

\noindent
\abstpuremethoddef{j0}{<real-number>}{<real>}
\puremethoddefwithvalue{j0}{<real>}{<real>}{r-j0}
\puremethoddef{j0}{<rational>}{<real>}
\puremethoddef{j0}{<integer>}{<real>}

These methods compute the Bessel function \code{j0}.

\vspace{0.3cm}

\indexmethod{j1}

\noindent
\abstpuremethoddef{j1}{<real-number>}{<real>}
\puremethoddefwithvalue{j1}{<real>}{<real>}{r-j1}
\puremethoddef{j1}{<rational>}{<real>}
\puremethoddef{j1}{<integer>}{<real>}

These methods compute the Bessel function \code{j1}.

\vspace{0.3cm}

\indexmethod{jn}

\noindent
\abstpuremethoddef{jn}{<integer> <real-number>}{<real>}
\puremethoddefwithvalue{jn}{<integer> <real>}{<real>}{r-jn}
\puremethoddef{jn}{<integer> <rational>}{<real>}
\puremethoddef{jn}{<integer> <integer>}{<real>}

These methods compute the Bessel functions \code{jn}.

\vspace{0.3cm}

\indexmethod{y0}

\noindent
\abstpuremethoddef{y0}{<real-number>}{<real>}
\puremethoddefwithvalue{y0}{<real>}{<real>}{r-y0}
\puremethoddef{y0}{<rational>}{<real>}
\puremethoddef{y0}{<integer>}{<real>}

These methods compute the Bessel function \code{y0}.

\vspace{0.3cm}

\indexmethod{y1}

\noindent
\abstpuremethoddef{y1}{<real-number>}{<real>}
\puremethoddefwithvalue{y1}{<real>}{<real>}{r-y1}
\puremethoddef{y1}{<rational>}{<real>}
\puremethoddef{y1}{<integer>}{<real>}

These methods compute the Bessel function \code{y1}.

\vspace{0.3cm}

\indexmethod{yn}

\noindent
\abstpuremethoddef{yn}{<integer> <real-number>}{<real>}
\puremethoddefwithvalue{yn}{<integer> <real>}{<real>}{r-yn}
\puremethoddef{yn}{<integer> <rational>}{<real>}
\puremethoddef{yn}{<integer> <integer>}{<real>}

These methods compute the Bessel functions \code{yn}.


\chapter{Module \code{(standard-library matrix)}}


\section{Data Types}


\begin{datatype}
  \datatypename{:matrix}
  \datatypetype{\builtin{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{A matrix}
\end{datatype}


\begin{datatype}
  \datatypename{:diagonal-matrix}
  \datatypetype{\builtin{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{A diagonal matrix}
\end{datatype}


Note that the indices of the matrices have base zero.


\section{Simple Methods}


\procdef{construct-complex-matrix}


\startprocsyntax
\begin{codeblock}
  (construct-complex-matrix \procarg{mx-re} \procarg{mx-im})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{mx-re}{\code{(:matrix <real>)}}%
  {The real part of the result}
  \argument{mx-im}{\code{(:matrix <real>)}}%
  {The imaginary part of the result}
\end{arglist}


\procresult{A complex matrix with the given real and imaginary parts}%
{\code{(:matrix <complex>)}}


\procpurity{pure}


\procdef{construct-complex-matrix}


\startprocsyntax
\begin{codeblock}
  (construct-complex-matrix \procarg{mx-re} \procarg{mx-im})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{mx-re}{\code{(:diagonal-matrix <real>)}}%
  {The real part of the result}
  \argument{mx-im}{\code{(:diagonal-matrix <real>)}}%
  {The imaginary part of the result}
\end{arglist}


\procresult{A complex diagonal matrix with the given real and imaginary parts}%
{\code{(:diagonal-matrix <complex>)}}


\procpurity{pure}


\section{Parametrized Methods}


\procdef{matrix=}


\startprocsyntax
\begin{codeblock}
  (matrix= \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
  \argument{mx2}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{\true\ iff the arguments are numerically equal}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{diagonal-matrix=}


\startprocsyntax
\begin{codeblock}
  (diagonal-matrix= \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
  \argument{mx2}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{\true\ iff the arguments are numerically equal}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{matrix-diagonal-matrix=}


\startprocsyntax
\begin{codeblock}
  (matrix-diagonal-matrix= \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
  \argument{mx2}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{\true\ iff the arguments are numerically equal}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{diagonal-matrix-matrix=}


\startprocsyntax
\begin{codeblock}
  (diagonal-matrix-matrix= \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
  \argument{mx2}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{\true\ iff the arguments are numerically equal}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{column-vector}


\startprocsyntax
\begin{codeblock}
  (column-vector \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list \typeparam{number})}}%
  {The contents of the vector}
\end{arglist}


\procresult{A column vector constructed from the argument list}%
{\cbuiltin{(:matrix \typeparam{number})}}


\procpurity{pure}


\procdef{diagonal-matrix}


\startprocsyntax
\begin{codeblock}
  (diagonal-matrix \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list \typeparam{number})}}%
  {The contents of the diagonal}
\end{arglist}


\procresult{A diagonal matrix constructed from the argument list}%
{\cbuiltin{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


\procdef{diagonal-matrix*}


\startprocsyntax
\begin{codeblock}
  (diagonal-matrix* \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A diagonal matrix}
  \argument{mx2}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A diagonal matrix}
\end{arglist}


\procresult{Product of the given diagonal matrices}%
{\cbuiltin{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


\procdef{diagonal-matrix+}


\startprocsyntax
\begin{codeblock}
  (diagonal-matrix+ \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A diagonal matrix}
  \argument{mx2}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A diagonal matrix}
\end{arglist}


\procresult{Sum of the given diagonal matrices}%
{\cbuiltin{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


\procdef{diagonal-matrix-}


\startprocsyntax
\begin{codeblock}
  (diagonal-matrix- \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A diagonal matrix}
  \argument{mx2}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A diagonal matrix}
\end{arglist}


\procresult{Difference of the given diagonal matrices}%
{\cbuiltin{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


\procdef{diagonal-matrix-copy}


\startprocsyntax
\begin{codeblock}
  (diagonal-matrix-copy \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A diagonal matrix}
\end{arglist}


\procresult{A copy of the given diagonal matrix}%
{\cbuiltin{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


The contents of the argument and result matrices will be different
objects.


\procdef{diagonal-matrix-ref}


\startprocsyntax
\begin{codeblock}
  (diagonal-matrix-ref \procarg{mx} \procarg{index})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A diagonal matrix}
  \argument{index}{\builtin{<integer>}}{Index to the element}
\end{arglist}


\procresult{An element of the diagonal matrix}%
{\code{\typeparam{number}}}


\procpurity{pure}


\procdefexcl{diagonal-matrix-set!}{diagonal-matrix-set{"!}}


\startprocsyntax
\begin{codeblock}
  (diagonal-matrix-set! \procarg{mx} \procarg{index} \procarg{value})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A diagonal matrix}
  \argument{index}{\builtin{<integer>}}{Index to the element}
  \argument{value}{\code{\typeparam{number}}}%
           {The new value of the element}
\end{arglist}


\noprocresult


\procpurity{nonpure}


\procdef{make-column-vector}


\startprocsyntax
\begin{codeblock}
  (make-column-vector \procarg{len} \procarg{element-value})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{len}{\builtin{<integer>}}{The length of the vector}
  \argument{element-value}{\builtin{\typeparam{number}}}{A value to
    fill the vector}
\end{arglist}


\procresult{A column vector}%
{\cbuiltin{(:matrix \typeparam{number})}}


\procpurity{pure}


\procdef{make-diagonal-matrix}


\startprocsyntax
\begin{codeblock}
  (make-diagonal-matrix \procarg{len} \procarg{element-value})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{len}{\builtin{<integer>}}{The number of rows and columns
    in the diagonal matrix}
  \argument{element-value}{\builtin{\typeparam{number}}}{A value to
    fill the diagonal}
\end{arglist}


\procresult{A diagonal matrix}%
{\cbuiltin{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


\procdef{make-matrix}


\startprocsyntax
\begin{codeblock}
  (make-matrix \procarg{rows} \procarg{columns} \procarg{element-value})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{rows}{\builtin{<integer>}}{Number of rows in the matrix}
  \argument{columns}{\builtin{<integer>}}{Number of columns in the matrix}
  \argument{element-value}{\builtin{\typeparam{number}}}{A value to
    fill the matrix}
\end{arglist}


\procresult{A matrix}%
{\cbuiltin{(:matrix \typeparam{number})}}


\procpurity{pure}


\procdef{make-row-vector}


\startprocsyntax
\begin{codeblock}
  (make-row-vector \procarg{len} \procarg{element-value})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{len}{\builtin{<integer>}}{The length of the vector}
  \argument{element-value}{\builtin{\typeparam{number}}}{A value to
    fill the vector}
\end{arglist}


\procresult{A row vector}%
{\cbuiltin{(:matrix \typeparam{number})}}


\procpurity{pure}


\procdef{matrix}
\label{sec:matrix}


\startprocsyntax
\begin{codeblock}
  (matrix \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list (:uniform-list \typeparam{number}))}}%
  {The contents of the matrix}
\end{arglist}


\procresult{A matrix constructed from the argument list}%
{\cbuiltin{(:matrix \typeparam{number})}}


\procpurity{pure}


The argument type shall be a list of number lists. Each sublist gives
the contents of one row in the matrix. All of the sublists must have
equal lengths.


\procdef{matrix*}


\startprocsyntax
\begin{codeblock}
  (matrix* \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
  \argument{mx2}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{Product of the given matrices}%
{\cbuiltin{(:matrix \typeparam{number})}}


\procpurity{pure}


\procdef{matrix+}


\startprocsyntax
\begin{codeblock}
  (matrix+ \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
  \argument{mx2}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{Sum of the given matrices}%
{\cbuiltin{(:matrix \typeparam{number})}}


\procpurity{pure}


\procdef{matrix-}


\startprocsyntax
\begin{codeblock}
  (matrix- \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
  \argument{mx2}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{Difference of the given matrices}%
{\cbuiltin{(:matrix \typeparam{number})}}


\procpurity{pure}


\procdef{matrix-copy}


\startprocsyntax
\begin{codeblock}
  (matrix-copy \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{A copy of the given matrix}%
{\cbuiltin{(:matrix \typeparam{number})}}


\procpurity{pure}


The contents of the argument and result matrices will be different
objects.


\procdef{row-vector}


\startprocsyntax
\begin{codeblock}
  (row-vector \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{(:uniform-list \typeparam{number})}}%
  {The contents of the vector}
\end{arglist}


\procresult{A row vector constructed from the argument list}%
{\cbuiltin{(:matrix \typeparam{number})}}


\procpurity{pure}


\procdef{matrix-conj}


\startprocsyntax
\begin{codeblock}
  (matrix-conj \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{Conjugate matrix of the argument}%
{\code{(:matrix \typeparam{number})}}


\procpurity{pure}


\procdef{transpose}


\startprocsyntax
\begin{codeblock}
  (transpose \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{Transpose of the argument}%
{\code{(:matrix \typeparam{number})}}


\procpurity{pure}


\procdef{herm}


\startprocsyntax
\begin{codeblock}
  (herm \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{Hermitian conjugate of the argument}%
{\code{(:matrix \typeparam{number})}}


\procpurity{pure}


\procdef{diag-of}


\startprocsyntax
\begin{codeblock}
  (diag-of \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{Diagonal of the argument}%
{\code{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


Note that the argument need not be a square matrix.


\procdef{generate-matrix}


\startprocsyntax
\begin{codeblock}
  (generate-matrix \procarg{i-rows} \procarg{i-columns} \procarg{proc})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{i-rows}{\builtin{<integer>}}%
  {Number of rows in the matrix}
  \argument{i-columns}{\builtin{<integer>}}%
  {Number of columns in the matrix}
  \argument{proc}{\code{(:procedure (<integer> <integer>) \typeparam{number} pure)}}%
  {The procedure to generate the elements of the matrix}
\end{arglist}


\procresult{A matrix}%
{\code{(:matrix \typeparam{number})}}


\procpurity{pure}


This method uses the argument procedure to generate a matrix.
The indices of the elements are passed to the argument procedure.


\procdef{generate-diag-matrix}


\startprocsyntax
\begin{codeblock}
  (generate-diag-matrix \procarg{i-numel} \procarg{proc})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{i-numel}{\builtin{<integer>}}%
  {Number of elements in the diagonal matrix}
  \argument{proc}{\code{(:procedure (<integer>) \typeparam{number} pure)}}%
  {The procedure to generate the elements of the diagonal matrix}
\end{arglist}


\procresult{A diagonal matrix}%
{\code{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


This method uses the argument procedure to generate a diagonal matrix.
The indices of the elements are passed to the argument procedure.


\procdef{matrix-map}


\startprocsyntax
\begin{codeblock}
  (matrix-map \procarg{proc} \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{number}) \typeparam{number} pure)}}%
  {The procedure to apply to the elements}
  \argument{mx}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{A matrix}%
{\code{(:matrix \typeparam{number})}}


\procpurity{pure}


The result matrix is constructed by applying the argument procedure to
the elements of the argument matrix.


\procdef{matrix-map}


\startprocsyntax
\begin{codeblock}
  (matrix-map \procarg{proc} \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{number}) \typeparam{number} pure)}}%
  {The procedure to apply to the elements}
  \argument{mx}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A diagonal matrix}
\end{arglist}


\procresult{A diagonal matrix}%
{\code{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


The result matrix is constructed by applying the argument procedure to
the elements of the argument matrix.


\procdef{matrix-map-w-ind}


\startprocsyntax
\begin{codeblock}
  (matrix-map-w-ind \procarg{proc} \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<integer> <integer> \typeparam{number}) \typeparam{number} pure)}}%
  {The procedure to apply to the elements}
  \argument{mx}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{A matrix}%
{\code{(:matrix \typeparam{number})}}


\procpurity{pure}


The result matrix is constructed by applying the argument procedure to
the elements of the argument matrix. The indices of the elements are
passed to the procedure, too.


\procdef{diag-matrix-map-w-ind}


\startprocsyntax
\begin{codeblock}
  (diag-matrix-map-w-ind \procarg{proc} \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<integer> \typeparam{number}) \typeparam{number} pure)}}%
  {The procedure to apply to the elements}
  \argument{mx}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{A diagonal matrix}%
{\code{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


The result matrix is constructed by applying the argument procedure to
the elements of the argument matrix. The indices of the elements are
passed to the procedure, too.


\section{Parametrized Virtual Methods}


\procdef{=}


\startprocsyntax
\begin{codeblock}
  (= \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:matrix \typeparam{number})} or %
    \code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
  \argument{mx2}{\code{(:matrix \typeparam{number})} or %
    \code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{\true\ iff the arguments are numerically equal}%
{\builtin{<boolean>}}


\procpurity{pure}


All combinations of \code{(:matrix \typeparam{number})} and
\code{(:diagonal-matrix \typeparam{number})} as argument types
are supported.


\procdef{*}


\startprocsyntax
\begin{codeblock}
  (* \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:matrix \typeparam{number})} or %
    \code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
  \argument{mx2}{\code{(:matrix \typeparam{number})} or %
    \code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{The product of the matrices}%
{\code{\typeparam{number}}}


\procpurity{pure}


All combinations of \code{(:matrix \typeparam{number})} and
\code{(:diagonal-matrix \typeparam{number})} as argument types
are supported.


\procdef{*}


\startprocsyntax
\begin{codeblock}
  (* \procarg{nr} \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{nr}{\code{\typeparam{number}}}
  {A scalar}
  \argument{mx}{\code{(:matrix \typeparam{number})} or %
    \code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{The product of the number and the matrix}%
{\code{(:matrix \typeparam{number})} or %
  \code{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


The result type is the same as the type of argument \procarg{mx}.


\procdef{*}


\startprocsyntax
\begin{codeblock}
  (* \procarg{mx} \procarg{nr})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:matrix \typeparam{number})} or %
    \code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
  \argument{nr}{\code{\typeparam{number}}}
  {A scalar}
\end{arglist}


\procresult{The product of the matrix and the number}%
{\code{(:matrix \typeparam{number})} or %
  \code{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


The result type is the same as the type of argument \procarg{mx}.


\procdef{/}


\startprocsyntax
\begin{codeblock}
  (/ \procarg{mx} \procarg{nr})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:matrix \typeparam{number})} or %
    \code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
  \argument{nr}{\code{\typeparam{number}}}
  {A scalar}
\end{arglist}


\procresult{The quotient of the matrix and the number}%
{\code{(:matrix \typeparam{number})} or %
  \code{(:diagonal-matrix \typeparam{number})}}


\procpurity{pure}


The result type is the same as the type of argument \procarg{mx}.


\procdef{+}


\startprocsyntax
\begin{codeblock}
  (+ \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:matrix \typeparam{number})} or %
    \code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
  \argument{mx2}{\code{(:matrix \typeparam{number})} or %
    \code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{The sum of the matrices}%
{\code{\typeparam{number}}}


\procpurity{pure}


All combinations of \code{(:matrix \typeparam{number})} and
\code{(:diagonal-matrix \typeparam{number})} as argument types
are supported.


\procdef{-}


\startprocsyntax
\begin{codeblock}
  (- \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:matrix \typeparam{number})} or %
    \code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{The opposite matrix}%
{\code{\typeparam{number}}}


\procpurity{pure}


The result type is the same as the type of argument \procarg{mx}.


\procdef{-}


\startprocsyntax
\begin{codeblock}
  (- \procarg{mx1} \procarg{mx2})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:matrix \typeparam{number})} or %
    \code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
  \argument{mx2}{\code{(:matrix \typeparam{number})} or %
    \code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{The difference of the matrices}%
{\code{\typeparam{number}}}


\procpurity{pure}


All combinations of \code{(:matrix \typeparam{number})} and
\code{(:diagonal-matrix \typeparam{number})} as argument types
are supported.


\procdef{matrix-ref}


\startprocsyntax
\begin{codeblock}
  (matrix-ref \procarg{mx} \procarg{row} \procarg{column})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
  \argument{row}{\builtin{<integer>}}{Row index}
  \argument{column}{\builtin{<integer>}}{Column index}
\end{arglist}


\procresult{The element of the matrix at the given position}%
{\code{\typeparam{number}}}


\procpurity{pure}


\procdef{matrix-ref}


\startprocsyntax
\begin{codeblock}
  (matrix-ref \procarg{mx} \procarg{row} \procarg{column})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
  \argument{row}{\builtin{<integer>}}{Row index}
  \argument{column}{\builtin{<integer>}}{Column index}
\end{arglist}


\procresult{The element of the matrix at the given position}%
{\code{\typeparam{number}}}


\procpurity{pure}


Note that elements outside the diagonal are zero.


\procdefexcl{matrix-set!}{matrix-set{"!}}


\startprocsyntax
\begin{codeblock}
  (matrix-set! \procarg{mx} \procarg{row} \procarg{column} \procarg{element-value})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
  \argument{row}{\builtin{<integer>}}{Row index}
  \argument{column}{\builtin{<integer>}}{Column index}
  \argument{element-value}{\code{\typeparam{number}}}%
  {The new value at the specified position}
\end{arglist}


\noprocresult


\procpurity{nonpure}


\procdefexcl{matrix-set!}{matrix-set{"!}}


\startprocsyntax
\begin{codeblock}
  (matrix-set! \procarg{mx} \procarg{row} \procarg{column} \procarg{element-value})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
  \argument{row}{\builtin{<integer>}}{Row index}
  \argument{column}{\builtin{<integer>}}{Column index}
  \argument{element-value}{\code{\typeparam{number}}}%
  {The new value at the specified position}
\end{arglist}


\noprocresult


\procpurity{nonpure}


The row and column indices have to be equal.


\procdef{number-of-columns}


\startprocsyntax
\begin{codeblock}
  (number-of-columns \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{Number of columns in the matrix}%
{\cbuiltin{<integer>}}


\procpurity{pure}


\procdef{number-of-columns}


\startprocsyntax
\begin{codeblock}
  (number-of-columns \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{Length of the diagonal}%
{\cbuiltin{<integer>}}


\procpurity{pure}


\procdef{number-of-rows}


\startprocsyntax
\begin{codeblock}
  (number-of-rows \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{Number of rows in the matrix}%
{\cbuiltin{<integer>}}


\procpurity{pure}


\procdef{number-of-rows}


\startprocsyntax
\begin{codeblock}
  (number-of-rows \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx}{\code{(:diagonal-matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{Length of the diagonal}%
{\cbuiltin{<integer>}}


\procpurity{pure}


\procdef{conj}


\startprocsyntax
\begin{codeblock}
  (conj \procarg{mx})
\end{codeblock}


\typeparams{\typeparam{number}}


\startprocarguments
\begin{arglist}
  \argument{mx1}{\code{(:matrix \typeparam{number})}}%
  {A matrix}
\end{arglist}


\procresult{Conjugate matrix of the argument}%
{\code{(:matrix \typeparam{number})}}


\procpurity{pure}


\chapter{Module \code{(standard-library bvm-matrix-base)}}


\section{Data Types}


\begin{datatype}
  \datatypename{:bvm-matrix}
  \datatypetype{\builtin{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{A matrix stored as double precision numbers}
\end{datatype}


\begin{datatype}
  \datatypename{:bvm-single-matrix}
  \datatypetype{\builtin{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{A matrix stored as single precision numbers}
\end{datatype}


\begin{datatype}
  \datatypename{<bvm-matrix>}
  \datatypedef{(:bvm-matrix <real>)}
\end{datatype}


\begin{datatype}
  \datatypename{<bvm-complex-matrix>}
  \datatypedef{(:bvm-matrix <complex>)}
\end{datatype}


\begin{datatype}
  \datatypename{<bvm-single-matrix>}
  \datatypedef{(:bvm-single-matrix <real>)}
\end{datatype}


\begin{datatype}
  \datatypename{<bvm-single-complex-matrix>}
  \datatypedef{(:bvm-single-matrix <complex>)}
\end{datatype}


\vspace{1cm}


Note that the indices of the matrices have base zero.


\section{Simple Methods}


\indexmethod{bvm-ref}
\normalpuremethoddef{bvm-ref}{<bvm-matrix> <integer> %
  <integer>}{<real>}
\normalpuremethoddef{bvm-ref}{<bvm-complex-matrix> <integer> %
  <integer>}{<complex>}
\normalpuremethoddef{bvm-ref}{<bvm-single-matrix> <integer> %
  <integer>}{<real>}
\normalpuremethoddef{bvm-ref}{<bvm-single-complex-matrix> <integer> %
  <integer>}{<complex>}

\shortprocarguments
\begin{arglist}
  \shortargument{mx}{a matrix}
  \shortargument{i1}{row index}
  \shortargument{i2}{column index}
\end{arglist}

\shortprocdesc

\noindent
Return the element of the matrix at the given indices.

\vspace{0.5cm}

\indexmethod{bvm-set{"!}}
\noindent
\normalmethoddef{bvm-set!}{<bvm-matrix> <integer> %
  <integer> <real>}{<none>}
\normalmethoddef{bvm-set!}{<bvm-complex-matrix> <integer> %
  <integer> <complex>}{<none>}
\normalmethoddef{bvm-set!}{<bvm-single-matrix> <integer> %
  <integer> <real>}{<none>}
\normalmethoddef{bvm-set!}{<bvm-single-complex-matrix> <integer> %
  <integer> <complex>}{<none>}

\shortprocarguments
\begin{arglist}
  \shortargument{mx}{a matrix}
  \shortargument{i1}{row index}
  \shortargument{i2}{column index}
  \shortargument{value}{new value of the element}
\end{arglist}

\shortprocdesc

\noindent
These methods set the element of the argument matrix at the given
indices to the new value.


\vspace{0.5cm}

\indexmethod{bvm-make-matrix}
\noindent
\normalpuremethoddef{bvm-make-matrix}{<integer> <integer> <real>}{<bvm-matrix>}
\normalpuremethoddef{bvm-make-matrix}{<integer> <integer> <complex>}{<bvm-complex-matrix>}
\indexmethod{bvm-make-single-matrix}
\noindent
\normalpuremethoddef{bvm-make-single-matrix}{<integer> <integer> <real>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm-make-single-matrix}{<integer> <integer> <complex>}{<bvm-single-complex-matrix>}

\shortprocarguments
\begin{arglist}
  \shortargument{i-rows}{number of rows}
  \shortargument{i-columns}{number of columns}
  \shortargument{element-value}{the initial value of the elements}
\end{arglist}

\shortprocdesc

\noindent
These methods return a matrix filled with the given value.


\vspace{0.5cm}

\indexmethod{construct-complex-matrix}
\noindent
\normalpuremethoddef{construct-complex-matrix}{<bvm-matrix> <bvm-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{construct-complex-matrix}{<bvm-single-matrix> <bvm-single-matrix>}{<bvm-single-complex-matrix>}

\shortprocarguments
\begin{arglist}
  \shortargument{mx-re}{the real part}
  \shortargument{mx-im}{the imaginary part}
\end{arglist}

\shortprocdesc

\noindent
These procedures construct a complex matrix with given real and
imaginary parts.


\vspace{0.5cm}

\indexmethod{->real-matrix}
\indexmethod{->single-matrix}
\indexmethod{->complex-matrix}
\indexmethod{->single-complex-matrix}
\noindent
\normalpuremethoddef{->real-matrix}{<bvm-matrix>}{<bvm-matrix>}
\normalpuremethoddef{->real-matrix}{<bvm-single-matrix>}{<bvm-matrix>}
\normalpuremethoddef{->single-matrix}{<bvm-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{->single-matrix}{<bvm-single-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{->complex-matrix}{<bvm-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{->complex-matrix}{<bvm-single-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{->complex-matrix}{<bvm-complex-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{->complex-matrix}{<bvm-single-complex-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{->single-complex-matrix}{<bvm-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{->single-complex-matrix}{<bvm-single-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{->single-complex-matrix}{<bvm-complex-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{->single-complex-matrix}{<bvm-single-complex-matrix>}{<bvm-complex-matrix>}

\shortprocdesc

\noindent
These procedures convert the argument matrix to another type.


\vspace{0.5cm}

\indexmethod{bvm+}
\noindent
\normalpuremethoddef{bvm+}{<bvm-matrix> <bvm-matrix>}{<bvm-matrix>}
\normalpuremethoddef{bvm+}{<bvm-complex-matrix> <bvm-complex-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm+}{<bvm-single-matrix> <bvm-single-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm+}{<bvm-single-complex-matrix> <bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}

\shortprocdesc

\noindent
These procedures compute the sum of the arguments.


\vspace{0.5cm}

\indexmethod{bvm-}
\noindent
\normalpuremethoddef{bvm-}{<bvm-matrix> <bvm-matrix>}{<bvm-matrix>}
\normalpuremethoddef{bvm-}{<bvm-complex-matrix> <bvm-complex-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm-}{<bvm-single-matrix> <bvm-single-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm-}{<bvm-single-complex-matrix> <bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}

\shortprocdesc

\noindent
These procedures compute the difference of the arguments.


\vspace{0.5cm}

\indexmethod{bvm-}
\noindent
\normalpuremethoddef{bvm-}{<bvm-matrix>}{<bvm-matrix>}
\normalpuremethoddef{bvm-}{<bvm-complex-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm-}{<bvm-single-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm-}{<bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}

\shortprocdesc

\noindent
These procedures compute the opposite matrix of the argument.


\vspace{0.5cm}

\indexmethod{bvm-copy}
\noindent
\normalpuremethoddef{bvm-copy}{<bvm-matrix>}{<bvm-matrix>}
\normalpuremethoddef{bvm-copy}{<bvm-complex-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm-copy}{<bvm-single-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm-copy}{<bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}

\shortprocdesc

\noindent
These procedures copy the argument so that the contents of the result
are stored in a separate memory area.


\vspace{0.5cm}

\indexmethod{bvm-fill!}
\noindent
\normalmethoddef{bvm-fill!}{<bvm-matrix> <real>}{<none>}
\normalmethoddef{bvm-fill!}{<bvm-complex-matrix> <complex>}{<none>}
\normalmethoddef{bvm-fill!}{<bvm-single-matrix> <real>}{<none>}
\normalmethoddef{bvm-fill!}{<bvm-single-complex-matrix> <complex>}{<none>}

\shortprocdesc

\noindent
These procedures fill the argument matrix with the given value.


\vspace{0.5cm}

\indexmethod{real-part}
\indexmethod{imag-part}
\noindent
\normalpuremethoddef{real-part}{<bvm-complex-matrix>}{<bvm-matrix>}
\normalpuremethoddef{real-part}{<bvm-single-complex-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{imag-part}{<bvm-complex-matrix>}{<bvm-matrix>}
\normalpuremethoddef{imag-part}{<bvm-single-complex-matrix>}{<bvm-single-matrix>}

\shortprocdesc

\noindent
These procedures compute the real and imaginary parts of the argument.


\vspace{0.5cm}

\indexmethod{bvm=}
\noindent
\normalpuremethoddef{bvm=}{<bvm-matrix> <bvm-matrix>}{<boolean>}
\normalpuremethoddef{bvm=}{<bvm-complex-matrix> <bvm-complex-matrix>}{<boolean>}
\normalpuremethoddef{bvm=}{<bvm-single-matrix> <bvm-single-matrix>}{<boolean>}
\normalpuremethoddef{bvm=}{<bvm-single-complex-matrix> <bvm-single-complex-matrix>}{<boolean>}

\shortprocdesc

\noindent
These procedures return \true\ iff the argument matrices are
identical. If the argument sizes are different return \false.


\vspace{0.5cm}

\indexmethod{bvm*}
\noindent
\normalpuremethoddef{bvm*}{<real> <bvm-matrix>}{<bvm-matrix>}
\normalpuremethoddef{bvm*}{<bvm-matrix> <real>}{<bvm-matrix>}
\normalpuremethoddef{bvm*}{<complex> <bvm-complex-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm*}{<bvm-complex-matrix> <complex>}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm*}{<real> <bvm-single-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm*}{<bvm-single-matrix> <real>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm*}{<complex> <bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}
\normalpuremethoddef{bvm*}{<bvm-single-complex-matrix> <complex>}{<bvm-single-complex-matrix>}

\shortprocdesc

\noindent
These procedures compute the product of a scalar and a matrix.


\vspace{0.5cm}

\indexmethod{bvm-column-vector}
\indexmethod{bvm-row-vector}
\indexmethod{bvm-single-column-vector}
\indexmethod{bvm-single-row-vector}
\noindent
\normalpuremethoddef{bvm-column-vector}{(:uniform-list <real>)}{<bvm-matrix>}
\normalpuremethoddef{bvm-column-vector}{(:uniform-list <complex>)}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm-single-column-vector}{(:uniform-list <real>)}{<bvm-single-matrix>}
\normalpuremethoddef{bvm-single-column-vector}{(:uniform-list <complex>)}{<bvm-single-complex-matrix>}
\normalpuremethoddef{bvm-row-vector}{(:uniform-list <real>)}{<bvm-matrix>}
\normalpuremethoddef{bvm-row-vector}{(:uniform-list <complex>)}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm-single-row-vector}{(:uniform-list <real>)}{<bvm-single-matrix>}
\normalpuremethoddef{bvm-single-row-vector}{(:uniform-list <complex>)}{<bvm-single-complex-matrix>}

\shortprocdesc

\noindent
These procedures construct column and row vectors (matrices).


\section{Parametrized Methods}


\indexmethod{bvm-matrix}
\indexmethod{bvm-single-matrix}
\noindent
\normalpuremethoddef{bvm-matrix}{(:uniform-list (:uniform-list
  \typeparam{number}))}{(:bvm-matrix \typeparam{number})}
\normalpuremethoddef{bvm-single-matrix}{(:uniform-list (:uniform-list
  \typeparam{number}))}{(:bvm-single-matrix \typeparam{number})}

\shortprocdesc

\noindent
These procedures make a matrix so that its elements are taken from a
list structure.


\vspace{0.5cm}

\indexmethod{bvm-rows}
\indexmethod{bvm-columns}
\noindent
\normalpuremethoddef{bvm-rows}{(:bvm-matrix \typeparam{number})}{<integer>}
\normalpuremethoddef{bvm-rows}{(:bvm-single-matrix \typeparam{number})}{<integer>}
\normalpuremethoddef{bvm-columns}{(:bvm-matrix \typeparam{number})}{<integer>}
\normalpuremethoddef{bvm-columns}{(:bvm-single-matrix \typeparam{number})}{<integer>}

\shortprocdesc

\noindent
These procedures return the number of rows and columns in a matrix.


\vspace{0.5cm}

\indexmethod{bvm*}
\noindent
\normalpuremethoddef{bvm*}{(:bvm-matrix \typeparam{number}) (:bvm-matrix \typeparam{number})}{(:bvm-matrix \typeparam{number})}
\normalpuremethoddef{bvm*}{(:bvm-single-matrix \typeparam{number}) (:bvm-single-matrix \typeparam{number})}{(:bvm-single-matrix \typeparam{number})}

\shortprocdesc

\noindent
These procedures compute matrix products.


\vspace{0.5cm}

\indexmethod{transpose}
\noindent
\normalpuremethoddef{transpose}{(:bvm-matrix \typeparam{number})}{(:bvm-matrix \typeparam{number})}
\normalpuremethoddef{transpose}{(:bvm-single-matrix \typeparam{number})}{(:bvm-single-matrix \typeparam{number})}

\shortprocdesc

\noindent
These procedures compute the transpose of a matrix.


\vspace{0.5cm}

\indexmethod{bvm-conj}
\noindent
\normalpuremethoddef{bvm-conj}{(:bvm-matrix \typeparam{number})}{(:bvm-matrix \typeparam{number})}
\normalpuremethoddef{bvm-conj}{(:bvm-single-matrix \typeparam{number})}{(:bvm-single-matrix \typeparam{number})}

\shortprocdesc

\noindent
These procedures compute the complex conjugate of a matrix.


\vspace{0.5cm}

\indexmethod{herm}
\noindent
\normalpuremethoddef{herm}{(:bvm-matrix \typeparam{number})}{(:bvm-matrix \typeparam{number})}
\normalpuremethoddef{herm}{(:bvm-single-matrix \typeparam{number})}{(:bvm-single-matrix \typeparam{number})}

\shortprocdesc

\noindent
These procedures compute the Hermitian conjugate of a matrix.


\vspace{0.5cm}

\indexmethod{bvm-generate-matrix}
\noindent
\normalpuremethoddef{bvm-generate-matrix}{<integer> <integer> %
  (:procedure (<integer> <integer>) \typeparam{number} pure)}%
{(:bvm-matrix \typeparam{number})}

\shortprocdesc

\noindent
This procedure generates a matrix using a procedure that takes matrix
indices as its arguments.


\vspace{0.5cm}

\indexmethod{bvm-generate-single-matrix}
\noindent
\normalpuremethoddef{bvm-generate-single-matrix}{<integer> <integer> %
  (:procedure (<integer> <integer>) \typeparam{number} pure)}%
{(:bvm-single-matrix \typeparam{number})}

\shortprocdesc

\noindent
This procedure generates a single precision matrix using a procedure
that takes matrix indices as its arguments.


\vspace{0.5cm}

\indexmethod{matrix-map}
\noindent
\normalpuremethoddef{matrix-map}{(:procedure (\typeparam{number})
  \typeparam{number} pure) (:bvm-matrix \typeparam{number})}{(:bvm-matrix \typeparam{number})}
\normalpuremethoddef{matrix-map}{(:procedure (\typeparam{number})
  \typeparam{number} pure) (:bvm-single-matrix \typeparam{number})}{(:bvm-single-matrix \typeparam{number})}

\shortprocdesc

\noindent
These procedures map the argument procedure to the elements of the
argument matrix.


\vspace{0.5cm}

\indexmethod{matrix-map-w-ind}
\noindent
\normalpuremethoddef{matrix-map-w-ind}{(:procedure (<integer>
  <integer> \typeparam{number})
  \typeparam{number} pure) (:bvm-matrix \typeparam{number})}{(:bvm-matrix \typeparam{number})}
\normalpuremethoddef{matrix-map-w-ind}{(:procedure (<integer>
  <integer> \typeparam{number})
  \typeparam{number} pure) (:bvm-single-matrix \typeparam{number})}{(:bvm-single-matrix \typeparam{number})}

\shortprocdesc

\noindent
These procedures map the argument procedure to the elements of the
argument matrix. The element indices are passed to the argument
procedure, too.


\section{Virtual Simple Methods}


\indexmethod{matrix-ref}
\puremethoddefwithincl{matrix-ref}{<bvm-matrix> <integer> %
  <integer>}{<real>}{bvm-ref}
\puremethoddefwithincl{matrix-ref}{<bvm-complex-matrix> <integer> %
  <integer>}{<complex>}{bvm-ref}
\puremethoddefwithincl{matrix-ref}{<bvm-single-matrix> <integer> %
  <integer>}{<real>}{bvm-ref}
\puremethoddefwithincl{matrix-ref}{<bvm-single-complex-matrix> <integer> %
  <integer>}{<complex>}{bvm-ref}


\vspace{0.5cm}

\indexmethod{matrix-set{"!}}
\noindent
\puremethoddefwithincl{matrix-set!}{<bvm-matrix> <integer> %
  <integer> <real>}{<none>}{bvm-set!}
\puremethoddefwithincl{matrix-set!}{<bvm-complex-matrix> <integer> %
  <integer> <complex>}{<none>}{bvm-set!}
\puremethoddefwithincl{matrix-set!}{<bvm-single-matrix> <integer> %
  <integer> <real>}{<none>}{bvm-set!}
\puremethoddefwithincl{matrix-set!}{<bvm-single-complex-matrix> <integer> %
  <integer> <complex>}{<none>}{bvm-set!}


\vspace{0.5cm}

\indexmethod{+}
\noindent
\puremethoddefwithincl{+}{<bvm-matrix> <bvm-matrix>}{<bvm-matrix>}{bvm+}
\puremethoddefwithincl{+}{<bvm-complex-matrix> <bvm-complex-matrix>}{<bvm-complex-matrix>}{bvm+}
\puremethoddefwithincl{+}{<bvm-single-matrix> <bvm-single-matrix>}{<bvm-single-matrix>}{bvm+}
\puremethoddefwithincl{+}{<bvm-single-complex-matrix> <bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}{bvm+}


\vspace{0.5cm}

\indexmethod{-}
\noindent
\puremethoddefwithincl{-}{<bvm-matrix> <bvm-matrix>}{<bvm-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-complex-matrix> <bvm-complex-matrix>}{<bvm-complex-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-single-matrix> <bvm-single-matrix>}{<bvm-single-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-single-complex-matrix> <bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}{bvm-}


\vspace{0.5cm}

\indexmethod{-}
\noindent
\puremethoddefwithincl{-}{<bvm-matrix>}{<bvm-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-complex-matrix>}{<bvm-complex-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-single-matrix>}{<bvm-single-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}{bvm-}


\vspace{0.5cm}

\indexmethod{*}
\noindent
\puremethoddefwithincl{*}{<real> <bvm-matrix>}{<bvm-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-matrix> <real>}{<bvm-matrix>}{bvm*}
\puremethoddefwithincl{*}{<complex> <bvm-complex-matrix>}{<bvm-complex-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-complex-matrix> <complex>}{<bvm-complex-matrix>}{bvm*}
\puremethoddefwithincl{*}{<real> <bvm-single-matrix>}{<bvm-single-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-single-matrix> <real>}{<bvm-single-matrix>}{bvm*}
\puremethoddefwithincl{*}{<complex> <bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-single-complex-matrix> <complex>}{<bvm-single-complex-matrix>}{bvm*}


\vspace{0.5cm}

\indexmethod{=}
\noindent
\puremethoddefwithincl{=}{<bvm-matrix> <bvm-matrix>}{<boolean>}{bvm=}
\puremethoddefwithincl{=}{<bvm-complex-matrix> <bvm-complex-matrix>}{<boolean>}{bvm=}
\puremethoddefwithincl{=}{<bvm-single-matrix> <bvm-single-matrix>}{<boolean>}{bvm=}
\puremethoddefwithincl{=}{<bvm-single-complex-matrix> <bvm-single-complex-matrix>}{<boolean>}{bvm=}


\section{Parametrized Virtual Methods}


\indexmethod{number-of-rows}
\indexmethod{number-of-columns}
\noindent
\puremethoddefwithincl{number-of-rows}{(:bvm-matrix \typeparam{number})}{<integer>}{bvm-rows}
\puremethoddefwithincl{number-of-rows}{(:bvm-single-matrix \typeparam{number})}{<integer>}{bvm-rows}
\puremethoddefwithincl{number-of-columns}{(:bvm-matrix \typeparam{number})}{<integer>}{bvm-columns}
\puremethoddefwithincl{number-of-columns}{(:bvm-single-matrix \typeparam{number})}{<integer>}{bvm-columns}


\vspace{0.5cm}

\indexmethod{*}
\noindent
\puremethoddefwithincl{*}{(:bvm-matrix \typeparam{number}) (:bvm-matrix \typeparam{number})}{(:bvm-matrix \typeparam{number})}{bvm*}
\puremethoddefwithincl{*}{(:bvm-single-matrix \typeparam{number}) (:bvm-single-matrix \typeparam{number})}{(:bvm-single-matrix \typeparam{number})}{bvm*}


\vspace{0.5cm}

\indexmethod{conj}
\noindent
\puremethoddefwithincl{conj}{(:bvm-matrix \typeparam{number})}{(:bvm-matrix \typeparam{number})}{bvm-conj}
\puremethoddefwithincl{conj}{(:bvm-single-matrix \typeparam{number})}{(:bvm-single-matrix \typeparam{number})}{bvm-conj}


\chapter{Module \code{(standard-library bvm-diag-matrix)}}


\section{Data Types}


\begin{datatype}
  \datatypename{:bvm-diag-matrix}
  \datatypetype{\builtin{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{A diagonal matrix stored as double precision numbers}
\end{datatype}


\begin{datatype}
  \datatypename{:bvm-single-diag-matrix}
  \datatypetype{\builtin{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{A diagonal matrix stored as single precision numbers}
\end{datatype}


\begin{datatype}
  \datatypename{<bvm-diag-matrix>}
  \datatypedef{(:bvm-diag-matrix <real>)}
\end{datatype}


\begin{datatype}
  \datatypename{<bvm-complex-diag-matrix>}
  \datatypedef{(:bvm-diag-matrix <complex>)}
\end{datatype}


\begin{datatype}
  \datatypename{<bvm-single-diag-matrix>}
  \datatypedef{(:bvm-single-diag-matrix <real>)}
\end{datatype}


\begin{datatype}
  \datatypename{<bvm-single-complex-diag-matrix>}
  \datatypedef{(:bvm-single-diag-matrix <complex>)}
\end{datatype}


\section{Simple Methods}


\indexmethod{bvm-ref}
\normalpuremethoddef{bvm-ref}{<bvm-diag-matrix> <integer> %
  <integer>}{<real>}
\normalpuremethoddef{bvm-ref}{<bvm-complex-diag-matrix> <integer> %
  <integer>}{<complex>}
\normalpuremethoddef{bvm-ref}{<bvm-single-diag-matrix> <integer> %
  <integer>}{<real>}
\normalpuremethoddef{bvm-ref}{<bvm-single-complex-diag-matrix> <integer> %
  <integer>}{<complex>}

\shortprocarguments
\begin{arglist}
  \shortargument{mx}{a diagonal matrix}
  \shortargument{i1}{row index}
  \shortargument{i2}{column index}
\end{arglist}

\shortprocdesc

\noindent
Return the element of the matrix at the given indices. If the indices
are not equal return zero.


\vspace{0.5cm}

\indexmethod{bvm-set{"!}}
\noindent
\normalmethoddef{bvm-set!}{<bvm-diag-matrix> <integer> %
  <integer> <real>}{<none>}
\normalmethoddef{bvm-set!}{<bvm-complex-diag-matrix> <integer> %
  <integer> <complex>}{<none>}
\normalmethoddef{bvm-set!}{<bvm-single-diag-matrix> <integer> %
  <integer> <real>}{<none>}
\normalmethoddef{bvm-set!}{<bvm-single-complex-diag-matrix> <integer> %
  <integer> <complex>}{<none>}

\shortprocarguments
\begin{arglist}
  \shortargument{mx}{a diagonal matrix}
  \shortargument{i1}{row index}
  \shortargument{i2}{column index}
  \shortargument{value}{new value of the element}
\end{arglist}

\shortprocdesc

\noindent
These methods set the element of the argument matrix at the given
indices to the new value. If the indices are not equal raise an
exception.


\vspace{0.5cm}

\indexmethod{diagonal-matrix-ref}
\noindent
\normalpuremethoddef{diagonal-matrix-ref}{<bvm-diag-matrix> <integer>}{<real>}
\normalpuremethoddef{diagonal-matrix-ref}{<bvm-complex-diag-matrix> <integer>}{<complex>}
\normalpuremethoddef{diagonal-matrix-ref}{<bvm-single-diag-matrix> <integer>}{<real>}
\normalpuremethoddef{diagonal-matrix-ref}{<bvm-single-complex-diag-matrix> <integer>}{<complex>}

\shortprocarguments
\begin{arglist}
  \shortargument{mx}{a diagonal matrix}
  \shortargument{i}{index (for both row and column)}
\end{arglist}

\shortprocdesc

\noindent
Return the element of the matrix at the given index.


\vspace{0.5cm}

\indexmethod{diagonal-matrix-set{"!}}
\noindent
\normalmethoddef{diagonal-matrix-set!}{<bvm-diag-matrix> <integer> %
  <real>}{<none>}
\normalmethoddef{diagonal-matrix-set!}{<bvm-complex-diag-matrix> <integer> %
  <complex>}{<none>}
\normalmethoddef{diagonal-matrix-set!}{<bvm-single-diag-matrix> <integer> %
  <real>}{<none>}
\normalmethoddef{diagonal-matrix-set!}{<bvm-single-complex-diag-matrix> <integer> %
  <complex>}{<none>}

\shortprocarguments
\begin{arglist}
  \shortargument{mx}{a diagonal matrix}
  \shortargument{i}{index (for both row and column)}
  \shortargument{value}{new value of the element}
\end{arglist}

\shortprocdesc

\noindent
These methods set the element of the argument matrix at the given
index to the new value.


\vspace{0.5cm}

\indexmethod{bvm-make-diag-matrix}
\indexmethod{bvm-make-single-diag-matrix}
\noindent
\normalpuremethoddef{bvm-make-diag-matrix}{<integer> %
  <real>}{<bvm-diag-matrix>}
\normalpuremethoddef{bvm-make-diag-matrix}{<integer> %
  <complex>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{bvm-make-single-diag-matrix}{<integer> %
  <real>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{bvm-make-single-diag-matrix}{<integer> %
  <complex>}{<bvm-single-complex-diag-matrix>}

\shortprocarguments
\begin{arglist}
  \shortargument{i-numel}{number of elements}
  \shortargument{element-value}{the initial value of the elements}
\end{arglist}

\shortprocdesc

\noindent
These methods return a diagonal matrix filled with the given value.


\vspace{0.5cm}

\indexmethod{construct-complex-diag-matrix}
\noindent
\normalpuremethoddef{construct-complex-diag-matrix}{<bvm-diag-matrix> <bvm-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{construct-complex-diag-matrix}{<bvm-single-diag-matrix> <bvm-single-diag-matrix>}{<bvm-single-complex-diag-matrix>}

\shortprocarguments
\begin{arglist}
  \shortargument{mx-re}{the real part}
  \shortargument{mx-im}{the imaginary part}
\end{arglist}

\shortprocdesc

\noindent
These procedures construct a complex diagonal matrix with given real and
imaginary parts.


\vspace{0.5cm}

\indexmethod{->real-diag-matrix}
\indexmethod{->single-diag-matrix}
\indexmethod{->complex-diag-matrix}
\indexmethod{->single-complex-diag-matrix}
\noindent
\normalpuremethoddef{->real-diag-matrix}{<bvm-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{->real-diag-matrix}{<bvm-single-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{->single-diag-matrix}{<bvm-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{->single-diag-matrix}{<bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{->complex-diag-matrix}{<bvm-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{->complex-diag-matrix}{<bvm-single-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{->complex-diag-matrix}{<bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{->complex-diag-matrix}{<bvm-single-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{->single-complex-diag-matrix}{<bvm-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{->single-complex-diag-matrix}{<bvm-single-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{->single-complex-diag-matrix}{<bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{->single-complex-diag-matrix}{<bvm-single-complex-diag-matrix>}{<bvm-complex-diag-matrix>}

\shortprocdesc

\noindent
These procedures convert the argument diagonal matrix to another type.


\vspace{0.5cm}

\indexmethod{bvm+}
\noindent
\normalpuremethoddef{bvm+}{<bvm-diag-matrix> <bvm-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{bvm+}{<bvm-complex-diag-matrix> <bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{bvm+}{<bvm-single-diag-matrix> <bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{bvm+}{<bvm-single-complex-diag-matrix> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}

\noindent
\normalpuremethoddef{bvm+}{<bvm-diag-matrix> <bvm-matrix>}{<bvm-matrix>}
\normalpuremethoddef{bvm+}{<bvm-complex-diag-matrix> <bvm-complex-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm+}{<bvm-single-diag-matrix> <bvm-single-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm+}{<bvm-single-complex-diag-matrix> <bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}

\noindent
\normalpuremethoddef{bvm+}{<bvm-matrix> <bvm-diag-matrix>}{<bvm-matrix>}
\normalpuremethoddef{bvm+}{<bvm-complex-matrix> <bvm-complex-diag-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm+}{<bvm-single-matrix> <bvm-single-diag-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm+}{<bvm-single-complex-matrix> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-matrix>}

\shortprocdesc

\noindent
These procedures compute the sum of the arguments.


\vspace{0.5cm}

\indexmethod{bvm-}
\noindent
\normalpuremethoddef{bvm-}{<bvm-diag-matrix> <bvm-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{bvm-}{<bvm-complex-diag-matrix> <bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{bvm-}{<bvm-single-diag-matrix> <bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{bvm-}{<bvm-single-complex-diag-matrix> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}

\noindent
\normalpuremethoddef{bvm-}{<bvm-diag-matrix> <bvm-matrix>}{<bvm-matrix>}
\normalpuremethoddef{bvm-}{<bvm-complex-diag-matrix> <bvm-complex-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm-}{<bvm-single-diag-matrix> <bvm-single-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm-}{<bvm-single-complex-diag-matrix> <bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}

\noindent
\normalpuremethoddef{bvm-}{<bvm-matrix> <bvm-diag-matrix>}{<bvm-matrix>}
\normalpuremethoddef{bvm-}{<bvm-complex-matrix> <bvm-complex-diag-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm-}{<bvm-single-matrix> <bvm-single-diag-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm-}{<bvm-single-complex-matrix> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-matrix>}

\shortprocdesc

\noindent
These procedures compute the difference of the arguments.


\vspace{0.5cm}

\indexmethod{bvm-}
\noindent
\normalpuremethoddef{bvm-}{<bvm-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{bvm-}{<bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{bvm-}{<bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{bvm-}{<bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}

\shortprocdesc

\noindent
These procedures compute the opposite matrix of the argument.


\vspace{0.5cm}

\indexmethod{bvm*}
\noindent
\normalpuremethoddef{bvm*}{<bvm-diag-matrix> <bvm-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{bvm*}{<bvm-complex-diag-matrix> <bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{bvm*}{<bvm-single-diag-matrix> <bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{bvm*}{<bvm-single-complex-diag-matrix> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}

\noindent
\normalpuremethoddef{bvm*}{<bvm-diag-matrix> <bvm-matrix>}{<bvm-matrix>}
\normalpuremethoddef{bvm*}{<bvm-complex-diag-matrix> <bvm-complex-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm*}{<bvm-single-diag-matrix> <bvm-single-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm*}{<bvm-single-complex-diag-matrix> <bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}

\noindent
\normalpuremethoddef{bvm*}{<bvm-matrix> <bvm-diag-matrix>}{<bvm-matrix>}
\normalpuremethoddef{bvm*}{<bvm-complex-matrix> <bvm-complex-diag-matrix>}{<bvm-complex-matrix>}
\normalpuremethoddef{bvm*}{<bvm-single-matrix> <bvm-single-diag-matrix>}{<bvm-single-matrix>}
\normalpuremethoddef{bvm*}{<bvm-single-complex-matrix> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-matrix>}

\shortprocdesc

\noindent
These procedures compute the matrix product of the arguments.


\vspace{0.5cm}

\indexmethod{bvm*}
\noindent
\normalpuremethoddef{bvm*}{<real> <bvm-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{bvm*}{<bvm-diag-matrix> <real>}{<bvm-diag-matrix>}
\normalpuremethoddef{bvm*}{<complex> <bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{bvm*}{<bvm-complex-diag-matrix> <complex>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{bvm*}{<real> <bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{bvm*}{<bvm-single-diag-matrix> <real>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{bvm*}{<complex> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}
\normalpuremethoddef{bvm*}{<bvm-single-complex-diag-matrix> <complex>}{<bvm-single-complex-diag-matrix>}

\shortprocdesc

\noindent
These procedures compute the product of a scalar and a diagonal matrix.


\vspace{0.5cm}

\indexmethod{bvm-copy}
\noindent
\normalpuremethoddef{bvm-copy}{<bvm-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{bvm-copy}{<bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{bvm-copy}{<bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{bvm-copy}{<bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}

\shortprocdesc

\noindent
These procedures copy the argument so that the contents of the result
are stored in a separate memory area.


\vspace{0.5cm}

\indexmethod{bvm-fill!}
\noindent
\normalmethoddef{bvm-fill!}{<bvm-diag-matrix> <real>}{<none>}
\normalmethoddef{bvm-fill!}{<bvm-complex-diag-matrix> <complex>}{<none>}
\normalmethoddef{bvm-fill!}{<bvm-single-diag-matrix> <real>}{<none>}
\normalmethoddef{bvm-fill!}{<bvm-single-complex-diag-matrix> <complex>}{<none>}

\shortprocdesc

\noindent
These procedures fill the argument matrix with the given value.


\vspace{0.5cm}

\indexmethod{real-part}
\indexmethod{imag-part}
\noindent
\normalpuremethoddef{real-part}{<bvm-complex-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{real-part}{<bvm-single-complex-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{imag-part}{<bvm-complex-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{imag-part}{<bvm-single-complex-diag-matrix>}{<bvm-single-diag-matrix>}

\shortprocdesc

\noindent
These procedures compute the real and imaginary parts of the argument.


\vspace{0.5cm}

\indexmethod{bvm=}
\noindent
\normalpuremethoddef{bvm=}{<bvm-diag-matrix> <bvm-diag-matrix>}{<boolean>}
\normalpuremethoddef{bvm=}{<bvm-complex-diag-matrix> <bvm-complex-diag-matrix>}{<boolean>}
\normalpuremethoddef{bvm=}{<bvm-single-diag-matrix> <bvm-single-diag-matrix>}{<boolean>}
\normalpuremethoddef{bvm=}{<bvm-single-complex-diag-matrix> <bvm-single-complex-matrix>}{<boolean>}

\noindent
\normalpuremethoddef{bvm=}{<bvm-diag-matrix> <bvm-matrix>}{<boolean>}
\normalpuremethoddef{bvm=}{<bvm-complex-diag-matrix> <bvm-complex-matrix>}{<boolean>}
\normalpuremethoddef{bvm=}{<bvm-single-diag-matrix> <bvm-single-matrix>}{<boolean>}
\normalpuremethoddef{bvm=}{<bvm-single-complex-diag-matrix> <bvm-single-complex-matrix>}{<boolean>}

\noindent
\normalpuremethoddef{bvm=}{<bvm-matrix> <bvm-diag-matrix>}{<boolean>}
\normalpuremethoddef{bvm=}{<bvm-complex-matrix> <bvm-complex-diag-matrix>}{<boolean>}
\normalpuremethoddef{bvm=}{<bvm-single-matrix> <bvm-single-diag-matrix>}{<boolean>}
\normalpuremethoddef{bvm=}{<bvm-single-complex-matrix> <bvm-single-complex-diag-matrix>}{<boolean>}

\shortprocdesc

\noindent
These procedures return \true\ iff the argument matrices are
identical. If the argument sizes are different return \false.


\vspace{0.5cm}

\indexmethod{bvm-conj}
\noindent
\normalpuremethoddef{bvm-conj}{<bvm-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{bvm-conj}{<bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{bvm-conj}{<bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{bvm-conj}{<bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}

\shortprocdesc

\noindent
These procedures compute the conjugate of the argument.


\vspace{0.5cm}

\indexmethod{transpose}
\noindent
\normalpuremethoddef{transpose}{<bvm-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{transpose}{<bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{transpose}{<bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{transpose}{<bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}

\shortprocdesc

\noindent
These procedures compute the transpose of the argument.


\vspace{0.5cm}

\indexmethod{herm}
\noindent
\normalpuremethoddef{herm}{<bvm-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{herm}{<bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{herm}{<bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{herm}{<bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}

\shortprocdesc

\noindent
These procedures compute the Hermitian conjugate of the argument.


\vspace{0.5cm}

\indexmethod{diag-of}
\noindent
\normalpuremethoddef{diag-of}{<bvm-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{diag-of}{<bvm-complex-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{diag-of}{<bvm-single-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{diag-of}{<bvm-single-complex-matrix>}{<bvm-single-complex-diag-matrix>}

\shortprocdesc

\noindent
These procedures return the diagonal of the argument.
Note that the argument need not be a square matrix.


\vspace{0.5cm}

\indexmethod{bvm-generate-diag-matrix}
\noindent
\normalpuremethoddef{bvm-generate-diag-matrix}{<integer> %
  (:procedure (<integer>) <real> pure)}%
{<bvm-diag-matrix>}
\normalpuremethoddef{bvm-generate-diag-matrix}{<integer> %
  (:procedure (<integer>) <complex> pure)}%
{<bvm-complex-diag-matrix>}
                    
\indexmethod{bvm-generate-single-diag-matrix}
\noindent
\normalpuremethoddef{bvm-generate-single-diag-matrix}{<integer> %
  (:procedure (<integer>) <real> pure)}%
{<bvm-single-diag-matrix>}
\normalpuremethoddef{bvm-generate-single-diag-matrix}{<integer> %
  (:procedure (<integer>) <complex> pure)}%
{<bvm-single-complex-diag-matrix>}

\shortprocdesc

\noindent
These procedures generate a diagonal matrix using a procedure that takes matrix
index as its argument.


\vspace{0.5cm}

\indexmethod{matrix-map}
\noindent
\normalpuremethoddef{matrix-map}{(:procedure (<real>) <real> pure) %
  <bvm-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{matrix-map}{(:procedure (<complex>) <complex> pure) %
  <bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{matrix-map}{(:procedure (<real>) <real> pure) %
  <bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{matrix-map}{(:procedure (<complex>) <complex> pure) %
  <bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}

\shortprocdesc

\noindent
These procedures map the argument procedure to the elements of the
argument matrix.


\vspace{0.5cm}

\indexmethod{diag-matrix-map-w-ind}
\noindent
\normalpuremethoddef{diag-matrix-map-w-ind}{(:procedure (<integer> <real>) <real> pure) %
  <bvm-diag-matrix>}{<bvm-diag-matrix>}
\normalpuremethoddef{diag-matrix-map-w-ind}{(:procedure (<integer> <complex>) <complex> pure) %
  <bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}
\normalpuremethoddef{diag-matrix-map-w-ind}{(:procedure (<integer> <real>) <real> pure) %
  <bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}
\normalpuremethoddef{diag-matrix-map-w-ind}{(:procedure (<integer> <complex>) <complex> pure) %
  <bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}

\shortprocdesc

\noindent
These procedures map the argument procedure to the elements of the
argument matrix. The element index is passed to the argument
procedure, too.


\section{Parametrized Methods}


\indexmethod{bvm-diag-matrix}
\indexmethod{bvm-single-diag-matrix}
\noindent
\normalpuremethoddef{bvm-diag-matrix}{(:uniform-list %
  \typeparam{number})}{(:bvm-diag-matrix \typeparam{number})}
\normalpuremethoddef{bvm-single-diag-matrix}{(:uniform-list %
  \typeparam{number})}{(:bvm-single-diag-matrix \typeparam{number})}

\shortprocdesc

\noindent
These procedures make a diagonal matrix so that its elements are taken from a
list.


\vspace{0.5cm}

\indexmethod{bvm-rows}
\indexmethod{bvm-columns}
\noindent
\normalpuremethoddef{bvm-rows}{(:bvm-diag-matrix \typeparam{number})}{<integer>}
\normalpuremethoddef{bvm-rows}{(:bvm-single-diag-matrix \typeparam{number})}{<integer>}
\normalpuremethoddef{bvm-columns}{(:bvm-diag-matrix \typeparam{number})}{<integer>}
\normalpuremethoddef{bvm-columns}{(:bvm-single-diag-matrix \typeparam{number})}{<integer>}

\shortprocdesc

\noindent
These procedures return the number of rows and columns (i.e. the
number of elements) in a diagonal matrix.


\vspace{0.5cm}

\indexmethod{diag-matrix-numel}
\noindent
\normalpuremethoddef{diag-matrix-numel}{(:bvm-diag-matrix \typeparam{number})}{<integer>}
\normalpuremethoddef{diag-matrix-numel}{(:bvm-single-diag-matrix \typeparam{number})}{<integer>}

\shortprocdesc

\noindent
These procedures return the number of elements in a diagonal matrix.


\vspace{0.5cm}

\indexmethod{diag->normal-matrix}
\noindent
\normalpuremethoddef{diag->normal-matrix}{(:bvm-diag-matrix %
  \typeparam{number})}{(:bvm-matrix \typeparam{number})}
\normalpuremethoddef{diag->normal-matrix}{(:bvm-single-diag-matrix %
  \typeparam{number})}{(:bvm-single-matrix \typeparam{number})}

\shortprocdesc

\noindent
These procedures convert a diagonal matrix to a normal matrix.


\section{Simple Virtual Methods}


\indexmethod{matrix-ref}
\puremethoddefwithincl{matrix-ref}{<bvm-diag-matrix> <integer> %
  <integer>}{<real>}{bvm-ref}
\puremethoddefwithincl{matrix-ref}{<bvm-complex-diag-matrix> <integer> %
  <integer>}{<complex>}{bvm-ref}
\puremethoddefwithincl{matrix-ref}{<bvm-single-diag-matrix> <integer> %
  <integer>}{<real>}{bvm-ref}
\puremethoddefwithincl{matrix-ref}{<bvm-single-complex-diag-matrix> <integer> %
  <integer>}{<complex>}{bvm-ref}


\vspace{0.5cm}

\indexmethod{matrix-set{"!}}
\noindent
\puremethoddefwithincl{matrix-set!}{<bvm-diag-matrix> <integer> %
  <integer> <real>}{<none>}{bvm-set!}
\puremethoddefwithincl{matrix-set!}{<bvm-complex-diag-matrix> <integer> %
  <integer> <complex>}{<none>}{bvm-set!}
\puremethoddefwithincl{matrix-set!}{<bvm-single-diag-matrix> <integer> %
  <integer> <real>}{<none>}{bvm-set!}
\puremethoddefwithincl{matrix-set!}{<bvm-single-complex-diag-matrix> <integer> %
  <integer> <complex>}{<none>}{bvm-set!}


\vspace{0.5cm}

\indexmethod{+}
\noindent
\puremethoddefwithincl{+}{<bvm-diag-matrix> <bvm-diag-matrix>}{<bvm-diag-matrix>}{bvm+}
\puremethoddefwithincl{+}{<bvm-complex-diag-matrix> <bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}{bvm+}
\puremethoddefwithincl{+}{<bvm-single-diag-matrix> <bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}{bvm+}
\puremethoddefwithincl{+}{<bvm-single-complex-diag-matrix> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}{bvm+}

\noindent
\puremethoddefwithincl{+}{<bvm-diag-matrix> <bvm-matrix>}{<bvm-matrix>}{bvm+}
\puremethoddefwithincl{+}{<bvm-complex-diag-matrix> <bvm-complex-matrix>}{<bvm-complex-matrix>}{bvm+}
\puremethoddefwithincl{+}{<bvm-single-diag-matrix> <bvm-single-matrix>}{<bvm-single-matrix>}{bvm+}
\puremethoddefwithincl{+}{<bvm-single-complex-diag-matrix> <bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}{bvm+}

\noindent
\puremethoddefwithincl{+}{<bvm-matrix> <bvm-diag-matrix>}{<bvm-matrix>}{bvm+}
\puremethoddefwithincl{+}{<bvm-complex-matrix> <bvm-complex-diag-matrix>}{<bvm-complex-matrix>}{bvm+}
\puremethoddefwithincl{+}{<bvm-single-matrix> <bvm-single-diag-matrix>}{<bvm-single-matrix>}{bvm+}
\puremethoddefwithincl{+}{<bvm-single-complex-matrix> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-matrix>}{bvm+}


\vspace{0.5cm}

\indexmethod{-}
\noindent
\puremethoddefwithincl{-}{<bvm-diag-matrix> <bvm-diag-matrix>}{<bvm-diag-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-complex-diag-matrix> <bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-single-diag-matrix> <bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-single-complex-diag-matrix> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}{bvm-}

\noindent
\puremethoddefwithincl{-}{<bvm-diag-matrix> <bvm-matrix>}{<bvm-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-complex-diag-matrix> <bvm-complex-matrix>}{<bvm-complex-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-single-diag-matrix> <bvm-single-matrix>}{<bvm-single-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-single-complex-diag-matrix> <bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}{bvm-}

\noindent
\puremethoddefwithincl{-}{<bvm-matrix> <bvm-diag-matrix>}{<bvm-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-complex-matrix> <bvm-complex-diag-matrix>}{<bvm-complex-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-single-matrix> <bvm-single-diag-matrix>}{<bvm-single-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-single-complex-matrix> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-matrix>}{bvm-}


\vspace{0.5cm}

\indexmethod{-}
\noindent
\puremethoddefwithincl{-}{<bvm-diag-matrix>}{<bvm-diag-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}{bvm-}
\puremethoddefwithincl{-}{<bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}{bvm-}


\vspace{0.5cm}

\indexmethod{*}
\noindent
\puremethoddefwithincl{*}{<bvm-diag-matrix> <bvm-diag-matrix>}{<bvm-diag-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-complex-diag-matrix> <bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-single-diag-matrix> <bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-single-complex-diag-matrix> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}{bvm*}

\noindent
\puremethoddefwithincl{*}{<bvm-diag-matrix> <bvm-matrix>}{<bvm-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-complex-diag-matrix> <bvm-complex-matrix>}{<bvm-complex-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-single-diag-matrix> <bvm-single-matrix>}{<bvm-single-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-single-complex-diag-matrix> <bvm-single-complex-matrix>}{<bvm-single-complex-matrix>}{bvm*}

\noindent
\puremethoddefwithincl{*}{<bvm-matrix> <bvm-diag-matrix>}{<bvm-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-complex-matrix> <bvm-complex-diag-matrix>}{<bvm-complex-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-single-matrix> <bvm-single-diag-matrix>}{<bvm-single-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-single-complex-matrix> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-matrix>}{bvm*}


\vspace{0.5cm}

\indexmethod{*}
\noindent
\puremethoddefwithincl{*}{<real> <bvm-diag-matrix>}{<bvm-diag-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-diag-matrix> <real>}{<bvm-diag-matrix>}{bvm*}
\puremethoddefwithincl{*}{<complex> <bvm-complex-diag-matrix>}{<bvm-complex-diag-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-complex-diag-matrix> <complex>}{<bvm-complex-diag-matrix>}{bvm*}
\puremethoddefwithincl{*}{<real> <bvm-single-diag-matrix>}{<bvm-single-diag-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-single-diag-matrix> <real>}{<bvm-single-diag-matrix>}{bvm*}
\puremethoddefwithincl{*}{<complex> <bvm-single-complex-diag-matrix>}{<bvm-single-complex-diag-matrix>}{bvm*}
\puremethoddefwithincl{*}{<bvm-single-complex-diag-matrix> <complex>}{<bvm-single-complex-diag-matrix>}{bvm*}


\vspace{0.5cm}

\indexmethod{=}
\noindent
\puremethoddefwithincl{=}{<bvm-diag-matrix> <bvm-diag-matrix>}{<boolean>}{bvm=}
\puremethoddefwithincl{=}{<bvm-complex-diag-matrix> <bvm-complex-diag-matrix>}{<boolean>}{bvm=}
\puremethoddefwithincl{=}{<bvm-single-diag-matrix> <bvm-single-diag-matrix>}{<boolean>}{bvm=}
\puremethoddefwithincl{=}{<bvm-single-complex-diag-matrix> <bvm-single-complex-diag-matrix>}{<boolean>}{bvm=}

\noindent
\puremethoddefwithincl{=}{<bvm-diag-matrix> <bvm-matrix>}{<boolean>}{bvm=}
\puremethoddefwithincl{=}{<bvm-complex-diag-matrix> <bvm-complex-matrix>}{<boolean>}{bvm=}
\puremethoddefwithincl{=}{<bvm-single-diag-matrix> <bvm-single-matrix>}{<boolean>}{bvm=}
\puremethoddefwithincl{=}{<bvm-single-complex-diag-matrix> <bvm-single-complex-matrix>}{<boolean>}{bvm=}

\noindent
\puremethoddefwithincl{=}{<bvm-matrix> <bvm-diag-matrix>}{<boolean>}{bvm=}
\puremethoddefwithincl{=}{<bvm-complex-matrix> <bvm-complex-diag-matrix>}{<boolean>}{bvm=}
\puremethoddefwithincl{=}{<bvm-single-matrix> <bvm-single-diag-matrix>}{<boolean>}{bvm=}
\puremethoddefwithincl{=}{<bvm-single-complex-matrix> <bvm-single-complex-diag-matrix>}{<boolean>}{bvm=}


\vspace{0.5cm}

\indexmethod{conj}
\noindent
\puremethoddefwithincl{conj}{<bvm-diag-matrix> <bvm-diag-matrix>}{<boolean>}{bvm-conj}
\puremethoddefwithincl{conj}{<bvm-complex-diag-matrix> <bvm-complex-diag-matrix>}{<boolean>}{bvm-conj}
\puremethoddefwithincl{conj}{<bvm-single-diag-matrix> <bvm-single-diag-matrix>}{<boolean>}{bvm-conj}
\puremethoddefwithincl{conj}{<bvm-single-complex-diag-matrix> <bvm-single-complex-diag-matrix>}{<boolean>}{bvm-conj}


\section{Parametrized Virtual Methods}

\indexmethod{number-of-rows}
\indexmethod{number-of-columns}
\noindent
\puremethoddefwithincl{number-of-rows}{(:bvm-diag-matrix \typeparam{number})}{<integer>}{bvm-rows}
\puremethoddefwithincl{number-of-rows}{(:bvm-single-diag-matrix \typeparam{number})}{<integer>}{bvm-rows}
\puremethoddefwithincl{number-of-columns}{(:bvm-diag-matrix \typeparam{number})}{<integer>}{bvm-columns}
\puremethoddefwithincl{number-of-columns}{(:bvm-single-diag-matrix \typeparam{number})}{<integer>}{bvm-columns}


\chapter{Module \code{(standard-library dynamic-list)}}


\section{Simple Methods}


\procdef{d-append0}


\startprocsyntax
\begin{codeblock}
  (d-append0 lst)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{<object>}}%
  {A list consisting of lists}
\end{arglist}


\procresult{A list constructed by concatenating the argument lists}%
{\cbuiltin{<object>}}


\procpurity{pure}


The lists are concatenated in the order they are given.


\procdef{d-append2}


\startprocsyntax
\begin{codeblock}
  (d-append2 lst1 lst2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst1}{\code{<object>}}{A list}
  \argument{lst2}{\code{<object>}}{A list}
\end{arglist}


\procresult{A list constructed by concatenating the argument lists}%
{\cbuiltin{<object>}}


\procpurity{pure}


\procdef{d-append}


\startprocsyntax
\begin{codeblock}
  (d-append lst-1 ... lst-n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst-k}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{A list constructed by concatenating the argument lists}%
{\cbuiltin{<object>}}


\procpurity{pure}


The lists are concatenated in the order they are given.


\procdef{d-car}


\startprocsyntax
\begin{codeblock}
  (d-car \procarg{obj})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\code{<object>}}%
  {An object}
\end{arglist}


\procresult{The head of the pair}%
{\cbuiltin{<object>}}


\procpurity{pure}


If the argument is not a pair an exception is raised.


\procdef{d-cdr}


\startprocsyntax
\begin{codeblock}
  (d-cdr \procarg{obj})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\code{<object>}}%
  {An object}
\end{arglist}


\procresult{The tail of the pair}%
{\cbuiltin{<object>}}


\procpurity{pure}


If the argument is not a pair an exception is raised.


\procdef{d-caar}


\startprocsyntax
\begin{codeblock}
  (d-caar \procarg{x})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{<object>}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\cbuiltin{<object>}}


\procpurity{pure}


Expression \code{(d-caar x)} is equivalent to \code{(d-car (d-car x))}.


\procdef{d-cadr}


\startprocsyntax
\begin{codeblock}
  (d-cadr \procarg{x})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{<object>}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\cbuiltin{<object>}}


\procpurity{pure}


Expression \code{(d-cadr x)} is equivalent to \code{(d-car (d-cdr x))}.


\procdef{d-cdar}


\startprocsyntax
\begin{codeblock}
  (d-cdar \procarg{x})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{<object>}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\cbuiltin{<object>}}


\procpurity{pure}


Expression \code{(d-cdar x)} is equivalent to \code{(d-cdr (d-car x))}.


\procdef{d-cddr}


\startprocsyntax
\begin{codeblock}
  (d-cddr \procarg{x})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{<object>}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\cbuiltin{<object>}}


\procpurity{pure}


Expression \code{(d-cddr x)} is equivalent to \code{(d-cdr (d-cdr x))}.


\procdef{d-caddr}


\startprocsyntax
\begin{codeblock}
  (d-caddr \procarg{x})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{<object>}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\cbuiltin{<object>}}


\procpurity{pure}


Expression \code{(d-caddr x)} is equivalent to \code{(d-car (d-cdr (d-cdr x)))}.


\procdef{d-cdddr}


\startprocsyntax
\begin{codeblock}
  (d-cdddr \procarg{x})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{<object>}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\cbuiltin{<object>}}


\procpurity{pure}


Expression \code{(d-cdddr x)} is equivalent to \code{(d-cdr (d-cdr (d-cdr x)))}.


\procdef{d-cadddr}


\startprocsyntax
\begin{codeblock}
  (d-cadddr \procarg{x})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{<object>}}%
  {An object}
\end{arglist}


\procresult{A value}%
{\cbuiltin{<object>}}


\procpurity{pure}


Expression \code{(d-cadddr x)} is equivalent to
\code{(d-car (d-cdr (d-cdr (d-cdr x))))}.


\procdef{d-drop-right}


\startprocsyntax
\begin{codeblock}
  (d-drop-right \procarg{lst} \procarg{i-count})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{<object>}}{A list}
  \argument{i-count}{\code{<integer>}}{Count of elements to be dropped}
\end{arglist}


\procresult{A list with specified number of elements dropped away from %
the end}%
{\cbuiltin{<object>}}


\procpurity{pure}


\procdef{d-drop}


\startprocsyntax
\begin{codeblock}
  (d-drop \procarg{lst} \procarg{i-count})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{<object>}}{A list}
  \argument{i-count}{\code{<integer>}}{Count of elements to be dropped}
\end{arglist}


\procresult{A list with specified number of elements dropped away from %
the beginning}%
{\cbuiltin{<object>}}


\procpurity{pure}


\procdef{d-exists?}


\startprocsyntax
\begin{codeblock}
  (d-exists? pred lst-1 ... lst-n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure ((\builtin{rest} <object>)) %
      <boolean> pure)}}
    {A predicate}
  \argument{lst-k}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for any elementwise
  application to lists \code{lst-k}}
{\code{<boolean>}}


\procpurity{pure}


\procdef{d-exists-nonpure?}


\startprocsyntax
\begin{codeblock}
  (d-exists-nonpure? pred lst-1 ... lst-n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure ((\builtin{rest} <object>)) %
      <boolean> nonpure)}}
    {A predicate}
  \argument{lst-k}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for any elementwise
  application to lists \code{lst-k}}
{\code{<boolean>}}


\procpurity{nonpure}


\procdef{d-exists0?}


\startprocsyntax
\begin{codeblock}
  (d-exists0? pred lists)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure ((\builtin{rest} <object>)) %
      <boolean> pure)}}
    {A predicate}
  \argument{lists}{\code{<object>}}%
  {A list of lists}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for any elementwise
  application to the lists}
{\code{<boolean>}}


\procpurity{pure}


\procdef{d-exists-nonpure0?}


\startprocsyntax
\begin{codeblock}
  (d-exists-nonpure0? pred lists)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure ((\builtin{rest} <object>)) %
      <boolean> nonpure)}}
    {A predicate}
  \argument{lists}{\code{<object>}}%
  {A list of lists}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for any elementwise
  application to the lists}
{\code{<boolean>}}


\procpurity{nonpure}


\procdef{d-exists1?}


\startprocsyntax
\begin{codeblock}
  (d-exists1? pred lst)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure ((\builtin{rest} <object>)) %
      <boolean> pure)}}
    {A predicate}
  \argument{lst}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for any element of the list}%
{\code{<boolean>}}


\procpurity{pure}


\procdef{d-exists-nonpure1?}


\startprocsyntax
\begin{codeblock}
  (d-exists-nonpure1? pred lst)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure ((\builtin{rest} <object>)) %
      <boolean> nonpure)}}
    {A predicate}
  \argument{lst}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for any element of the list}%
{\code{<boolean>}}


\procpurity{nonpure}


\procdef{d-exists2?}


\startprocsyntax
\begin{codeblock}
  (d-exists2? pred lst1 lst2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure (<object> <object>) %
      <boolean> pure)}}
    {A predicate}
  \argument{lst1}{\code{<object>}}%
  {A list}
  \argument{lst2}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for any pairwise
  application to \code{lst-1} and \code{lst-2}}
{\code{<boolean>}}


\procpurity{pure}


\procdef{d-exists-nonpure2?}


\startprocsyntax
\begin{codeblock}
  (d-exists-nonpure2? pred lst1 lst2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure (<object> <object>) %
      <boolean> nonpure)}}
    {A predicate}
  \argument{lst1}{\code{<object>}}%
  {A list}
  \argument{lst2}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for any pairwise
  application to \code{lst-1} and \code{lst-2}}
{\code{<boolean>}}


\procpurity{nonpure}


\procdef{d-for-all?}


\startprocsyntax
\begin{codeblock}
  (d-for-all? pred lst-1 ... lst-n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure ((\builtin{rest} <object>)) %
      <boolean> pure)}}
    {A predicate}
  \argument{lst-k}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for all the elementwise
  applications to lists \code{lst-k}}
{\code{<boolean>}}


\procpurity{pure}


\procdef{d-for-all-nonpure?}


\startprocsyntax
\begin{codeblock}
  (d-for-all-nonpure? pred lst-1 ... lst-n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure ((\builtin{rest} <object>)) %
      <boolean> nonpure)}}
    {A predicate}
  \argument{lst-k}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for all the elementwise
  applications to lists \code{lst-k}}
{\code{<boolean>}}


\procpurity{nonpure}


\procdef{d-for-all0?}


\startprocsyntax
\begin{codeblock}
  (d-for-all0? pred lists)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure ((\builtin{rest} <object>)) %
      <boolean> pure)}}
    {A predicate}
  \argument{lists}{\code{<object>}}%
  {A list of lists}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for all the elementwise
  applications to the lists}
{\code{<boolean>}}


\procpurity{pure}


\procdef{d-for-all-nonpure0?}


\startprocsyntax
\begin{codeblock}
  (d-for-all-nonpure0? pred lists)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure ((\builtin{rest} <object>)) %
      <boolean> nonpure)}}
    {A predicate}
  \argument{lists}{\code{<object>}}%
  {A list of lists}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for all the elementwise
  applications to the lists}
{\code{<boolean>}}


\procpurity{nonpure}


\procdef{d-for-all1?}


\startprocsyntax
\begin{codeblock}
  (d-for-all1? pred lst)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure ((\builtin{rest} <object>)) %
      <boolean> pure)}}
    {A predicate}
  \argument{lst}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for all elements of the list}%
{\code{<boolean>}}


\procpurity{pure}


\procdef{d-for-all-nonpure1?}


\startprocsyntax
\begin{codeblock}
  (d-for-all-nonpure1? pred lst)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure ((\builtin{rest} <object>)) %
      <boolean> nonpure)}}
    {A predicate}
  \argument{lst}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for all elements of the list}%
{\code{<boolean>}}


\procpurity{nonpure}


\procdef{d-for-all2?}


\startprocsyntax
\begin{codeblock}
  (d-for-all2? pred lst1 lst2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure (<object> <object>) %
      <boolean> pure)}}
    {A predicate}
  \argument{lst1}{\code{<object>}}%
  {A list}
  \argument{lst2}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for all the pairwise
  applications to \code{lst-1} and \code{lst-2}}
{\code{<boolean>}}


\procpurity{pure}


\procdef{d-for-all-nonpure2?}


\startprocsyntax
\begin{codeblock}
  (d-for-all-nonpure2? pred lst1 lst2)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:procedure (<object> <object>) %
      <boolean> nonpure)}}
    {A predicate}
  \argument{lst1}{\code{<object>}}%
  {A list}
  \argument{lst2}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{\true\ iff the predicate returns \true\ for all the pairwise
  applications to \code{lst-1} and \code{lst-2}}
{\code{<boolean>}}


\procpurity{nonpure}


\procdef{d-for-each}


\startprocsyntax
\begin{codeblock}
  (d-for-each proc lst-1 ... lst-n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<object>) <none> nonpure)}}%
  {A procedure to be applied into the given lists}
  \argument{lst-k}{\code{<object>}}%
  {A list}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure is similar to \code{for-each}, see section
\ref{sec:for-each}.
The given procedure is applied to the given lists and the results are
discarded.


\procdef{d-for-each0}


\startprocsyntax
\begin{codeblock}
  (d-for-each0 proc lists)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<object>) <none> nonpure)}}%
  {A procedure to be applied into the given lists}
  \argument{lists}{\code{<object>}}%
  {A list of lists}
\end{arglist}


\noprocresult


\procpurity{nonpure}


The given procedure is applied to the given lists and the results are
discarded.


\procdef{d-for-each1}


\startprocsyntax
\begin{codeblock}
  (d-for-each1 proc lst)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<object>) <none> nonpure)}}%
  {A procedure to be applied into the given list}
  \argument{lst}{\code{<object>}}%
  {A list}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure applies the given procedure to the given list and
discards the results.


\procdef{d-length}


\startprocsyntax
\begin{codeblock}
  (d-length lst)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{Number of elements in the list}%
{\cbuiltin{<integer>}}


\procpurity{pure}


\procdef{d-list}


\startprocsyntax
\begin{codeblock}
  (d-list obj-1 ... obj-n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj-k}{\code{<object>}}%
  {An object}
\end{arglist}


\procresult{A list constructed from the arguments}%
{\cbuiltin{<object>}}


\procpurity{pure}


\procdef{d-list-ref}


\startprocsyntax
\begin{codeblock}
  (d-list-ref lst index)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{<object>}}%
  {A list}
  \argument{index}{\code{<integer>}}%
  {Index to the list}
\end{arglist}


\procresult{The object at the specified position in the given list}%
{\cbuiltin{<object>}}


\procpurity{pure}


\procdef{d-map-car}
\label{sec:d-map-car}


\startprocsyntax
\begin{codeblock}
  (d-map-car \procarg{lst})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{<object>}}
  {Lists to take arguments from}
\end{arglist}


\procresult{A list constructed by taking the first element of each
  component list of \procarg{lst}}
{\code{<list>}}


\procpurity{pure}


\procdef{d-map-cdr}
\label{sec:d-map-cdr}


\startprocsyntax
\begin{codeblock}
  (d-map-cdr \procarg{lst})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{<object>}}
  {Lists to take arguments from}
\end{arglist}


\procresult{A list constructed by taking the tail of each
  component list of \procarg{lst}}
{\code{<list>}}


\procpurity{pure}


\procdef{d-reverse}


\startprocsyntax
\begin{codeblock}
  (d-reverse \procarg{lst})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{<object>}}{A list}
\end{arglist}


\procresult{A list consisting of the elements of \code{lst} in reverse order}%
{\cbuiltin{<object>}}


\procpurity{pure}


\procdef{d-take-right}


\startprocsyntax
\begin{codeblock}
  (d-take-right \procarg{lst} \procarg{i-count})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{<object>}}{A list}
  \argument{i-count}{\code{<integer>}}{Count of elements to be taken}
\end{arglist}


\procresult{A list consisting of the specified number of elements from the %
end of the argument list}%
{\cbuiltin{<object>}}


\procpurity{pure}


\procdef{d-take}


\startprocsyntax
\begin{codeblock}
  (d-take \procarg{lst} \procarg{i-count})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{lst}{\code{<object>}}{A list}
  \argument{i-count}{\code{<integer>}}{Count of elements to be taken}
\end{arglist}


\procresult{A list consisting of the specified number of elements from the %
beginning of the argument list}%
{\cbuiltin{<object>}}


\procpurity{pure}


\procdef{list?}


\startprocsyntax
\begin{codeblock}
  (list? \procarg{x})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\code{<object>}}%
  {An object}
\end{arglist}


\procresult{Returns \true\ iff \code{x} is a list.}%
{\cbuiltin{<boolean>}}


\section{Parametrized Methods}


\procdef{d-map}


\typeparams{\typeparam{type}}


\startprocsyntax
\begin{codeblock}
  (d-map proc lst-1 ... lst-n)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure ((\builtin{rest} <object>)) %
      \typeparam{type} pure)}}
    {A procedure to be applied into the given list}
  \argument{lst-k}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{A list constructed by applying the procedure to the
  elements of the lists}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


This procedure is similar to \code{map}, see section \ref{sec:map}.


\procdef{d-map0}


\typeparams{\typeparam{type}}


\startprocsyntax
\begin{codeblock}
  (d-map0 proc lists)
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure ((\builtin{rest} <object>)) %
      \typeparam{type} pure)}}
    {A procedure to be applied into the given list}
  \argument{lists}{\code{<object>}}%
  {A list of lists}
\end{arglist}


\procresult{A list constructed by applying the procedure to the
  elements of the lists}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


\procdef{d-map1}


\startprocsyntax
\begin{codeblock}
  (d-map1 proc lst)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<object>) \typeparam{type} pure)}}%
  {A procedure to be applied into the given list}
  \argument{lst}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{A list constructed by applying the procedure to each
  element of the list}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


\procdef{d-map2}


\startprocsyntax
\begin{codeblock}
  (d-map2 proc lst1 lst2)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<object> <object>) \typeparam{type} pure)}}%
  {A procedure to be applied into the given lists}
  \argument{lst1}{\code{<object>}}%
  {A list}
  \argument{lst2}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{A list constructed by applying the procedure pairwise to each
  element of the lists}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{pure}


\procdef{d-map-nonpure}


\startprocsyntax
\begin{codeblock}
  (d-map-nonpure proc lst-1 ... lst-n)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure ((\builtin{rest} <object>)) %
      \typeparam{type} nonpure)}}
           {A procedure to be applied into the given lists}
  \argument{lst}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{A list constructed by applying the procedure to the
  elements of the lists}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{nonpure}


This procedure is similar to \code{map-nonpure}, see section
\ref{sec:map-nonpure}.


\procdef{d-map-nonpure0}


\startprocsyntax
\begin{codeblock}
  (d-map-nonpure0 proc lists)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure ((\builtin{rest} <object>)) %
      \typeparam{type} nonpure)}}
           {A procedure to be applied into the given lists}
  \argument{lists}{\code{<object>}}%
  {A list of lists}
\end{arglist}


\procresult{A list constructed by applying the procedure to the
  elements of the lists}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{nonpure}


\procdef{d-map-nonpure1}


\startprocsyntax
\begin{codeblock}
  (d-map-nonpure1 proc lst)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<object>) \typeparam{type} nonpure)}}%
  {A procedure to be applied into the given list}
  \argument{lst}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{A list constructed by applying the procedure to each
  element of the list}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{nonpure}


\procdef{d-map-nonpure2}


\startprocsyntax
\begin{codeblock}
  (d-map-nonpure2 proc lst1 lst2)
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<object> <object>) \typeparam{type} nonpure)}}%
  {A procedure to be applied into the given lists}
  \argument{lst1}{\code{<object>}}%
  {A list}
  \argument{lst2}{\code{<object>}}%
  {A list}
\end{arglist}


\procresult{A list constructed by applying the procedure pairwise to each
  element of the lists}%
{\code{(:uniform-list \typeparam{type})}}


\procpurity{nonpure}


\procdef{d-fold1}
\label{sec:d-fold1}


\startprocsyntax
\begin{codeblock}
  (d-fold1 \procarg{proc} \procarg{x-init} \procarg{l})
\end{codeblock}


\typeparams{\typeparam{result}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
  (<object> \typeparam{result}) %
  \typeparam{result} pure)}}
  {A procedure to apply}
  \argument{x-init}{\code{\typeparam{result}}}
  {Initial value for folding}
  \argument{l}{\code{<object>}}
  {A list to fold}
\end{arglist}


\procresult{A list constructed by folding the argument list with the argument %
procedure}
{\code{\typeparam{result}}}


\procpurity{pure}


Each \code{proc} call is \code{(proc elem previous)} where elem is from \code{l}
and \code{previous} is the return value from the previous call to \code{proc},
or the given \code{x-init} for the first call. Procedure \code{d-fold1} works
through the list elements from first to last.


\procdef{d-fold-right1}
\label{sec:d-fold-right1}


\startprocsyntax
\begin{codeblock}
  (d-fold-right1 \procarg{proc} \procarg{x-init} \procarg{l})
\end{codeblock}


\typeparams{\typeparam{result}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(\cbuiltin{:procedure} %
  (<object> \typeparam{result}) %
  \typeparam{result} pure)}}
  {A procedure to apply}
  \argument{x-init}{\code{\typeparam{result}}}
  {Initial value for folding}
  \argument{l}{\code{<object>}}
  {A list to fold}
\end{arglist}


\procresult{A list constructed by folding the argument list with the argument %
procedure}
{\code{\typeparam{result}}}


\procpurity{pure}


Each \code{proc} call is \code{(proc elem previous)} where elem is from \code{l}
and \code{previous} is the return value from the previous call to \code{proc},
or the given \code{x-init} for the first call. Procedure \code{d-fold-right1} works
through the list elements from last to first.


\chapter{Module \code{(standard-library mutable-pair)}}


\section{Data Types}


\begin{datatype}
  \datatypename{:mpair}
  \datatypetype{\builtin{<param-class>}}
  \datatypenrparams{2}
  \datatypedesc{A mutable pair}
\end{datatype}


\begin{datatype}
  \datatypename{:mutable-alist}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{2}
  \datatypedesc{An association list consisting of mutable pairs}
\end{datatype}


\begin{datatype}
  \datatypename{:nonempty-mutable-alist}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{2}
  \datatypedesc{A nonempty association list consisting of mutable pairs}
\end{datatype}


\section{Parametrized Methods}


\procdef{mcons}


\startprocsyntax
\begin{codeblock}
  (mcons x1 x2)
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{x1}{\code{\typeparam{type1}}}{An object}
  \argument{x2}{\code{\typeparam{type2}}}{An object}
\end{arglist}


\procresult{A mutable pair consisting of the arguments}%
{\code{(:mpair \typeparam{type1} \typeparam{type2})}}


\procpurity{pure}


\procdef{mcar}


\startprocsyntax
\begin{codeblock}
  (mcar p)
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{p}{\code{(:mpair \typeparam{type1} \typeparam{type2})}}%
  {A mutable pair}
\end{arglist}


\procresult{The head of the argument}%
{\code{\typeparam{type1}}}


\procpurity{pure}


\procdef{mcdr}


\startprocsyntax
\begin{codeblock}
  (mcdr p)
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{p}{\code{(:mpair \typeparam{type1} \typeparam{type2})}}%
  {A mutable pair}
\end{arglist}


\procresult{The tail of the argument}%
{\code{\typeparam{type2}}}


\procpurity{pure}


\procdefexcl{m-set-car!}{m-set-car{"!}}


\startprocsyntax
\begin{codeblock}
  (m-set-car! p x)
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{p}{\code{(:mpair \typeparam{type1} \typeparam{type2})}}{A mutable pair}
  \argument{x}{\code{\typeparam{type1}}}{An object}
\end{arglist}


\noprocresult


\procpurity{nonpure}


Set the head of the mutable pair \code{p} to value \code{x}.


\procdefexcl{m-set-cdr!}{m-set-cdr{"!}}


\startprocsyntax
\begin{codeblock}
  (m-set-cdr! p x)
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{p}{\code{(:mpair \typeparam{type1} \typeparam{type2})}}{A mutable pair}
  \argument{x}{\code{\typeparam{type2}}}{An object}
\end{arglist}


\noprocresult


\procpurity{nonpure}


Set the tail of the mutable pair \code{p} to value \code{x}.


\procdef{m-assoc}


\startprocsyntax
\begin{codeblock}
  (m-assoc key alist default)
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}, \typeparam{default}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{key}}}{The key to be searched}
  \argument{alist}{\code{(:mutable-alist \typeparam{key} \typeparam{value})}}{A mutable association list}
  \argument{default}{\code{\typeparam{default}}}{The default value}
\end{arglist}


\procresult{The association corresponding to \code{key}}%
{\code{(:union (:mpair \typeparam{key} \typeparam{value}) \typeparam{default})}}


\procpurity{pure}


If no association is found \code{default} is returned.


\procdef{mpair->string}


\startprocsyntax
\begin{codeblock}
  (mpair->string p)
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{p}{\code{(:mpair \typeparam{type1} \typeparam{type2})}}%
  {A mutable pair}
\end{arglist}


\procresult{The mutable pair converted to a string}%
{\code{<string>}}


\procpurity{pure}


\section{Parametrized Virtual Methods}


\indexmethod{object->string}

\noindent
\puremethoddefwithvalue{object->string}{(:mpair \typeparam{type1} \typeparam{type2})}{<string>}{mpair->string}


\chapter{Module \code{(standard-library singleton)}}


\section{Data Types}


\begin{datatype}
  \datatypename{:singleton}
  \datatypetype{\builtin{<param-logical-type>}}
  \datatypenrparams{1}
  \datatypedesc{A singleton object}
\end{datatype}


A singleton is an object containing a single value.


\section{Parametrized Methods}


\procdef{make-singleton}


\startprocsyntax
\begin{codeblock}
  (make-singleton \procarg{element})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{element}{\code{\typeparam{type}}} %
           {An object}
\end{arglist}


\procresult{A new singleton object containing the given value}%
{\code{(:singleton \typeparam{type})}}


\procpurity{pure}


\procdef{singleton-get-element}


\startprocsyntax
\begin{codeblock}
  (singleton-get-element \procarg{sgt})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{sgt}{\code{(:singleton \typeparam{type})}} %
           {A singleton}
\end{arglist}


\procresult{The value contained in the argument object}%
{\code{\typeparam{type}}}


\procpurity{pure}


\procdefexcl{singleton-set-element!}{singleton-set-element{"!}}


\startprocsyntax
\begin{codeblock}
  (singleton-set-element! \procarg{sgt} \procarg{new-element})
\end{codeblock}


\typeparams{\typeparam{type}}


\startprocarguments
\begin{arglist}
  \argument{sgt}{\code{(:singleton \typeparam{type})}}{A singleton}
  \argument{new-element}{\code{\typeparam{type}}}{The new element value}
\end{arglist}


\noprocresult


\procpurity{nonpure}


The element of the singleton \procarg{sgt} is set to \procarg{new-element}.


\chapter{Module \code{(standard-library hash-table0)}}


This module is deprecated and works only for Guile target
platform. You should use module \code{(standard-library hash-table)}
instead.

When a hash table is used the hash procedure and the equality
predicate used by the association procedure must be compatible with
each other, i.e. the hash procedure shall never compute different hash
values for objects that are equal by the equality predicate.

When you create object, string, or symbol hash tables you have to
manually dispatch the value type. For example to create a string hash
table with symbols as the value type use code

\begin{codeblock}
  \noindent\hspace{0.5cm} ((param-proc-dispatch make-string-hash-table-with-size <symbol>) \\
  \mbox{ }\noindent\hspace{0.7cm} 100)
\end{codeblock}


\section{Data Types}


\begin{datatype}
  \datatypename{<raw-hash-table>}
  \datatypetype{\builtin{<class>}}
  \datatypedesc{The low-level guile hash table class. %
    This class should not be used directly.}
\end{datatype}


\begin{datatype}
  \datatypename{:hash-proc}
  \datatypetype{parametrized procedure class}
  \datatypenrparams{1}
  \datatypedesc{The type of a hash procedure. The type parameter is %
    the type of the values to be hashed.}
\end{datatype}


\begin{datatype}
  \datatypename{:assoc-proc}
  \datatypetype{parametrized procedure class}
  \datatypenrparams{2}
  \datatypedesc{The type of an association procedure for hash %
    tables. The first type parameter is the type of the key and the %
    second the type of the values with which the keys are associated.}
\end{datatype}


\begin{datatype}
  \datatypename{:hash-table}
  \datatypetype{\code{<param-class>}}
  \datatypenrparams{2}
  \datatypedesc{The parametrized class for hash tables. The first %
    parameter is the type of the keys and the second the type of the %
    values with which the keys are associated.}
\end{datatype}


\begin{datatype}
  \datatypename{:object-hash-table}
  \datatypetype{\code{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{The parametrized class for hash tables for which the %
    keys are arbitrary objects. The type parameter is the type of the %
    associated values.}
\end{datatype}


The hash procedure of an object hash table is compatible with the %
association procedure \code{assoc-objects1} with the following key
types:
\begin{itemize}
\item symbols
\item booleans
\item characters
\item strings
\item user defined nonprimitive classes
\item pairs
\item vectors (all four kinds of vectors)
\end{itemize}
Procedure \code{assoc-objects1} uses equivalence predicate
\code{equal-objects?}.  Note that if you use this class with string or
pair keys the keys are considered equal if they are the same object.


\begin{datatype}
  \datatypename{:string-hash-table}
  \datatypetype{\code{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{The parametrized class for hash tables for which the %
    keys are strings. The type parameter is the type of the %
    associated values.}
\end{datatype}


\begin{datatype}
  \datatypename{:symbol-hash-table}
  \datatypetype{\code{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{The parametrized class for hash tables for which the %
    keys are symbols. The type parameter is the type of the %
    associated values.}
\end{datatype}


\section{Simple Methods}


\procdef{object-hash}


\startprocsyntax
\begin{codeblock}
(object-hash \procarg{obj} \procarg{size})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<object>}}{The object for which the hash %
    value is computed}
  \argument{size}{\builtin{<integer>}}{The size of the hash table %
    for which the hash value is computed.}
\end{arglist}


\procresult{Hash value}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{string-hash}


\startprocsyntax
\begin{codeblock}
(string-hash \procarg{str} \procarg{size})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{The string for which the hash %
    value is computed}
  \argument{size}{\builtin{<integer>}}{The size of the hash table %
    for which the hash value is computed.}
\end{arglist}


\procresult{Hash value}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{hashq}


\startprocsyntax
\begin{codeblock}
(hashq \procarg{x} \procarg{size})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\builtin{<object>}}{The object for which the hash %
    value is computed}
  \argument{size}{\builtin{<integer>}}{The size of the hash table %
    for which the hash value is computed.}
\end{arglist}


\procresult{Hash value}%
{\builtin{<integer>}}


\procpurity{pure}


This procedure computes a hash value with Scheme procedure \code{hashq}.
This procedure is compatible with the Scheme predicate \code{eq?}. See
\cite[chapter 6.1]{shinn2017}.


\procdef{hashv}


\startprocsyntax
\begin{codeblock}
(hashv \procarg{x} \procarg{size})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\builtin{<object>}}{The object for which the hash %
    value is computed}
  \argument{size}{\builtin{<integer>}}{The size of the hash table %
    for which the hash value is computed.}
\end{arglist}


\procresult{Hash value}%
{\builtin{<integer>}}


\procpurity{pure}


This procedure computes a hash value with Scheme procedure \code{hashv}.
This procedure is compatible with the Scheme predicate \code{eqv?}. See
\cite[chapter 6.1]{shinn2017}.


\procdef{hash-contents}


\startprocsyntax
\begin{codeblock}
(hash-contents \procarg{x} \procarg{size})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\builtin{<object>}}{The object for which the hash %
    value is computed}
  \argument{size}{\builtin{<integer>}}{The size of the hash table %
    for which the hash value is computed.}
\end{arglist}


\procresult{Hash value}%
{\builtin{<integer>}}


\procpurity{pure}


This procedure computes a hash value with Scheme procedure \code{hash}.
This procedure is compatible with the Scheme predicate \code{equal?}
(not the similar Theme-D predicate). See \cite[chapter 6.1]{shinn2017}.


\section{Parametrized Methods}


\procdef{make-object-hash-table}


\startprocsyntax
\begin{codeblock}
  (make-object-hash-table \procarg{dummy})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{dummy}{\code{(:maybe \typeparam{value})}}{A dummy argument determining the value type}
\end{arglist}


\procresult{An object hash table}%
{\cbuiltin{(:object-hash-table \typeparam{value})}}


\procpurity{pure}


\procdef{make-object-hash-table-with-size}


\startprocsyntax
\begin{codeblock}
  (make-object-hash-table-with-size \procarg{dummy} \procarg{i-size})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{dummy}{\code{(:maybe \typeparam{value})}}%
           {A dummy argument determining the value type}
  \argument{i-size}{\builtin{<integer>}}{Size of the hash table}
\end{arglist}


\procresult{An object hash table with given size}%
{\cbuiltin{(:object-hash-table \typeparam{value})}}


\procpurity{pure}


\procdef{make-string-hash-table}


\startprocsyntax
\begin{codeblock}
  (make-string-hash-table \procarg{dummy})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{dummy}{\code{(:maybe \typeparam{value})}}%
           {A dummy argument determining the value type}
\end{arglist}


\procresult{A string hash table}%
{\cbuiltin{(:string-hash-table \typeparam{value})}}


\procpurity{pure}


\procdef{make-string-hash-table-with-size}


\startprocsyntax
\begin{codeblock}
  (make-string-hash-table-with-size \procarg{dummy} \procarg{i-size})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{dummy}{\code{(:maybe \typeparam{value})}}%
           {A dummy argument determining the value type}
  \argument{i-size}{\builtin{<integer>}}{Size of the hash table}
\end{arglist}


\procresult{A string hash table with given size}%
{\cbuiltin{(:string-hash-table \typeparam{value})}}


\procpurity{pure}


\procdef{make-symbol-hash-table}


\startprocsyntax
\begin{codeblock}
  (make-symbol-hash-table \procarg{dummy})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{dummy}{\code{(:maybe \typeparam{value})}}%
           {A dummy argument determining the value type}
\end{arglist}


\procresult{A symbol hash table}%
{\cbuiltin{(:symbol-hash-table \typeparam{value})}}


\procpurity{pure}


\procdef{make-symbol-hash-table-with-size}


\startprocsyntax
\begin{codeblock}
  (make-symbol-hash-table-with-size \procarg{dummy} \procarg{i-size})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{dummy}{\code{(:maybe \typeparam{value})}}%
           {A dummy argument determining the value type}
  \argument{i-size}{\builtin{<integer>}}{Size of the hash table}
\end{arglist}


\procresult{A symbol hash table with given size}%
{\cbuiltin{(:symbol-hash-table \typeparam{value})}}


\procpurity{pure}


\procdefexcl{hash-clear!}{hash-clear{"!}}


\startprocsyntax
\begin{codeblock}
  (hash-clear! \procarg{hashtable})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure removes all the element from the argument hash table.


\procdef{hash-count-elements}


\startprocsyntax
\begin{codeblock}
  (hash-count-elements \procarg{hashtable})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
\end{arglist}


\procresult{The number of elements in the hash table}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{hash-exists?}


\startprocsyntax
\begin{codeblock}
  (hash-exists? \procarg{hashtable} \procarg{key})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
  \argument{key}{\code{\typeparam{key}}}{Key to be searched}
\end{arglist}


\procresult{Returns \true\ iff the given key is found from the %
  hash table}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{hash-for-each}


\startprocsyntax
\begin{codeblock}
  (hash-for-each \procarg{proc} \procarg{hashtable})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{key} %
      \typeparam{value}) <none> nonpure)}}%
  {The procedure to be called}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure calls the given procedure for all elements in the hash
table.


\procdef{hash-ref}


\startprocsyntax
\begin{codeblock}
  (hash-ref \procarg{hashtable} \procarg{key} \procarg{default})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}, \typeparam{default}}


\startprocarguments
\begin{arglist}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
  \argument{key}{\code{\typeparam{key}}}{Key to be searched}
  \argument{default}{\code{\typeparam{default}}}{The default value}
\end{arglist}


\procresult{The value associated with the given key in the hash %
  table. Returns \procarg{default} if the key is not found.}%
{\code{(:union \typeparam{value} \typeparam{default})}}


\procpurity{pure}


\procdefexcl{hash-remove!}{hash-remove{"!}}


\startprocsyntax
\begin{codeblock}
  (hash-remove! \procarg{hashtable} \procarg{key})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
  \argument{key}{\code{\typeparam{key}}}{Key to be defined}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure removes the given key from the hash table. If the key
is not found the procedure does nothing.


\procdefexcl{hash-set!}{hash-set{"!}}


\startprocsyntax
\begin{codeblock}
  (hash-set! \procarg{hashtable} \procarg{key} \procarg{value})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
  \argument{key}{\code{\typeparam{key}}}{Key to be defined}
  \argument{value}{\code{\typeparam{value}}}{Value to be associated}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure associates the given key with the given value in the
hash table.


\procdef{make-hash-table}


\startprocsyntax
\begin{codeblock}
  (make-hash-table \procarg{proc-hash} \procarg{proc-assoc})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{proc-hash}{\code{(:hash-proc \typeparam{key})}}%
  {A procedure to compute hash values}
  \argument{proc-assoc}{\code{(:assoc-proc \typeparam{key} %
      \typeparam{value})}}%
  {A procedure to associate keys and values}
\end{arglist}


\procresult{A hash table}%
{\cbuiltin{(:hash-table \typeparam{key} \typeparam{value})}}


\procpurity{pure}


\procdef{make-hash-table-with-size}


\startprocsyntax
\begin{codeblock}
  (make-hash-table-with-size \procarg{proc-hash} \procarg{proc-assoc}
  \procarg{i-size})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{proc-hash}{\code{(:hash-proc \typeparam{key})}}%
  {A procedure to compute hash values}
  \argument{proc-assoc}{\code{(:assoc-proc \typeparam{key} %
      \typeparam{value})}}%
  {A procedure to associate keys and values}
  \argument{i-size}{\builtin{<integer>}}{Size of the hash table}
\end{arglist}


\procresult{A hash table with given size}%
{\cbuiltin{(:hash-table \typeparam{key} \typeparam{value})}}


\procpurity{pure}


\procdef{assoc1}


\startprocsyntax
\begin{codeblock}
  (assoc1 \procarg{key} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}{The key to be searched}
  \argument{lst}{\code{(:alist \typeparam{key} \typeparam{value})}}%
  {The association list from which the object is searched}
\end{arglist}


\procresult{The association or \false\ if none is found.}%
{\cbuiltin{(:union (:pair \typeparam{type2} \typeparam{type2}) <boolean>)}}


\procpurity{pure}


This procedure uses the equivalence predicate \code{equal?}.


\procdef{assoc-values1}


\startprocsyntax
\begin{codeblock}
  (assoc-values1 \procarg{key} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}{The key to be searched}
  \argument{lst}{\code{(:alist \typeparam{key} \typeparam{value})}}%
  {The association list from which the object is searched}
\end{arglist}


\procresult{The association or \false\ if none is found.}%
{\cbuiltin{(:union (:pair \typeparam{type2} \typeparam{type2}) <boolean>)}}


\procpurity{pure}


This procedure uses the equivalence predicate \code{equal-values?}.


\procdef{assoc-objects1}


\startprocsyntax
\begin{codeblock}
  (assoc-objects1 \procarg{key} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}{The key to be searched}
  \argument{lst}{\code{(:alist \typeparam{key} \typeparam{value})}}%
  {The association list from which the object is searched}
\end{arglist}


\procresult{The association or \false\ if none is found.}%
{\cbuiltin{(:union (:pair \typeparam{type2} \typeparam{type2}) <boolean>)}}


\procpurity{pure}


This procedure uses the equivalence predicate \code{equal-objects?}.


\procdef{assoc-contents1}


\startprocsyntax
\begin{codeblock}
  (assoc-contents1 \procarg{key} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}{The key to be searched}
  \argument{lst}{\code{(:alist \typeparam{key} \typeparam{value})}}%
  {The association list from which the object is searched}
\end{arglist}


\procresult{The association or \false\ if none is found.}%
{\cbuiltin{(:union (:pair \typeparam{type2} \typeparam{type2}) <boolean>)}}


\procpurity{pure}


This procedure uses the equivalence predicate \code{equal-contents?}.


\chapter{Modules \code{(standard-library hash-table)} and
  \code{(standard-library hash-table-opt)}}


\section{Data Types}


For module \code{hash-table-opt} the following three types are simple
procedure classes.


\begin{datatype}
  \datatypename{:hash-proc}
  \datatypetype{parametrized procedure class}
  \datatypenrparams{1}
  \datatypedesc{The type of a hash procedure. The type parameter is %
    the type of the values to be hashed.}
\end{datatype}


\begin{datatype}
  \datatypename{:assoc-proc}
  \datatypetype{parametrized procedure class}
  \datatypenrparams{2}
  \datatypedesc{The type of an association procedure for hash %
    tables. The first type parameter is the type of the key and the %
    second the type of the values with which the keys are associated.}
\end{datatype}


\begin{datatype}
  \datatypename{:alist-delete-proc}
  \datatypetype{parametrized procedure class}
  \datatypenrparams{2}
  \datatypedesc{The type of a procedure used to delete objects from an %
    association list. %
    The first type parameter is the type of the key and the %
    second the type of the values with which the keys are associated.}
\end{datatype}


\begin{datatype}
  \datatypename{:hash-table}
  \datatypetype{\code{<param-class>}}
  \datatypenrparams{2}
  \datatypedesc{The parametrized class for hash tables. The first %
    parameter is the type of the keys and the second the type of the %
    values with which the keys are associated.}
\end{datatype}


\begin{datatype}
  \datatypename{:object-hash-table}
  \datatypetype{\code{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{The parametrized class for hash tables for which the %
    keys are arbitrary objects. The type parameter is the type of the %
    associated values.}
\end{datatype}


The hash procedure of an object hash table is compatible with the %
association procedure \code{assoc-objects1} with the following key
types:
\begin{itemize}
\item symbols
\item booleans
\item characters
\item strings
\item user defined nonprimitive classes
\item pairs
\item vectors (all four kinds of vectors)
\end{itemize}
Procedure \code{assoc-objects1} uses equivalence predicate
\code{equal-objects?}.  Note that if you use this class with string or
pair keys the keys are considered equal if they are the same object.


\begin{datatype}
  \datatypename{:string-hash-table}
  \datatypetype{\code{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{The parametrized class for hash tables for which the %
    keys are strings. The type parameter is the type of the %
    associated values.}
\end{datatype}


\begin{datatype}
  \datatypename{:symbol-hash-table}
  \datatypetype{\code{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{The parametrized class for hash tables for which the %
    keys are symbols. The type parameter is the type of the %
    associated values.}
\end{datatype}


\section{Simple Methods}


\procdef{object-hash}


\startprocsyntax
\begin{codeblock}
(object-hash \procarg{obj} \procarg{size})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{obj}{\builtin{<object>}}{The object for which the hash %
    value is computed}
  \argument{size}{\builtin{<integer>}}{The size of the hash table %
    for which the hash value is computed.}
\end{arglist}


\procresult{Hash value}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{string-hash}


\startprocsyntax
\begin{codeblock}
(string-hash \procarg{str} \procarg{size})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{str}{\builtin{<string>}}{The string for which the hash %
    value is computed}
  \argument{size}{\builtin{<integer>}}{The size of the hash table %
    for which the hash value is computed.}
\end{arglist}


\procresult{Hash value}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{hashq}


\startprocsyntax
\begin{codeblock}
(hashq \procarg{x} \procarg{size})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\builtin{<object>}}{The object for which the hash %
    value is computed}
  \argument{size}{\builtin{<integer>}}{The size of the hash table %
    for which the hash value is computed.}
\end{arglist}


\procresult{Hash value}%
{\builtin{<integer>}}


\procpurity{pure}


This procedure computes a hash value with Scheme procedure \code{hashq}.
This procedure is compatible with the Scheme predicate \code{eq?}. See
\cite[chapter 6.1]{shinn2017}.


\procdef{hashv}


\startprocsyntax
\begin{codeblock}
(hashv \procarg{x} \procarg{size})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\builtin{<object>}}{The object for which the hash %
    value is computed}
  \argument{size}{\builtin{<integer>}}{The size of the hash table %
    for which the hash value is computed.}
\end{arglist}


\procresult{Hash value}%
{\builtin{<integer>}}


\procpurity{pure}


This procedure computes a hash value with Scheme procedure \code{hashv}.
This procedure is compatible with the Scheme predicate \code{eqv?}. See
\cite[chapter 6.1]{shinn2017}.


\procdef{hash-contents}


\startprocsyntax
\begin{codeblock}
(hash-contents \procarg{x} \procarg{size})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{x}{\builtin{<object>}}{The object for which the hash %
    value is computed}
  \argument{size}{\builtin{<integer>}}{The size of the hash table %
    for which the hash value is computed.}
\end{arglist}


\procresult{Hash value}%
{\builtin{<integer>}}


\section{Parametrized Methods}


\procdef{make-hash-table}


\startprocsyntax
\begin{codeblock}
  (make-hash-table \procarg{proc-hash} \procarg{proc-assoc}
  \procarg{proc-delete})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{proc-hash}{\code{(:hash-proc \typeparam{key})}}%
  {A procedure to compute hash values}
  \argument{proc-assoc}{\code{(:assoc-proc \typeparam{key} %
      \typeparam{value})}}%
  {A procedure to associate keys and values}
  \argument{proc-delete}{\code{(:alist-delete-proc \typeparam{key} %
      \typeparam{value})}}%
  {A procedure to delete an element from an association list}
\end{arglist}


\procresult{A hash table}%
{\cbuiltin{(:hash-table \typeparam{key} \typeparam{value})}}


\procpurity{pure}


\procdef{make-hash-table-with-size}


\startprocsyntax
\begin{codeblock}
  (make-hash-table \procarg{proc-hash} \procarg{proc-assoc}
  \procarg{proc-delete} \procarg{i-size})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{proc-hash}{\code{(:hash-proc \typeparam{key})}}%
  {A procedure to compute hash values}
  \argument{proc-assoc}{\code{(:assoc-proc \typeparam{key} %
      \typeparam{value})}}%
  {A procedure to associate keys and values}
  \argument{proc-delete}{\code{(:alist-delete-proc \typeparam{key} %
      \typeparam{value})}}%
           {A procedure to delete an element from an association list}
  \argument{i-size}{\builtin{<integer>}}{The size of the hash table}
\end{arglist}


\procresult{A hash table with the given size}%
{\cbuiltin{(:hash-table \typeparam{key} \typeparam{value})}}


\procpurity{pure}


\procdef{make-object-hash-table}


\startprocsyntax
\begin{codeblock}
  (make-object-hash-table \procarg{dummy})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{dummy}{\code{(:maybe \typeparam{value})}}{A dummy argument determining the value type}
\end{arglist}


\procresult{An object hash table}%
{\cbuiltin{(:object-hash-table \typeparam{value})}}


\procpurity{pure}


\procdef{make-object-hash-table-with-size}


\startprocsyntax
\begin{codeblock}
  (make-object-hash-table-with-size \procarg{dummy} \procarg{i-size})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{dummy}{\code{(:maybe \typeparam{value})}}%
           {A dummy argument determining the value type}
  \argument{i-size}{\builtin{<integer>}}{Size of the hash table}
\end{arglist}


\procresult{An object hash table with given size}%
{\cbuiltin{(:object-hash-table \typeparam{value})}}


\procpurity{pure}


\procdef{make-string-hash-table}


\startprocsyntax
\begin{codeblock}
  (make-string-hash-table \procarg{dummy})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{dummy}{\code{(:maybe \typeparam{value})}}%
           {A dummy argument determining the value type}
\end{arglist}


\procresult{A string hash table}%
{\cbuiltin{(:string-hash-table \typeparam{value})}}


\procpurity{pure}


\procdef{make-string-hash-table-with-size}


\startprocsyntax
\begin{codeblock}
  (make-string-hash-table-with-size \procarg{dummy} \procarg{i-size})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{dummy}{\code{(:maybe \typeparam{value})}}%
           {A dummy argument determining the value type}
  \argument{i-size}{\builtin{<integer>}}{Size of the hash table}
\end{arglist}


\procresult{A string hash table with given size}%
{\cbuiltin{(:string-hash-table \typeparam{value})}}


\procpurity{pure}


\procdef{make-symbol-hash-table}


\startprocsyntax
\begin{codeblock}
  (make-symbol-hash-table \procarg{dummy})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{dummy}{\code{(:maybe \typeparam{value})}}%
           {A dummy argument determining the value type}
\end{arglist}


\procresult{A symbol hash table}%
{\cbuiltin{(:symbol-hash-table \typeparam{value})}}


\procpurity{pure}


\procdef{make-symbol-hash-table-with-size}


\startprocsyntax
\begin{codeblock}
  (make-symbol-hash-table-with-size \procarg{dummy} \procarg{i-size})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{dummy}{\code{(:maybe \typeparam{value})}}%
           {A dummy argument determining the value type}
  \argument{i-size}{\builtin{<integer>}}{Size of the hash table}
\end{arglist}


\procresult{A symbol hash table with given size}%
{\cbuiltin{(:symbol-hash-table \typeparam{value})}}


\procpurity{pure}


\procdefexcl{hash-clear!}{hash-clear{"!}}


\startprocsyntax
\begin{codeblock}
  (hash-clear! \procarg{hashtable})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure removes all the element from the argument hash table.


\procdef{hash-exists?}


\startprocsyntax
\begin{codeblock}
  (hash-exists? \procarg{hashtable} \procarg{key})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
  \argument{key}{\code{\typeparam{key}}}{Key to be searched}
\end{arglist}


\procresult{Returns \true\ iff the given key is found from the %
  hash table}%
{\builtin{<boolean>}}


\procpurity{pure}


\procdef{hash-for-each}


\startprocsyntax
\begin{codeblock}
  (hash-for-each \procarg{proc} \procarg{hashtable})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{key} %
      \typeparam{value}) <none> nonpure)}}%
  {The procedure to be called}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure calls the given procedure for all elements in the hash
table.


\procdef{hash-map->list}


\startprocsyntax
\begin{codeblock}
  (hash-map->list \procarg{proc} \procarg{hashtable})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}, \typeparam{result}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{key} %
      \typeparam{value}) \typeparam{result} pure)}}%
  {The procedure to be called}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
\end{arglist}


\procresult{A list consisting of the applications of the procedure}%%
{\code{(:uniform-list \typeparam{result})}}


\procpurity{pure}


This procedure calls the given procedure for all elements in the hash
table and returns a list consisting of the results of the calls.


\procdef{hash-map->list-nonpure}


\startprocsyntax
\begin{codeblock}
  (hash-map->list-nonpure \procarg{proc} \procarg{hashtable})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}, \typeparam{result}}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (\typeparam{key} %
      \typeparam{value}) \typeparam{result} nonpure)}}%
  {The procedure to be called}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
\end{arglist}


\procresult{A list consisting of the applications of the procedure}%%
{\code{(:uniform-list \typeparam{result})}}


\procpurity{nonpure}


This procedure calls the given procedure for all elements in the hash
table and returns a list consisting of the results of the calls.


\procdef{hash-ref}


\startprocsyntax
\begin{codeblock}
  (hash-ref \procarg{hashtable} \procarg{key} \procarg{default})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}, \typeparam{default}}


\startprocarguments
\begin{arglist}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
  \argument{key}{\code{\typeparam{key}}}{Key to be searched}
  \argument{default}{\code{\typeparam{default}}}{The default value}
\end{arglist}


\procresult{The value associated with the given key in the hash %
  table. Returns \procarg{default} if the key is not found.}%
{\code{(:union \typeparam{value} \typeparam{default})}}


\procpurity{pure}


\procdefexcl{hash-remove!}{hash-remove{"!}}


\startprocsyntax
\begin{codeblock}
  (hash-remove! \procarg{hashtable} \procarg{key})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
  \argument{key}{\code{\typeparam{key}}}{Key to be defined}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure removes the given key from the hash table. If the key
is not found the procedure does nothing.


\procdefexcl{hash-set!}{hash-set{"!}}


\startprocsyntax
\begin{codeblock}
  (hash-set! \procarg{hashtable} \procarg{key} \procarg{value})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
  \argument{key}{\code{\typeparam{key}}}{Key to be defined}
  \argument{value}{\code{\typeparam{value}}}{Value to be associated}
\end{arglist}


\noprocresult


\procpurity{nonpure}


This procedure associates the given key with the given value in the
hash table.


\procdef{hash-count}


\startprocsyntax
\begin{codeblock}
  (hash-count \procarg{pred} \procarg{hashtable})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:binary-predicate \typeparam{key}
      \typeparam{value})}}%
    {A binary predicate}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
\end{arglist}


\procresult{The number of elements satisfying the predicate in the hash table}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{hash-count-elements}


\startprocsyntax
\begin{codeblock}
  (hash-count-elements \procarg{hashtable})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}}


\startprocarguments
\begin{arglist}
  \argument{hashtable}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
\end{arglist}


\procresult{The number of elements in the hash table}%
{\builtin{<integer>}}


\procpurity{pure}


\procdef{hash-search-first}


\startprocsyntax
\begin{codeblock}
  (hash-search-first \procarg{pred} \procarg{ht} \procarg{x-default})
\end{codeblock}


\typeparams{\typeparam{key}, \typeparam{value}, \typeparam{default}}


\startprocarguments
\begin{arglist}
  \argument{pred}{\code{(:binary-predicate \typeparam{key}
      \typeparam{value})}}%
    {A binary predicate}
  \argument{ht}{\code{(:hash-table %
      \typeparam{key} \typeparam{value})}} %
           {A hash table}
  \argument{x-default}{\code{\typeparam{default}}}%
  {The default return value}
\end{arglist}


\procresult{The first element satisfying the predicate in the hash table}%
{\code{(:union \typeparam{value} \typeparam{default})}}


\procpurity{pure}


If no element satisfies the predicate value \procarg{x-default} is
returned.


\procdef{assoc1}


\startprocsyntax
\begin{codeblock}
  (assoc1 \procarg{key} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}{The key to be searched}
  \argument{lst}{\code{(:alist \typeparam{key} \typeparam{value})}}%
  {The association list from which the object is searched}
\end{arglist}


\procresult{The association or \false\ if none is found.}%
{\cbuiltin{(:union (:pair \typeparam{type2} \typeparam{type2}) <boolean>)}}


\procpurity{pure}


This procedure uses the equivalence predicate \code{equal?}.


\procdef{assoc-values1}


\startprocsyntax
\begin{codeblock}
  (assoc-values1 \procarg{key} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}{The key to be searched}
  \argument{lst}{\code{(:alist \typeparam{key} \typeparam{value})}}%
  {The association list from which the object is searched}
\end{arglist}


\procresult{The association or \false\ if none is found.}%
{\cbuiltin{(:union (:pair \typeparam{type2} \typeparam{type2}) <boolean>)}}


\procpurity{pure}


This procedure uses the equivalence predicate \code{equal-values?}.


\procdef{assoc-objects1}


\startprocsyntax
\begin{codeblock}
  (assoc-objects1 \procarg{key} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}{The key to be searched}
  \argument{lst}{\code{(:alist \typeparam{key} \typeparam{value})}}%
  {The association list from which the object is searched}
\end{arglist}


\procresult{The association or \false\ if none is found.}%
{\cbuiltin{(:union (:pair \typeparam{type2} \typeparam{type2}) <boolean>)}}


\procpurity{pure}


This procedure uses the equivalence predicate \code{equal-objects?}.


\procdef{assoc-contents1}


\startprocsyntax
\begin{codeblock}
  (assoc-contents1 \procarg{key} \procarg{lst})
\end{codeblock}


\typeparams{\typeparam{type1}, \typeparam{type2}}


\startprocarguments
\begin{arglist}
  \argument{key}{\code{\typeparam{type1}}}{The key to be searched}
  \argument{lst}{\code{(:alist \typeparam{key} \typeparam{value})}}%
  {The association list from which the object is searched}
\end{arglist}


\procresult{The association or \false\ if none is found.}%
{\cbuiltin{(:union (:pair \typeparam{type2} \typeparam{type2}) <boolean>)}}


\procpurity{pure}


This procedure uses the equivalence predicate \code{equal-contents?}.


\chapter{Module \code{(standard-library command-line-parser)}}


\section{Data Types}


\begin{datatype}
  \datatypename{<argument-descriptor>}
  \datatypetype{\builtin{<class>}}
  \datatypedesc{A descriptor for a command-line argument}
\end{datatype}


\begin{datatype}
  \datatypename{<argument-descriptor-list>}
  \datatypetype{\builtin{:union}}
  \datatypedesc{A list of argument descriptors}
\end{datatype}


\begin{datatype}
  \datatypename{<argument-handler>}
  \datatypetype{\builtin{:procedure}}
  \datatypedesc{A procedure to handle an argument}
\end{datatype}

\vspace{0.5cm}

\noindent
An object of type \code{<argument-descriptor>} has the following
fields:
\begin{itemize}
\item
  \code{x-name}: The name of the argument, either a character or a
  string.
\item
  \code{takes-argument?}:
  A boolean value, \true\ iff the option takes an argument.
\item
  \code{proc-handler}:
  A handler procedure for the option, type \code{<argument-handler>}.
\end{itemize}

A procedure of type \code{<argument-handler>} takes a single
\code{<string>} argument, which is the argument passed to the command
line option. If the option does not take any arguments the argument is
an empty string.

See example program \code{command-line-demo.thp} for the usage of this
module.


\section{Simple Methods}


\procdef{parse-command-line}

\startprocsyntax
\begin{codeblock}
  (parse-command-line l-command-line l-argdescs proc-handle-proper-args)
\end{codeblock}

\startprocarguments
\begin{arglist}
  \argument{l-command-line}{\code{(:uniform-list <string>)}}%
  {The command line arguments}
  \argument{l-arg-descs}{\code{<argument-descriptor-list>}}%
  {List of argument descriptors}
  \argument{proc-handle-proper-args}%
  {\code{(:procedure ((:uniform-list <string>)) <none> nonpure)}}%
  {A procedure to handle non-option arguments}
\end{arglist}

\noprocresult

\procpurity{nonpure}

This procedure parses the command line arguments using the given
argument descriptors and non-option argument handler.


\chapter{Module \code{(standard-library statprof)}}


This is a wrapper module for guile profiler \code{statprof}.
Note that all features of \code{statprof} are not supported.
A simple use of \code{statprof} would look like this:
\begin{codeblock}
  \cl{0.5cm}
  (statprof-reset 0 50000 \#f) \\
  \cl{0.5cm}
  (statprof-start) \\
  \cl{0.5cm}
  (do-something) \\
  \cl{0.5cm}
  (statprof-stop) \\
  \cl{0.5cm}
  (statprof-display)
\end{codeblock}
See guile documentation for further information.


\section{Simple Methods}


\procdef{statprof-start}


\startprocsyntax
\begin{codeblock}
  (statprof-start)
\end{codeblock}


\noprocarguments


\noprocresult


\procpurity{nonpure}


\noindent
Start profiling.


\procdef{statprof-stop}


\startprocsyntax
\begin{codeblock}
  (statprof-stop)
\end{codeblock}


\noprocarguments


\noprocresult


\procpurity{nonpure}


\noindent
Stop profiling.


\procdef{statprof-reset}


\startprocsyntax
\begin{codeblock}
  (statprof-reset \procarg{sample-seconds} \procarg{sample-microseconds}
  \procarg{count-calls?})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{sample-seconds}{\builtin{<integer>}}%
           {Seconds for the sampler interval}
  \argument{sample-microseconds}{\builtin{<integer>}}%
           {Microseconds for the sampler interval}
  \argument{count-calls?}{\builtin{<boolean>}}%
           {\true\ to count procedure calls}
\end{arglist}


\noprocresult


\procpurity{nonpure}


\noindent
Reset the profiler.


\procdef{statprof-display}


\startprocsyntax
\begin{codeblock}
  (statprof-display)
\end{codeblock}


\noprocarguments


\noprocresult


\procpurity{nonpure}


\noindent
Display a summary of the statistics collected.


\chapter{Module \code{(standard-library plugins)}}


Note that this module supports only dynamically loaded modules created by
linking \theme\ module bodies to plugins. See test plugin \code{test913} 
and test program \code{test914} for a simple example of plugin usage.


\section{Data Types}


\begin{datatype}
  \datatypename{<module>}
  \datatypetype{\builtin{<class>}}
  \datatypedesc{A dynamically loaded Guile module}
\end{datatype}


\section{Simple Methods}


\procdef{load-module}


\startprocsyntax
\begin{codeblock}
  (load-module \procarg{l-s-module})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{l-s-module}{\code{(:uniform-list <symbol>)}}%
  {The name of the module to be loaded}
\end{arglist}


\procresult{A module object or \false}%
{\code{(:alt-maybe <module>)}}


\procpurity{nonpure}


This method loads a Guile module and returns an object representing it. If the
module is not found return \false.


\procdef{load-plugin}


\startprocsyntax
\begin{codeblock}
  (load-plugin \procarg{l-s-plugin})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{l-s-plugin}{\code{(:uniform-list <symbol>)}}%
  {The name of the plugin to be loaded}
\end{arglist}


\procresult{A module object}%
{\code{<module>}}


\procpurity{nonpure}


This method loads a \theme\ plugin and returns an object representing it. If the
module is not found raise exception \code{plugin-not-found}. If the module is
not a proper \theme\ plugin file raise exception \code{not-a-plugin-file}.


\procdef{module-var-exists?}


\startprocsyntax
\begin{codeblock}
  (module-var-exists? \procarg{module} \procarg{s-var})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{module}{\code{<module>}}%
  {A dynamically loaded module}
  \argument{s-var}{\code{<symbol>}}%
  {The name of a variable}
\end{arglist}


\procresult{\true\ iff \code{module} defines variable \code{s-var}}%
{\code{<boolean>}}


\procpurity{pure}


\procdef{module-ref}


\startprocsyntax
\begin{codeblock}
  (module-ref \procarg{module} \procarg{s-var})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{module}{\code{<module>}}%
  {A dynamically loaded module}
  \argument{s-var}{\code{<symbol>}}%
  {The name of a variable}
\end{arglist}


\procresult{The value of the variable \code{s-var} in \code{module}}%
{\code{<object>}}


\procpurity{pure}


\procdef{dyn-call}


\startprocsyntax
\begin{codeblock}
  (dyn-call \procarg{proc} \indexedprocarg{x}{1} ... \indexedprocarg{x}{n})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{<object>}}%
  {A procedure defined in some plugin}
  \indexedargument{x}{k}{\code{<object>}}%
  {The value of an argument}
\end{arglist}


\procresult{The result of the procedure call}%
{\code{<object>}}


\procpurity{nonpure}


The procedure is evaluated using the given arguments and the obtained value is
returned. The procedure must return a valid \theme\ object.


\procdef{dyn-call-no-result}


\startprocsyntax
\begin{codeblock}
  (dyn-call-no-result \procarg{proc} \indexedprocarg{x}{1} ... \indexedprocarg{x}{n})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{<object>}}%
  {A procedure defined in some plugin}
  \indexedargument{x}{k}{\code{<object>}}%
  {The value of an argument}
\end{arglist}


\noprocresult


\procpurity{nonpure}


The procedure is evaluated using the given arguments. No value is returned.


\procdef{dyn-apply}


\startprocsyntax
\begin{codeblock}
  (dyn-apply \procarg{proc} \procarg{l-args})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{<object>}}%
  {A procedure defined in some plugin}
  \argument{l-args}{\code{(:uniform-list <object>)}}%
  {The argument values}
\end{arglist}


\procresult{The result of the procedure call}%
{\code{<object>}}


\procpurity{nonpure}


The procedure is evaluated using the given argument list and the obtained value is
returned. The procedure must return a valid \theme\ object.


\procdef{dyn-apply-no-result}


\startprocsyntax
\begin{codeblock}
  (dyn-apply-no-result \procarg{proc} \procarg{l-args})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{<object>}}%
  {A procedure defined in some plugin}
  \argument{l-args}{\code{(:uniform-list <object>)}}%
  {The argument values}
\end{arglist}


\noprocresult


\procpurity{nonpure}


The procedure is evaluated using the given argument list. No value is returned.


\procdef{get-exported-var-name}


\startprocsyntax
\begin{codeblock}
  (get-exported-var-name \procarg{s-source-name})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{s-source-name}{\code{<symbol>}}%
  {A name of a variable}
\end{arglist}


\procresult{The internal name of the variable}%
{\code{<symbol>}}


\procpurity{pure}


This method returns the internal plugin name corresponding to an ordinary
variable name (not a generic procedure).  The result name is computed by
adding prefix \code{\_x\_} into the source name.


\procdef{get-exported-ngp-name}


\startprocsyntax
\begin{codeblock}
  (get-exported-ngp-name \procarg{s-source-name})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{s-source-name}{\code{<symbol>}}%
  {A name of a normal generic procedure}
\end{arglist}


\procresult{The internal name of the variable}%
{\code{<symbol>}}


\procpurity{pure}


This method returns the internal plugin name corresponding to a name of a
normal generic procedure.  The result name is computed by
adding prefix \code{\_n\_} into the source name.


\procdef{get-exported-vgp-name}


\startprocsyntax
\begin{codeblock}
  (get-exported-vgp-name \procarg{s-source-name})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{s-source-name}{\code{<symbol>}}%
  {A name of a normal generic procedure}
\end{arglist}


\procresult{The internal name of the variable}%
{\code{<symbol>}}


\procpurity{pure}


This method returns the internal plugin name corresponding to a name of a
virtual generic procedure.  The result name is computed by
adding prefix \code{\_v\_} into the source name.


\procdef{plugin-exported-normal-vars}


\startprocsyntax
\begin{codeblock}
  (plugin-exported-normal-vars \procarg{plugin})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{plugin}{\code{<module>}}%
  {A plugin module}
\end{arglist}


\procresult{List of ordinary variables exported by the plugin}%
{\code{(:uniform-list <symbol>)}}


\procpurity{pure}


\procdef{plugin-exported-ngps}


\startprocsyntax
\begin{codeblock}
  (plugin-exported-ngps \procarg{plugin})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{plugin}{\code{<module>}}%
  {A plugin module}
\end{arglist}


\procresult{List of normal generic procedures exported by the plugin}%
{\code{(:uniform-list <symbol>)}}


\procpurity{pure}


\procdef{plugin-exported-vgps}


\startprocsyntax
\begin{codeblock}
  (plugin-exported-vgps \procarg{plugin})
\end{codeblock}


\startprocarguments
\begin{arglist}
  \argument{plugin}{\code{<module>}}%
  {A plugin module}
\end{arglist}


\procresult{List of virtual generic procedures exported by the plugin}%
{\code{(:uniform-list <symbol>)}}


\procpurity{pure}


\backmatter


\bibliographystyle{abbrv}

\bibliography{theme-d-language-manual}


\printindex


\end{document}
