trunk/c_xtn0/c_xtn0.tex

%$Header: /home/dashley/cvsrep/e3ft_gpl01/e3ft_gpl01/dtaipubs/esrgubka/c_xtn0/c_xtn0.tex,v 1.11 2003/04/03 19:49:36 dtashley Exp $

\chapter[\cxtnzeroshorttitle{}]{\cxtnzerolongtitle{}}

\label{cxtn0}

\beginchapterquote{``One way to prevent progress is by arguing that any first
                   step is unfair to somebody.''}
                   {Unknown}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}
%Section Tag: INT0
\label{cxtn0:sint0}

The Tcl scripting language provides for \emph{extensions}, which are
compiled-in commands added to the language.  These extensions have advantages
for performance, because they allow the high-frequency interactions to occur
in compiled code, and the lower-frequency interactions to occur in 
a Tcl script.

This chapter describes the extensions that have been added to the Tcl
interpreters which are part of \emph{The Iju Tool Set}.

Many of the parameter formats are common between the Tcl extensions
(described in this chapter) and the DOS command-line
utilities (described in Chapter
\cdcmzeroxrefhyphen{}\ref{cdcm0}).  For this reason, to avoid
redundancy of documentation, the parameter formats described
in Section \ctinzeroxrefhyphen{}\ref{ctin0:sccl0} apply both to the 
Tcl extensions
and the DOS command-line utilities.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Version Control Extensions}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{vcinfo}

\index{vcinfo@\emph{vcinfo}}
\begin{tclcommandname}{vcinfo}%
retrieves embedded static version and version control information for 
IjuScripter or IjuConsole.
This allows a script to determine which version of script interpreter it is
running under.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{vcinfo}{-ijutoolsversion}
\tclcommandsynopsisline{vcinfo}{?-crconly? -fileversion filename}
\tclcommandsynopsisline{vcinfo}{?-crconly? -extensionversion extensionname}
\tclcommandsynopsisline{vcinfo}{-buildmanifest}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{vcinfo} command returns information about the version of the
IjuScripter or IjuConsole executable program, about the version of
a specific source file, or [collectively] about the version of all files
which [directly] contribute to the behavior of an embedded Tcl/Tk extension.
This command can be used to
inquire about the version of the executable program or certain of its
components.

Most commonly, this command is used to help assure reproducibility
of a script's behavior by coding a script so that it will
run only under a specific version(s) of executable.

\tclcommanddescsynopsisline{vcinfo}{-ijutoolsversion}
\begin{tclcommandinternaldescription}
Returns a string identifying the version number of the IjuScripter or IjuConsole
executable.  The string will be of the form ``vm.nx'', where \emph{v} is the letter
``v'', \emph{m} is the major version number, \emph{n} is the minor version number, and
\emph{x} is an optional lower-case letter identifying a service release which fixes defects
but adds no new functionality.

For example, a return value of ``v1.03'' would identify version 1.03.  A return
value of ``v1.03c'' would identify the third service release to version 1.03; with
the service release designed to correct defects present in version 1.03b, but adding
no new functionality.
\end{tclcommandinternaldescription}

\tclcommanddescsynopsisline{vcinfo}{-fileversion filename}
\begin{tclcommandinternaldescription}
(Not yet implemented.)  Returns a string with version control information for the file
\emph{filename}, which must be part of the IjuScripter or IjuConsole build.
An error is generated if a \emph{filename} which is not part of the build
is supplied.  This form of the \emph{vcinfo} command is not normally used from a script.
\end{tclcommandinternaldescription}

\tclcommanddescsynopsisline{vcinfo}{-crconly -fileversion filename}
\begin{tclcommandinternaldescription}
(Not yet implemented.)  Returns the CRC32 of the the string result of the command above.
Note that the value returned is the CRC of the version control information embedded in the file
rather than the CRC of the file.
\emph{filename} must be part of the IjuScripter or IjuConsole build, and
an error is generated if a \emph{filename} which is not part of the build is supplied.
This form is
useful because it supplies a terse result of eight hexadecimal digits which can easily
establish with a probability of about $1-2^{-32}$ that two versions of IjuScripter or IjuConsole
have the same file component; or establish with unity probability that they do not.
\end{tclcommandinternaldescription}

\tclcommanddescsynopsisline{vcinfo}{-extensionversion extensionname}
\begin{tclcommandinternaldescription}
(Not yet implemented.)  Returns a string with version control information for all
files which contribute directly to the behavior of the Tcl extension \emph{extensionname},
which must be part of the IjuScripter or IjuConsole static build.
An error is generated if an \emph{extensionname} which is not part of the build
is supplied.
\end{tclcommandinternaldescription}

\tclcommanddescsynopsisline{vcinfo}{-crconly -extensionversion extensionname}
\begin{tclcommandinternaldescription}
(Not yet implemented.)  Returns the CRC32 of the the string result of the command above.
Note that the value returned is the CRC of the version control information embedded in the file(s)
rather than the CRC(s) of the file(s).
\emph{extensionname} must be part of the IjuScripter or IjuConsole build, and
an error is generated if an \emph{extensionname} which is not part of the build is supplied.
This form is
useful because it supplies a terse result of eight hexadecimal digits which can easily
establish with a probability of about $1-2^{-32}$ that two versions of IjuScripter or IjuConsole
have the same extension component(s); or establish with unity probability that they do not.
\end{tclcommandinternaldescription}

\tclcommanddescsynopsisline{vcinfo}{-crconly -buildmanifest}
\begin{tclcommandinternaldescription}
(Not yet implemented.)  Returns the full combined build manifest of IjuScripter and IjuConsole.
This includes size and CRC information for every file involved in the build.  This form
of \emph{vcinfo} is provided for assistance in defect diagnosis.
\end{tclcommandinternaldescription}

\end{tclcommanddescription}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{File Transformation Extensions}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{CRC, Checksum, And Hash Extensions}
%Section Tag: CRC0


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{crc32}
%Subsection Tag: CRC0
\label{cxtn0:scrc0:scrc0}


\index{crc32@\emph{crc32}}
\begin{tclcommandname}{crc32}%
generates the CRC-32 of a file or string.  This CRC can be reliably used to obtain
digital signatures of files or data.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{crc32}{filename}
\tclcommandsynopsisline{crc32}{-string binarystringval}

Note:  as of 01/01/01, the ``stateful'' forms below are not yet implemented.

\tclcommandsynopsisline{crc32}{-initialstate}
\tclcommandsynopsisline{crc32}{-advancestate state filename}
\tclcommandsynopsisline{crc32}{-advancestate -string state binarystringval}
\tclcommandsynopsisline{crc32}{-crcfromstate state}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{crc32} command forms the CRC-32 of the binary contents of a file
or of the binary contents of a string.  The CRC-32 is useful as a digital
signature, and can be used with unity probability to determine that two
files are different, or with a probability of about $1-2^{-32}$ to determine
that two files are almost certainly identical.

