
\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 (C) 2012-2019 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{core-forms} defines some basic control structures as
  macros.
\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{text-file-io} defines primitive classes for input and
  output ports and basic operations with them.
\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{dynamic-list} implements dynamically type checked
  lists.
\item
  Module \code{singleton} implements singletons.
\item
  Module \code{hash-table} implements hash tables.
\item
  Module \code{hash-table2} implements hash tables.
\item
  Module \code{statprof} provides an interface to the guile
  \code{statprof} profiler.
\end{itemize}

Modules \code{hash-table}, \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.  We write ``pure'' in
a procedure definition to indicate that the procedure is pure.


\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-forms_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}.


\procdef{call-with-current-continuation-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}.


\procdef{call-with-current-continuation-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{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{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}


\subsection{Simple Procedures}


\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{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{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{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=?}

\indexmethod{=}

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


\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{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}


See section \ref{sec:core-other}.


\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{: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-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{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{<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{: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{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}.


\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{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}


\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{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 keyword defines a GOOPS class with the default equivalence
predicates (Scheme \code{eqv?} for \code{equal?} and
\code{equal-contents?} and Scheme \code{eq?} for
\code{equal-objects?}) and no zero object.


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


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{define-param-method} \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{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}


The \keyword{define-param-method} defines a 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-static-param-method}


This form defines a static parametrized method. Its syntax is similar
to \keyword{define-param-method}.


\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}


\startmacrosyntax
\begin{syntaxblock}
  \slp \skeyword{define-simple-method} \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{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 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-static-simple-method}


This form defines a static simple method. Its syntax is similar to
\keyword{define-simple-method}.


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


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


\macrodef{make}


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


Keyword \keyword{make} 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{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 list-utilities)}}


\section{Simple Procedures}


\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 Procedures}


\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{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{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{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 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 Scheme \code{map}.
Note that you cannot use procedure with result type \builtin{<none>}
as the first argument of \code{map1}.


\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 or \code{map-nonpure} resemble \code{map} except
\code{proc} may be nonpure and the applications of \code{proc} are
guaranteed to be done 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-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 Scheme \code{map}.
Note that you cannot use procedure with result type \builtin{<none>}
as the first argument of \code{map-nonpure1}.


\procdef{and-map?}
\label{sec:and-map?}


\startprocsyntax
\begin{codeblock}
  (and-map? \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}


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{and-map1?}
\label{sec:and-map1?}


\startprocsyntax
\begin{codeblock}
  (and-map1? \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}


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{and-map-nonpure?}
\label{sec:and-map-nonpure?}


\startprocsyntax
\begin{codeblock}
  (and-map-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{and-map?} except that \procarg{proc}
may have side effects.


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


\startprocsyntax
\begin{codeblock}
  (and-map-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{and-map1?} except that \procarg{proc}
may have side effects.


\procdef{or-map?}
\label{sec:or-map?}


\startprocsyntax
\begin{codeblock}
  (or-map? \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\).
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{or-map1?}
\label{sec:or-map1?}


\startprocsyntax
\begin{codeblock}
  (or-map1? \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}


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{or-map-nonpure?}
\label{sec:or-map-nonpure?}


\startprocsyntax
\begin{codeblock}
  (or-map-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{or-map?} except that \procarg{proc}
may have side effects.


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


\startprocsyntax
\begin{codeblock}
  (or-map-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{or-map1?} 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{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}


\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 Procedures}


\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 Procedures}


\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{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{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{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 Procedures}


\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 Procedures}


\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 Procedures}


\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 Procedures}


\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 Procedures}


\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 Procedures}


\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 Procedures}


\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{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 text-file-io)}}


\section{Data Types}


\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 Procedures}


\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{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{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{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{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{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 Procedures}


\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 system)}}


\section{Simple Procedures}


\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{(:maybe <string>)}}


\procpurity{pure}


If the environment variable does not exist return \code{()}.


\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 Procedures}


\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}


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{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 Procedures}


\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{Methods}


\indexmethod{=}

\noindent
\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 Procedures}


\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{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{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 Procedures}


\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{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 Procedures}


\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{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{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{(standar1d-library matrix)}}


\section{Data Types}


\begin{datatype}
  \datatypename{:matrix}
  \datatypetype{\builtin{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{A complex number}
\end{datatype}


\begin{datatype}
  \datatypename{:diagonal-matrix}
  \datatypetype{\builtin{<param-class>}}
  \datatypenrparams{1}
  \datatypedesc{A complex number}
\end{datatype}


Class \code{<complex>} is equal by value, not inheritable, and not
immutable.
Note that the indices of the matrices have base zero.


\section{Parametrized Procedures}


\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}


\section{Parametrized 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}


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


\section{Simple Procedures}


\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-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-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-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}


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


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<object>) <object> 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}%
{\cbuiltin{<object>}}


\procpurity{pure}


This procedure is similar to \code{map}, see section \ref{sec:map}.


\procdef{d-map1}


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


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<object>) <object> 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}%
{\cbuiltin{<object>}}


\procpurity{pure}


\procdef{d-map-nonpure}


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


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<object>) <object> 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}%
{\cbuiltin{<object>}}


\procpurity{nonpure}


This procedure is similar to \code{map-nonpure}, see section
\ref{sec:map-nonpure}.


\procdef{d-map-nonpure1}


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


\startprocarguments
\begin{arglist}
  \argument{proc}{\code{(:procedure (<object>) <object> 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}%
{\cbuiltin{<object>}}


\procpurity{nonpure}


\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 Procedures}


\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-table)}}


This module is deprecated and works only for Guile target
platform. You should use module \code{(standard-library hash-table2)}
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 Procedures}


\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 Procedures}


\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{make-object-hash-table}


\startprocsyntax
\begin{codeblock}
  (make-object-hash-table)
\end{codeblock}


\typeparams{\typeparam{value}}


\noprocarguments


\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{i-size})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \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)
\end{codeblock}


\typeparams{\typeparam{value}}


\noprocarguments


\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{i-size})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \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)
\end{codeblock}


\typeparams{\typeparam{value}}


\noprocarguments


\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{i-size})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \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}


\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 hash-table2)}}


\section{Data Types}


\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 Procedures}


\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 Procedures}


\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)
\end{codeblock}


\typeparams{\typeparam{value}}


\noprocarguments


\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{i-size})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \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)
\end{codeblock}


\typeparams{\typeparam{value}}


\noprocarguments


\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{i-size})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \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)
\end{codeblock}


\typeparams{\typeparam{value}}


\noprocarguments


\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{i-size})
\end{codeblock}


\typeparams{\typeparam{value}}


\startprocarguments
\begin{arglist}
  \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-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 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 2.0 documentation for further information.


\section{Simple Procedures}


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


\backmatter


\bibliographystyle{abbrv}

\bibliography{theme-d-language-manual}


\printindex


\end{document}