In the invocations below, the CRC-32 is always returned as a 10-character ASCII string
of the form \emph{``0xDDDDDDDD''}, where \emph{``DDDDDDDD''} is the hexadecimal representation
of the 32-bit CRC-32, and \emph{``0x''} is a constant 2-character prefix 
(the ``zero'' digit followed by ``x'') which is included for
aesthetics.  It is guaranteed that:

\begin{itemize}
\item The string returned will be exclusively ASCII.
\item The string will have a length of exactly 10 characters.
\item The first two characters of the string will be \emph{``0x''}.
\item The hexadecimal representation
      will be exactly 8 characters, and any letters 
      in the hexadecimal representation will be upper-case.
\end{itemize}

\tclcommanddescsynopsisline{crc32}{filename}
\begin{tclcommandinternaldescription}
Returns the CRC-32 of \emph{filename}, treated as an ordered collection of bytes (i.e.
newline characters and file termination characters are not processed---the file is
treated as a binary file).  \emph{filename} must be specified in the form accepted by
the Tcl internals (forward slashes only).
\end{tclcommandinternaldescription}

\tclcommanddescsynopsisline{crc32}{-string binarystringval}
\begin{tclcommandinternaldescription}
Returns the CRC-32 of \emph{binarystringval}, treated as an ordered collection of bytes (i.e.
newline characters and string termination characters are not honored---the string is
treated as a binary string).\footnote{For an ASCII string, the \emph{crc32} extension will
behave as expected, and will process all characters up to but not including the zero
terminator.  However, the \emph{crc32} extension will also correctly process non-ASCII strings.}
\end{tclcommandinternaldescription}

\tclcommanddescsynopsisline{crc32}{-initialstate}
\tclcommanddescsynopsisline{crc32}{-advancestate state filename}
\tclcommanddescsynopsisline{crc32}{-advancestate -string state filename}
\tclcommanddescsynopsisline{crc32}{-crcfromstate state}
\begin{tclcommandinternaldescription}
The four forms above are designed to allow ``running CRCs'' to be calculated; in which
the CRC is calculated piecemeal.  These forms allow the caller to retain the internal
state vector of the CRC calculation algorithm.

The first form, \emph{crc32 -initialstate}, returns an ASCII representation of the
correct initial state vector of the CRC-32 state machine.  The client is required
to obtain this initial state before beginning a piecemeal CRC calculation.  Although the
returned string is a constant (it will always be the same), representational details
may change in future versions of the \emph{crc32} extension, and so a caller should never
make assumptions about what this invocation will return, as these assumptions may
render a script incompatible with future versions of \emph{crc32}.

The second and third forms, \emph{crc32 -advancestate state filename}
and \emph{crc32 -advancestate -string state filename}, apply a file or a binary string
to \emph{state} to produce a new \emph{state}, which is returned.  This new \emph{state}
must be retained by the caller and used in subsequent calls.

The final form, \emph{crc32 -crcfromstate state}, maps from the state vector to the
calculated CRC, and will return a 10-character ASCII string as described above.
\end{tclcommandinternaldescription}
\end{tclcommanddescription}

\begin{tclcommandusagenotes}
(1) The ``piecemeal'' forms are as efficient as the file and string forms---there is no difference
in the internal algorithms.  The primary cost of the piecemeal forms is in importing and
exporting the algorithm state vector to/from an ASCII string.
Thus, the piecemeal forms become less efficient when
small files or strings are processed, as there are more exports and imports
of the state vector.  When using the piecemeal forms, processing the data in
larger chunks will give better performance.

(2) If the \emph{crc32} command is used to signature files, it is recommended that 
the \texttt{file size} command also be used to lower the probability of falsely
assuming two non-identical files are identical yet further.  Two files might be
assumed identical if they have the same size and the same CRC-32.
\end{tclcommandusagenotes}

\begin{tclcommandacknowledgements}
The \emph{crc32} command was implemented using ideas and C-language
code from a website (\cite{bibref:w:ellingsoncrc32pages})
provided by Richard A. Ellingson\index{Ellingson, Richard A.}
\cite{bibref:i:richardaellingson}.  I am especially
grateful to Mr. Ellingson for providing these materials publicly
and free of charge.
\end{tclcommandacknowledgements}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Random Number Generation Extensions}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{rngPwrResRndA}

\index{rngPwrResRndA@\emph{rngPwrResRndA}}
\begin{tclcommandname}{rngPwrResRndA}%
generates pseudo-random integers using the power residue
method with $\alpha = 7^5 = 16,807$ and
$M = 2^{31}-1 = 2,147,483,647$, providing a period of $M - 1 = 2^{31}-2 = 2,147,483,646$
(\cite{bibref:b:LeonGarciaProb}, pp. 69-71).
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{rngPwrResRndA}{}
\tclcommandsynopsisline{rngPwrResRndA}{$N$}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{rngPwrResRndA} command generates pseudo-random positive integers
using the [power residue] recursive formula

\begin{equation}
\label{cxtn0:rngPwrResRndA:eq00}
Z_i = \alpha Z_{i-1} mod M,
\end{equation}

with $(\alpha, M)$ chosen as $(\alpha = 7^5=16,807, M = 2^{31}-1 = 2,147,483,647)$, as
indicated above.  With these choices of $(\alpha, M)$, the sequence has a period
of $M - 1 = 2^{31}-2 = 2,147,483,646$ and good statistical properties.

The basis for choosing $(\alpha, M)$ has its origins in number theory, and won't
be discussed here.  We refer the reader to \cite{bibref:b:LeonGarciaProb}
and to mathematical papers on the power residue method.

This extension maintains one internal seed value, which is initialized to
1,578,127,215 at Tcl/Tk startup.\footnote{There is no scientific
reason for the choice of the integer 1,578,127,215 as the
startup value.  It was chosen arbitrarily with no rationale.}  
It is not possible to set the internal
seed to an arbitrary desired value.  The single internal seed value is adequate
for most applications which simply require random numbers.  If an
application requires control over the seed or requires multiple seeds, the ability
of this extension to generate the successor of an integer using 
(\ref{cxtn0:rngPwrResRndA:eq00}) can be used to achieve this functionality in a
script.


\tclcommanddescsynopsisline{rngPwrResRndA}{}
\begin{tclcommandinternaldescription}
Buffers the current seed for a return value, then advances this seed using
(\ref{cxtn0:rngPwrResRndA:eq00}).  Note that the ``old'' value is the value
returned, so that after Tcl/Tk startup the first value 
returned will be 1,578,127,215.
\end{tclcommandinternaldescription}

\tclcommanddescsynopsisline{rngPwrResRndA}{$N$}
\begin{tclcommandinternaldescription}
Forms the successor of $N$ using (\ref{cxtn0:rngPwrResRndA:eq00}) and
returns this successor.  The single internal seed value is not affected. 
\end{tclcommandinternaldescription}

\end{tclcommanddescription}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Arbitrary-Length Integer Extensions}
%Section Tag:  SARB0
\label{cxtn0:sarb0}

Starting with Version 1.05 of \emph{The Iju Tool Set}, \emph{IjuScripter} and
\emph{IjuConsole} contain a limited\footnote{By \emph{limited} we mean that
the library was consolidated and simplified.  The GNU MP library has as its
explicit design goal speed over clarity, and uses many advanced algorithms,
such as Karatsuba multiplication and special algorithms for the 
greatest common divisor of integers.  The library was simplified to regain
clarity at the expense of efficiency before its incorporation into
\emph{The Iju Tool Set}.} version of the 
\index{GNU!Multiple Precision Arithmetic Library (GMP)}\emph{GNU Multiple Precision
Library} \cite{bibref:s:gnumultipleprecisionarithmeticlibrary}.  
The version of the library incorporated into the tools has been
modified not to process integers larger than about 100,000 decimal digits.
We feel that this limit is sufficiently high for any practical applications,
and also that the computational speed will become unbearable long before the
data size limit is approached.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Error And Overflow Behavior Of Arbitrary-Length Integer Extensions}
%Subsection Tag:  EAB0
\label{cxtn0:sarb0:seab0}

The underlying data structure of arbitrary-length integers includes flags
to indicate that an arithmetic error has occured.  Essentially, these flags are
``NAN'', or ``not-a-number'' flags.  They indicate that the result is not
an integer.  These error flags propagate.  Combining a NAN value with a 
valid integer through a binary operation always results in a NAN value.  Naturally,
the result of a unary operation on a NAN value is also a NAN value.
The nature of NAN propagation is that the first arithmetic operation that
creates an error using valid integers as input will generate an overflow error (one of
the first two flags listed below).
Subsequent operations that use these original errors as input will generate
outputs which are ``taint'' errors (the second set of two flags listed below).

At the lowest level (in the innards of the `C' code), these flags are
bits within an integer.  However, for use within Tcl (where all data is string data), these
error flags are assigned symbolic strings to indicate the nature of the error.  Note that the
error flags are only approximate---they don't \emph{precisely} indicate the
nature of the error.  However, combined with propagation mechanisms,
they are adequate to prevent the interpretation
of invalid data as valid data.  Any result that is predicated on an invalid
result will itself be invalid.

The four possible error strings are enumerated below.  If any Tcl long integer
function creates an erroneous result, the result will be assigned one of these
four symbolic error strings rather than a string of digits.

\begin{itemize}
\item \index{GMP\_INTS\_EF\_INTOVF\_POS@\texttt{GMP\_INTS\_EF\_INTOVF\_POS}}
      \texttt{GMP\_INTS\_EF\_INTOVF\_POS}---the result is too positive (i.e. too
      large in a positive direction).  This error flag is also produced
          by an attempted division by zero, regardless of the sign of the
          dividend.
\item \index{GMP\_INTS\_EF\_INTOVF\_NEG@\texttt{GMP\_INTS\_EF\_INTOVF\_NEG}}
      \texttt{GMP\_INTS\_EF\_INTOVF\_NEG}---the result is too negative (i.e. too
      large in a negative direction).
\item \index{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS@\texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS}}
      \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS}---the result has been ``tainted''
      by combination with an integer which has the 
          \texttt{GMP\_INTS\_EF\_INTOVF\_POS} flag set.
\item \index{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG@\texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG}}
      \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG}---the result has been
      ``tainted'' by combination with an integer which has the
          \texttt{GMP\_INTS\_EF\_INTOVF\_NEG} flag set.
\end{itemize}

Note that the functions which operate on arbitrary length integers will
never produce an exception or a fatal error.  Instead, they will mark
results as NAN, and these NAN results will propagate.  
This mechanism provides for graceful failures, and also allows complex
calculations to be performed without the necessity of checking for
errors after every calculation step.

Note also that each of the separate arbitrary-length integer extensions described
in this section are a ``sub-extension'' to the \texttt{arbint} extension.  It
should also be noted
that many of these extensions perform the same function as a DOS
utility with the same name (see Chapter \cdcmzeroxrefhyphen{}\ref{cdcm0}).


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint iseflag} Extension}

\index{arbint iseflag@\emph{arbint iseflag}}
\index{iseflag@\emph{iseflag}}
\begin{tclcommandname}{arbint iseflag}%
identifies a string as an arbitrary integer error flag (or not) and
returns an integer value categorizing the string.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint iseflag }{stringarg}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension returns:
\begin{itemize}
\item ``0'' if the string argument supplied is not a recognized
      error flag.
\item ``1'' if the string argument supplied is recognized as the\\
      \texttt{GMP\_INTS\_EF\_INTOVF\_POS}
          error flag.
\item ``2'' if the string argument supplied is recognized as the\\
      \texttt{GMP\_INTS\_EF\_INTOVF\_NEG}
          error flag.
\item ``3'' if the string argument supplied is recognized as the\\
      \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS}
          error flag.
\item ``4'' if the string argument supplied is recognized as the\\
      \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG}
          error flag.
\end{itemize}

This extension is most often used to classify the output of an
arbitrary-length integer operation.  All valid integers will create
a value of zero if passed to this extension as an argument.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint iseflag GMP_INTS_EF_INTOVF_NEG
2
% arbint iseflag 249,422
0
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also Section \ref{cxtn0:sarb0:seab0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint commanate} Extension}
%Subsection Tag: COM0
\label{cxtn0:sarb0:scom0}

\index{arbint commanate@\emph{arbint commanate}}
\index{commanate@\emph{commanate}}
\begin{tclcommandname}{arbint commanate}%
inserts comma characters (`,') into a string as necessary to
make it a properly formatted integer with commas.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint commanate}{sint}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension adds commas to an integer to make it a properly
formatted integer with commas.  This extension is normally used to
format a string for more ``human-friendly'' output.  The input to this extension
must be either:

\begin{itemize}
\item A integer with no commas, as a string of digits (i.e. 
      scientific notation is not allowed).  The only valid representation
          for zero is ``0''.
\item An integer with all commas properly placed (i.e. it is 
      allowed to ``recommanate'' an integer that is already
          ``commanated'').
\item One of the four symbolic NAN strings described in
      Section \ref{cxtn0:sarb0:seab0}.  (Such a string
          will not be modified and will be returned unmodified from
          this extension.)
\end{itemize}

Any string that cannot be parsed as described above will result in
an error.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint intfac 129
4974504222477287440390234150412680963965661113713884314596886402265216893219635
5119328515747917449637889876686464600208839390308261862352651828829226610077151
044469167497022952331930501120000000000000000000000000000000
% arbint commanate [arbint intfac 129]
49,745,042,224,772,874,403,902,341,504,126,809,639,656,611,137,138,843,145,968,
864,022,652,168,932,196,355,119,328,515,747,917,449,637,889,876,686,464,600,208
,839,390,308,261,862,352,651,828,829,226,610,077,151,044,469,167,497,022,952,33
1,930,501,120,000,000,000,000,000,000,000,000,000,000
% arbint commanate GMP_INTS_EF_INTOVF_POS
GMP_INTS_EF_INTOVF_POS
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint decommanate} Extension}
%Subsection Tag: dco0
\label{cxtn0:sarb0:sdco0}

\index{arbint decommanate@\emph{arbint decommanate}}
\index{decommanate@\emph{decommanate}}
\begin{tclcommandname}{arbint decommanate}%
removes comma characters (`,') from a properly
formatted integer.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint decommanate}{sint}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension removes commas from a properly formatted integer.
The input to this extension
must be either:

\begin{itemize}
\item A integer with no commas, as a string of digits (i.e. 
      scientific notation is not allowed).  The only valid representation
          for zero is ``0''.  (Note that it is allowed to ``decommanate''
          an integer that contains no commas.)
\item An integer with all commas properly placed.
\item One of the four symbolic NAN strings described in
      Section \ref{cxtn0:sarb0:seab0}.  (Such a string
          will not be modified and will be returned unmodified from
          this extension.)
\end{itemize}

Any string that cannot be parsed as described above will result in
an error.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint intfac 129
4974504222477287440390234150412680963965661113713884314596886402265216893219635
5119328515747917449637889876686464600208839390308261862352651828829226610077151
044469167497022952331930501120000000000000000000000000000000
% arbint commanate [arbint intfac 129]
49,745,042,224,772,874,403,902,341,504,126,809,639,656,611,137,138,843,145,968,
864,022,652,168,932,196,355,119,328,515,747,917,449,637,889,876,686,464,600,208
,839,390,308,261,862,352,651,828,829,226,610,077,151,044,469,167,497,022,952,33
1,930,501,120,000,000,000,000,000,000,000,000,000,000
% set number [arbint commanate [arbint intfac 129]]
49,745,042,224,772,874,403,902,341,504,126,809,639,656,611,137,138,843,145,968,
864,022,652,168,932,196,355,119,328,515,747,917,449,637,889,876,686,464,600,208
,839,390,308,261,862,352,651,828,829,226,610,077,151,044,469,167,497,022,952,33
1,930,501,120,000,000,000,000,000,000,000,000,000,000
% arbint decommanate $number
4974504222477287440390234150412680963965661113713884314596886402265216893219635
5119328515747917449637889876686464600208839390308261862352651828829226610077151
044469167497022952331930501120000000000000000000000000000000
% arbint decommanate GMP_INTS_EF_INTOVF_POS
GMP_INTS_EF_INTOVF_POS
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint intcmp} Extension}
%Subsection Tag: add0
\label{cxtn0:sarb0:scmp0}

\index{arbint intcmp@\emph{arbint intcmp}}
\index{intcmp@\emph{intcmp}}
\begin{tclcommandname}{arbint intcmp}%
compares two arbitrary integers and returns a result indicating their relative
ordering.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint intcmp}{sint\_a sint\_b}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension compares \emph{sint\_a} and \emph{sint\_b} and
returns $\{-1, 0, 1\}$ if 
\emph{sint\_a} $\{ <, =, > \}$ \emph{sint\_b}.  This extension
is used to compare arbitrarily large integers in Tcl scripts.
Because NAN tags (see Section \ref{cxtn0:sarb0:seab0}) 
cannot be logically compared,
this extension will signal an error if either parameter is 
a NAN tag.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint intcmp -5 -3
-1
% arbint intcmp -5 -5
0
% arbint intcmp 7 5
1
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{arbint rncmp} Tcl extension,
Section \ref{cxtn0:srne0:srcm0}, which performs a similar
function for arbitrary rational numbers.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint intadd} Extension}
%Subsection Tag: add0
\label{cxtn0:sarb0:sadd0}

\index{arbint intadd@\emph{arbint intadd}}
\index{intadd@\emph{intadd}}
\begin{tclcommandname}{arbint intadd}%
calculates and returns as a string the sum of two integers.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint intadd}{sint sint}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension returns the sum of two integer
arguments, or one of the NAN tags described in
Section \ref{cxtn0:sarb0:seab0} if an overflow occurs.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint intadd 1e20 21643215482123164
100021643215482123164
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{intadd} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sadd0}.
\end{tclcommandseealso}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint intsub} Extension}
%Subsection Tag: mod0
\label{cxtn0:sarb0:ssub0}

\index{arbint intsub@\emph{arbint intsub}}
\index{intsub@\emph{intsub}}
\begin{tclcommandname}{arbint intsub}%
calculates and returns as a string the difference of two integers.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint intsub}{sint sint}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension returns the difference of two integer
arguments, or one of the NAN tags described in
Section \ref{cxtn0:sarb0:seab0} if an overflow occurs.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint intsub 123846129436219 1e25
-9999999999876153870563781
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{intsub} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:ssub0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint intmul} Extension}
%Subsection Tag: mul0
\label{cxtn0:sarb0:smul0}

\index{arbint intmul@\emph{arbint intmul}}
\index{intmul@\emph{intmul}}
\begin{tclcommandname}{arbint intmul}%
calculates and returns as a string the product of two integers.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint intmul}{sint sint}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension returns the product of two integer arguments.
The result of this 
extension will always be either a NAN tag
(see Section \ref{cxtn0:sarb0:seab0}) 
or an integer.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint intmul -329749813264962165493214963541976325 4.36463214521843123e38
-143923663485602892702423181098245942606484617030062975000000000000000000000
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{intmul} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:smul0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint intdiv} Extension}
%Subsection Tag: div0
\label{cxtn0:sarb0:sdiv0}

\index{arbint intdiv@\emph{arbint intdiv}}
\index{intdiv@\emph{intdiv}}
\begin{tclcommandname}{arbint intdiv}%
calculates and returns as a string the quotient of two integers.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint intdiv}{sint\_dividend sint\_divisor}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension returns the quotient of two integer arguments.
The first integer argument is interpreted to be the dividend,
and the second the divisor.  The quotient is without remainder,
i.e. what is actually returned is

\begin{equation}
sgn(dividend \cdot divisor) 
\left\lfloor{\frac{|dividend|}{|divisor|}}\right\rfloor ,
\end{equation}

or one of the NAN tags described in
Section \ref{cxtn0:sarb0:seab0}
if division by zero is attempted.  Note that division
by zero is not an error (as far as a Tcl script is concerned):
the only outcome is that the result will be assigned a symbolic
NAN tag rather than a string of digits representing an integer.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint intdiv 2364832165653218648321543215848236458124 2854871354812543821
828349817467869034672
% arbint intdiv 2364832165653218648321543215848236458124 0
GMP_INTS_EF_INTOVF_POS
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{intdiv} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sdiv0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint intmod} Extension}
%Subsection Tag: mod0
\label{cxtn0:sarb0:smod0}

\index{arbint intmod@\emph{arbint intmod}}
\index{intmod@\emph{intmod}}
\begin{tclcommandname}{arbint intmod}%
calculates and returns as a string the modulo of two integers.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint intmod}{sint\_dividend sint\_divisor}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension returns the remainder resulting from the 
division of two integer arguments.
The first integer argument is interpreted to be the dividend,
and the second the divisor.  The sign of the remainder is always 
chosen so that the following relationship holds:

\begin{equation}
dividend \; div \; divisor + \frac{dividend \; mod \; divisor}{divisor} 
= \frac{dividend}{divisor},
\end{equation}

where the \emph{div} operator is as explained in Section
\ref{cxtn0:sarb0:sdiv0} for the \emph{arbint intdiv} extension.
If division by zero is attempted, this extension 
returns one of the NAN tags described in
Section \ref{cxtn0:sarb0:seab0}.  Note that division
by zero is not an error (as far as a Tcl script is concerned):
the only outcome is that the result will be assigned a symbolic
NAN tag rather than a string of digits representing an integer.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint intmod 264321654632432421 2175438321654
1547674828113
% arbint intmod 264321654632432421 0
GMP_INTS_EF_INTOVF_POS
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{intmod} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:smod0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint intexp} Extension}
%Subsection Tag: exp0
\label{cxtn0:sarb0:sixp0}

\index{arbint intexp@\emph{arbint intexp}}
\index{intexp@\emph{intexp}}
\begin{tclcommandname}{arbint intexp}%
computes and returns as a string one integer
exponentiated to the power of another, 
$base^{exponent}$.

\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint intexp}{sint\_base uint32\_exponent}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension exponentiates an integer to a non-negative
power.  For
simplicity and convenience, $0^0$ will return 1, although
this is inconsistent with the mathematical definition.
All other exponentiations are as expected.

The method used to exponentiate is simple squaring and multiplying
based on the bit pattern of the exponent, as discussed 
in \cite{bibref:b:knuthclassic2ndedvol2}, pp. 461-462.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint intexp 47 69
2370021018513446695324337468306899241173950476009917473665218657220346081293500
4143894985892600403244809901800125167
% arbint intexp 1 0
1
% arbint intexp 0 0
1
% arbint intexp 0 1
0
% arbint intexp 0 19237498
0
% arbint intexp -47 69
-237002101851344669532433746830689924117395047600991747366521865722034608129350
04143894985892600403244809901800125167
% arbint intexp -47 -69
arbint intexp: "-69" is not a recognized unsigned 32-bit integer.
% arbint intexp 193461926436214 99999999
GMP_INTS_EF_INTOVF_TAINT_POS
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{intexp} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sixp0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint intfac} Extension}
%Subsection Tag: fac0
\label{cxtn0:sarb0:sfac0}

\index{arbint intfac@\emph{arbint intfac}}
\index{intfac@\emph{intfac}}
\begin{tclcommandname}{arbint intfac}%
computes and returns as a string the factorial ($!$) of
the integer argument supplied.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint intfac}{uint32}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension returns the factorial of an integer argument.
Any of the symbolic NAN strings described in 
Section \ref{cxtn0:sarb0:seab0} will cause a return
value of an appropriate symbolic NAN string.
Strings that cannot be parsed as integers or 
NAN strings, strings 
that represent negative integers, and strings that represent
non-negative integers that will not fit in 32 bits will generate
an error.

As of this writing, 200! requires about 1 second to compute on a
600MHz PC.  Although this function will calculate factorials of any size
up to 100,000 digits, it is not recommended to use this function above 
about 200! as the increase in computation time appears to be exponential
with respect to the argument.  This may improve in the future as algorithmic
enhancements are made.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint intfac 129
4974504222477287440390234150412680963965661113713884314596886402265216893219635
5119328515747917449637889876686464600208839390308261862352651828829226610077151
044469167497022952331930501120000000000000000000000000000000
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{intfac} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sifc0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint intgcd} Extension}
%Subsection Tag: gcd0
\label{cxtn0:sarb0:sgcd0}

\index{arbint intgcd@\emph{arbint intgcd}}
\index{intgcd@\emph{intgcd}}
\begin{tclcommandname}{arbint intgcd}%
calculates and returns as a string the g.c.d. 
(greatest common divisor) of two integers.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint intgcd}{sint sint}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension returns the g.c.d. of two integer arguments.
If either argument is 0, the result will be 1.  If either
argument is negative, the absolute value of the argument
will be used in its place.  The result of this 
extension will always be either a NAN tag
(see Section \ref{cxtn0:sarb0:seab0}) 
or an integer greater than or equal to 1.

The algorithm employed is the
\emph{Modern Euclidian Algorithm} as
described in \cite{bibref:b:knuthclassic2ndedvol2}, p. 337.
Although faster algorithms for computer
implementation do exist, this is the simplest
and most direct algorithm.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint intgcd 263130836933693530167218012160000000 503580
4620
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{intgcd} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sgcd0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint intlcm} Extension}
%Subsection Tag: lcm0
\label{cxtn0:sarb0:slcm0}

\index{arbint intgcd@\emph{arbint intlcm}}
\index{intlcm@\emph{intlcm}}
\begin{tclcommandname}{arbint intlcm}%
calculates and returns as a string the l.c.m. 
(least common multiple) of two integers.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint intlcm}{sint sint}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension returns the l.c.m. of two integer arguments.
If either argument is 0, the argument will be treated as if it
were 1.  If either
argument is negative, the absolute value of the argument
will be used in its place.  The result of this 
extension will always be either a NAN tag
(see Section \ref{cxtn0:sarb0:seab0}) 
or an integer greater than or equal to 1.

The algorithm employed is to calculate
the g.c.d. of the arguments using the
\emph{Modern Euclidian Algorithm} as
described in \cite{bibref:b:knuthclassic2ndedvol2}, p. 337;
then to divide the product of the arguments by their
g.c.d., as implied by \cite{bibref:b:knuthclassic2ndedvol2},
p. 334, Equation 10.  Both sides of this equation can be
divided by $\gcd(u,v)$ to yield

\begin{equation}
lcm(u,v) = \frac{uv}{\gcd(u,v)},
\end{equation}

and this is the relationship used to calculated the l.c.m.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint intlcm 64 100
1600
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{intlcm} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:slcm0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Rational Number Extensions}
%Section Tag: RNE0

This section describes extensions that implement
rational number arithmetic.

In most cases, the rational number extensions described in
this section are liberal in the representations of rational numbers
they accept, but always produce results as integer components
separated by the forward slash character.  This means that the
rational number extensions described in this section can exchange data
freely---the output of any of the extensions is suitable as input
for another extension.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint rnred} Extension}
%Subsection Tag: RNR0
\label{cxtn0:srne0:srnr0}

\index{arbint rnred@\emph{arbint rnred}}
\index{rnred@\emph{rnred}}
\begin{tclcommandname}{arbint rnred}%
reduces a rational number to lowest terms and normalizes it.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint rnred}{srn}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{arbint rnred} extension reduces a rational number to its lowest terms
and normalizes it.  By \emph{reducing} a rational number and
normalizing it, we mean the application of the following rules.

\begin{enumerate}
\item Any number with a numerator of zero is given the
      representation 0/1, i.e. 0/1 is the canonical 
          representation of zero.
\item Any number with a denominator of zero is given
      the representation 1/0, i.e. 1/0 is the canonical
          representation of ``division by zero''.
\item Rational numbers which are effectively positive
      are normalized to have a positve numerator and positive
          denominator.
\item Rational numbers which are effectively negative are
      normalized to have a negative numerator and positive
          denominator.
\item Any common factors are removed from the numerator and
      denominator, i.e. the numerator and denominator are
          made coprime.
\end{enumerate}

Note that one behavior above may be unexpected---the
\emph{arbint rnred} extension \emph{will} accept a rational number
specified with a denominator of zero, and will normalize it to
1/0.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint rnred 422.414
211207/500
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{rnred} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srnr0}.
\end{tclcommandseealso}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint rnadd} Extension}
%Subsection Tag: RAD0
\label{cxtn0:srne0:srad0}

\index{arbint rnadd@\emph{arbint rnadd}}
\index{rnadd@\emph{rnadd}}
\begin{tclcommandname}{arbint rnadd}%
adds two rational numbers to produce a normalized rational result.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint rnadd}{srn srn}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{arbint rnadd} extension adds two rational numbers to produce a 
normalized rational result.

If either of the two rational input arguments has a denominator of zero,
the string ``NAN'' will be returned.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint rnadd 3.1415 64/259
1755297/518000
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{rnadd} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srna0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint rnsub} Extension}
%Subsection Tag: RSB0
\label{cxtn0:srne0:srsb0}

\index{arbint rnsub@\emph{arbint rnsub}}
\index{rnsub@\emph{rnsub}}
\begin{tclcommandname}{arbint rnsub}%
subtracts two rational numbers to produce a normalized rational result.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint rnsub}{srn\_arg1 srn\_arg2}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{arbint rnsub} extension subtracts two rational numbers to produce a 
normalized rational result.  The second argument is subtracted from the first, i.e.
the result $arg_2 - arg_1$ is formed.

If either of the two rational input arguments has a denominator of zero,
the string ``NAN'' will be returned.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint rnsub 3.129 122/451
1289179/451000
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{rnsub} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srsb0}.
\end{tclcommandseealso}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint rnmul} Extension}
%Subsection Tag: RMU0
\label{cxtn0:srne0:srmu0}

\index{arbint rnmul@\emph{arbint rnmul}}
\index{rnmul@\emph{rnmul}}
\begin{tclcommandname}{arbint rnmul}%
multiplies two rational numbers to produce a normalized rational result.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint rnmul}{srn srn}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{arbint rnmul} extension multiplies two rational numbers to produce a 
normalized rational result.

If either of the two rational input arguments has a denominator of zero,
the string ``NAN'' will be returned.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint rnmul 3.14 32/491
2512/12275
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{rnmul} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srmu0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint rndiv} Extension}
%Subsection Tag: RDV0
\label{cxtn0:srne0:srdv0}

\index{arbint rndiv@\emph{arbint rndiv}}
\index{rndiv@\emph{rndiv}}
\begin{tclcommandname}{arbint rndiv}%
divides two rational numbers to produce a normalized rational result.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint rndiv}{srn srn}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{arbint rndiv} extension divides two rational numbers to produce a 
normalized rational result.

If either of the two rational input arguments has a denominator of zero, or
if the divisor is zero,
the string ``NAN'' will be returned.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint rndiv 3.14 32/491
77087/1600
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{rnmul} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srdv0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint rncmp} Extension}
%Subsection Tag: RCM0
\label{cxtn0:srne0:srcm0}

\index{arbint rncmp@\emph{arbint rncmp}}
\index{rncmp@\emph{rncmp}}
\begin{tclcommandname}{arbint rncmp}%
compares two rational numbers.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint rncmp}{srn\_arg1 srn\_arg2}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{arbint rncmp} extension compares two rational numbers
and returns $\{-1, 0, 1\}$ if $arg_1$
$\{<, =, >\}$ $arg_2$.

The rational numbers do not need to be reduced or normalized in any way.
Any combination of signs on the numerators and denominators is permitted,
and the numerators and denominators are not required to be coprime.

If for any reason the extension cannot compare the rational numbers,
an error message will be returned and the extension will return
\texttt{TCL\_ERROR}, which will normally cause a script to fail.
The reason for the error return is that if the two rational number
cannot be compared, in most cases it is logically impossible for a script to
continue.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint rncmp -4/-7 0.5
1
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}


\begin{tclcommandseealso}
See also the \emph{arbint intcmp} Tcl extension,
Section \ref{cxtn0:sarb0:scmp0}, which performs a similar
function for arbitrary integers.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Number Theory Extensions}
%Section Tag: NTH0
\label{cxtn0:snth0}

This section describes extensions that are related to number theory.
Extensions that deal with continued fractions are included in this
category because of the relationship between continued fractions
and number theory.  Any extensions related to number theory that 
must process large integers are
still a subextension of \texttt{arbint}.\footnote{This was done to
avoid creating an excessive number of software modules and 
Tcl extensions.}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint cfratnum} Extension}
%Subsection Tag: CFR0
\label{cxtn0:snth0:scfr0}

\index{arbint cfratnum@\emph{arbint cfratnum}}
\index{cfratnum@\emph{cfratnum}}
\begin{tclcommandname}{arbint cfratnum}%
calculates the partial quotients and convergents of
a non-negative rational number.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint cfratnum}{urn}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
This extension calculates the partial quotients and convergents of 
of a non-negative rational number.  The results are
returned as a string containing integers separated by spaces.
The integers are arranged in consecutive triplets of the form
``$a_k \; p_k \; q_k$''.  Such a string can be converted to a
list and processed from a Tcl script.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint cfratnum 3.14
3 3 1 7 22 7 7 157 50
\end{verbatim}
\end{scriptsize}

In the sample invocation above, note that $a_0 = 3$,
$p_0 = 3$, $q_0 = 1$, $a_1 = 7$, $p_1 = 22$, $q_1 = 7$,
$a_2 = 7$, $p_2 = 157$, and $q_2 = 50$.  
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
See also the \emph{cfratnum} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:snth0:scfr0}.
\end{tclcommandseealso}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint cfbrapab} Extension}
%Subsection Tag: BRA0
\label{cxtn0:snth0:sbra0}

\index{arbint cfbrapab@\emph{arbint cfbrapab}}
\index{cfbrapab@\emph{cfbrapab}}
\begin{tclcommandname}{arbint cfbrapab}%
finds best rational approximations to a supplied rational
number in either the Farey series of order $k_{MAX}$ (denoted
$F_{k_{MAX}}$), or in a rectangular region of the integer lattice
bounded by $k \leq k_{MAX}$ and $h \leq h_{MAX}$
(denoted $F_{k_{MAX}, \overline{h_{MAX}}}$).
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint cfbrapab}{srn uint\_kmax [options]}
\tclcommandsynopsisline{arbint cfbrapab}{srn uint\_kmax uint\_hmax [options]}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
When used without options, this extension returns the closest rational
number to the specified rational number in $F_{k_{MAX}}$ (if only $k_{MAX}$ is
specified) or in  $F_{k_{MAX}, \overline{h_{MAX}}}$ (if both 
$k_{MAX}$ and $h_{MAX}$ are specified).  If the rational number specified
is already in the series of interest, its reduced form is returned.
If the rational number supplied is equidistant from the two closest
formable rational numbers in the series of interest, the neighbor of smaller 
magnitude (absolute value) is returned.

When operating in $F_{k_{MAX}}$, there are no practical constraints 
on the size of rational numbers that this extension can approximate.
However, when operating in $F_{k_{MAX}, \overline{h_{MAX}}}$,
this extension will not accept rational numbers outside the
interval $[-h_{MAX}, h_{MAX}]$ (note that $-h_{MAX}/1$ and
$h_{MAX}/1$ are the smallest and largest numbers that can be formed
when the numerator of the rational approximations is constrained).
Any attempt to approximate a rational number outside $[-h_{MAX}, h_{MAX}]$
will result in a Tcl error, which will normally terminate a script.

The \texttt{-neversmaller} and \texttt{-neverlarger}
options cause the extension to always choose the larger and
smaller neighbors (rather than the closer neighbor), respectively.
These options are useful when approximations are desired that 
do not underestimate or overestimate the function of interest for
large values in the domain.  These parameters do not affect
the behavior if the rational number supplied is already in the
series of interest---the reduced form of the specified number
is returned in the case of equality.
The \texttt{-neversmaller} and \texttt{-neverlarger} options
must be used alone, with no other options.

The \texttt{-pred} and \texttt{-succ} options cause this extension
to calculate either the predecessor or successor to the rational
number specified in the series of interest.  If the number specified
is already in series of interest, its predecessor or successor 
is returned. 
If the number specified is not in the series of interest,
the left or right neighbor is returned.  If no predecessor,
successor, or left or right neighbor exist, an error is generated.
These options (\texttt{-pred} or \texttt{-succ})
must be used alone, with no other options.

The normal behavior of this extension is to return a single
rational number, as described above.
The \texttt{-n \emph{uint32\_count}} option will cause the extension
to return \emph{count} rational numbers on each side of the
rational number specified.  If the rational number specified is already
in the series of interest, it will be returned as well, normally\footnote{If
the set of returned rational numbers is not clipped at $-h_{MAX}/1$ or
$h_{MAX}/1$.} resulting
in an odd number of rational numbers returned.  If the rational number
specified is not already in the series of interest, an even number of
rational numbers will normally be returned.  The rational
numbers returned are prefixed with integer indices, which 
indicate their ordinal distance from the rational number to be approximated
(see the invocation examples below).  The index of 0 is reserved for
the reduced form of the rational number specified, and and a rational number with
this index will be in the output only if the rational number supplied was already
in the series of interest.
The rational numbers returned
will be formatted as integer indices and slash-separated integers, separated
by single spaces and arranged in ascending order..
If the number of rational numbers requested by this option exceeds
the number available, the sequence will simply be truncated at
$-h_{MAX}/1$ or $h_{MAX}/1$, as appropriate.  Any request for more than
10,000 neighbors (on each side) will be clipped to 10,000.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
% arbint cfbrapab 1.6093 255
346/215
% arbint cfbrapab 1.6093 255 255
243/151
% arbint cfbrapab 1.6093 255 255 -neversmaller
103/64
% arbint cfbrapab 1.6093 255 255 -neverlarger
243/151
% arbint cfbrapab 1.6093 255 255 -n 20
-20 143/89 -19 188/117 -18 233/145 -17 45/28 -16 217/135 -15 172/107 -14 127/79
-13 209/130 -12 82/51 -11 201/125 -10 119/74 -9 156/97 -8 193/120 -7 230/143 -6
37/23 -5 251/156 -4 214/133 -3 177/110 -2 140/87 -1 243/151 1 103/64 2 169/105
3 235/146 4 66/41 5 227/141 6 161/100 7 95/59 8 219/136 9 124/77 10 153/95 11
182/113 12 211/131 13 240/149 14 29/18 15 253/157 16 224/139 17 195/121 18 
166/103 19 137/85 20 245/152
% arbint cfbrapab 1.6093 255 255 -succ
103/64
% arbint cfbrapab 1.6093 255 255 -pred
243/151
% arbint cfbrapab 2/3 255 255 -pred
169/254
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}

\begin{tclcommandseealso}
This extension uses the continued fraction
algorithms presented in Chapter \ccfrzeroxrefhyphen{}\ref{ccfr0}.
See also the \emph{cfratnum} DOS command-line utility, 
Section \cdcmzeroxrefhyphen{}\ref{cdcm0:snth0:sbra0}.
\end{tclcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \texttt{arbint const} Extension}
%Subsection Tag: CEX0
\label{cxtn0:snth0:scex0}

\index{arbint const@\emph{arbint const}}
\index{const (Tcl arbint sub-extension)@\emph{const} (Tcl \emph{arbint} sub-extension)}
\begin{tclcommandname}{arbint const}%
returns a string representing the value of important
mathematical and conversion constants (such as the value
of $\pi$ or $e$, or the conversion factor from miles to kilometers).
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{arbint const}{const\_tag}
\tclcommandsynopsisline{arbint const}{const\_tag uint32\_ndigits}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{const} subextension returns the value (as a string) of
constants that may be useful in engineering work.  Such constants
may include mathematically significant numbers (such as 
\index{pi@$\pi$ (transcendental constant)}$\pi$ or 
\index{e@$e$ (transcendental constant)}$e$), or 
useful conversion factors (the conversion factor from 
miles to kilometers, for example).  These string constants
can be used in calculations involving rational numbers.

All constants are simply tabulated as character strings
within the `C' source code.

Mathematically significant numbers (which, to the best
of the author's knowledge are always irrational and
usually transcendental, as mathematicians
don't seem to have any lasting interest in specific integers
or rational numbers) are available to about 1,000 significant digits,
and have been obtained from various web pages.  It is reasoned that
1,000 significant digits should be adequate for engineering applications.

Measurement unit conversion constants have typically been obtained from
\emph{NIST Special Publication 811} \cite{bibref:b:nistsp811:1995ed}.
These constants are always tabulated with their full precision, since
no physical constant can be precise to more than several decimal places.

If the number of significant figures is not specified, 
each constant is returned as a string with a default number of
decimal places (typically about 30).  In most cases, the default
number of decimal places provides more than enough precision for
engineering work.  However, an optional parameter allows more
or fewer digits to be obtained, up to the maximum number tabulated internally
in the software.  The default number of decimal places is a compromise
between calculation speed and accuracy.  It is felt in most cases that
the default number of decimal places provides excellent accuracy
and good calculation speed.

Please e-mail the authors if you would like additional useful 
constants included.  Because the list of tabulated constants
may grow and shrink, it would not be a sound decision to document
the constants which are included here.  Instead, use
\emph{arbint const} with an invalid tag, and the software itself
will list all of the internally tabulated constants and their
significance.
\end{tclcommanddescription}

\begin{tclcommandsampleinvocations}
Please note that the sample invocation below was created using
v1.05 of the tool set.  The list of constants may have grown
since this example was created.  Please poll the software directly
by using \emph{arbint const} with an invalid tag to obtain the 
list of constants and their significance.
\begin{scriptsize}
\begin{verbatim}
% arbint const xxx
arbint const: "xxx" is not a recognized constant.
Available constants are:
   e (1000 digits available)
      Historically significant transcendental constant.  Digits obtained
      from http://fermi.udw.ac.za/physics/e.html on 08/17/01.
   g_si (6 digits available)
      Gravitational acceleration in SI units, meters per second**2.
      Obtained from NIST Special Publication 811 on 08/17/01.
   in2m (3 digits available)
      Multiplicative conversion factor from inches to meters.
      Obtained from NIST Special Publication 811 on 08/17/01.
   mi2km (7 digits available)
      Multiplicative conversion factor from miles to kilometers.
      Obtained from NIST Special Publication 811 on 08/17/01.
   pi (1201 digits available)
      Transcendental constant supplying ratio of a circle's circumference
      to its diameter.  Digits obtained from http://www.joyofpi.com/
      pi.htm on 08/17/01.
   sqrt5 (1040 digits available)
      The square root of 5.  Digits obtained from
      http://home.earthlink.net/~maryski/sqrt51000000.txt on 08/17/01.
% arbint const pi
3.14159265358979323846264338327
% arbint const pi 100
3.141592653589793238462643383279502884197169399375105820974944592307816406286208998628034825342117067
% arbint const pi 10
3.141592653
% arbint cfbrapab [arbint const pi 100] 65535 65535
65298/20785
\end{verbatim}
\end{scriptsize}
\end{tclcommandsampleinvocations}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Miscellaneous Extensions}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{credits}

\index{credits@\emph{credits}}
\begin{tclcommandname}{credits}%
returns information about authorship of software components.
\end{tclcommandname}

\begin{tclcommandsynopsis}
\tclcommandsynopsisline{credits}{}
\tclcommandsynopsisline{credits}{searchstring}
\end{tclcommandsynopsis}

\begin{tclcommanddescription}
The \emph{credits} command returns a list of contributors to the tools,
their area(s) of contribution, and e-mail addresses.  The volume of
information returned can be reduced by using an optional \emph{searchstring}.

\tclcommanddescsynopsisline{credits}{}
\begin{tclcommandinternaldescription}
Returns the complete list of contributors to the tools and their area(s) of contribution.
\end{tclcommandinternaldescription}

\tclcommanddescsynopsisline{credits}{searchstring}
\begin{tclcommandinternaldescription}
Returns all credit records containing \emph{searchstring}.
Most commonly, this option is used to search for information about a specific
command by using the command name as the \emph{searchstring}, or about a
specific individual by using a component of the individual's name as the
\emph{searchstring}.

\end{tclcommandinternaldescription}

\end{tclcommanddescription}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\noindent\begin{figure}[!b]
\noindent\rule[-0.25in]{\textwidth}{1pt}
\begin{tiny}
\begin{verbatim}
$RCSfile: c_xtn0.tex,v $
$Source: /home/dashley/cvsrep/e3ft_gpl01/e3ft_gpl01/dtaipubs/esrgubka/c_xtn0/c_xtn0.tex,v $
$Revision: 1.11 $
$Author: dtashley $
$Date: 2003/04/03 19:49:36 $
\end{verbatim}
\end{tiny}
\noindent\rule[0.25in]{\textwidth}{1pt}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% $Log: c_xtn0.tex,v $
% Revision 1.11  2003/04/03 19:49:36  dtashley
% Global corrections to typeface of "gcd" made as per Jan-Hinnerk Reichert's
% recommendation.
%
% Revision 1.10  2001/08/18 18:37:56  dtashley
% Preparation for v1.05 release.
%
% Revision 1.9  2001/08/16 19:53:27  dtashley
% Beginning to prepare for v1.05 release.
%
% Revision 1.8  2001/08/12 10:15:33  dtashley
% Safety check-in.  Substantial progress.
%
% Revision 1.7  2001/08/10 00:56:07  dtashley
% Completion of basic rational number arithmetic utilities and extensions.
%
% Revision 1.6  2001/08/08 02:25:03  dtashley
% Completion of RNRED utility and ARBINT RNRED Tcl extension.
%
% Revision 1.5  2001/08/07 10:46:44  dtashley
% Completion of CFRATNUM Tcl extension and DOS command-line utility.
%
% Revision 1.4  2001/08/01 03:37:39  dtashley
% Finished most primitive integer operations, both as Tcl extensions and
% as DOS command-line utilities, such as addition, subtraction,
% multiplication, division, and modulo.
%
% Revision 1.3  2001/07/30 02:54:17  dtashley
% INTFAC extension and command-line utility finished.
%
% Revision 1.2  2001/07/01 20:50:58  dtashley
% Move out of binary mode for use with CVS.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% $History: c_xtn0.tex $
% 
% *****************  Version 3  *****************
% User: Dashley1     Date: 2/10/01    Time: 2:03a
% Updated in $/uC Software Multi-Volume Book (A)/Chapter, XTN0, IjuScripter-IjuConsole Tcl-Tk Extensions
% Completion of Farey series chapter.
% 
% *****************  Version 2  *****************
% User: Dashley1     Date: 1/01/01    Time: 8:13p
% Updated in $/uC Software Multi-Volume Book (A)/Chapter, XTN0, IjuScripter-IjuConsole Tcl-Tk Extensions
% Edits.
%
% *****************  Version 1  *****************
% User: Dashley1     Date: 12/31/00   Time: 9:34p
% Created in $/uC Software Multi-Volume Book (A)/Chapter, XTN0, IjuScripter-IjuConsole Tcl-Tk Extensions
% Initial check-in.
%
%End of file C_XTN0.TEX