trunk/c_dcm0/c_dcm0.tex

%$Header$

\chapter{\cdcmzerolongtitle{}}

\label{cdcm0}


`''---From A Chinese Restaurant 
         Fortune Cookie, 01/26/01

\beginchapterquote{``Simplicity of character is the natural result
                   of profound thought.''}
                   {From A Chinese Restaurant fortune cookie, 01/26/01}

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

\emph{The Iju Tool Set} includes a number of DOS console-mode utilities.
Although these utilities present a humble interface (text-only input and output),
some are very powerful.  Because the internal architecture of the
\index{Microsoft \emph{Windows}@Microsoft Windows}\emph{Windows} family of
operating systems has changed over the years so that DOS console-mode
applications now use the Win32 memory model, these applications can now
allocate at least hundreds of megabytes of memory and are generally unfettered
in their operation.  Despite the humble interface, console-mode applications
can now be very powerful indeed.

Many of these utilities are very similar to---and sometimes use the
same software components as---Tcl/Tk extensions that perform the same
functions.

The first part of this chapter describes command-line option formats which
are common across more than one utility.  The second part of the chapter describes
each of the utilities in detail.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Notational Conventions}
%Subsection tag: NCO0
\label{ctin0:sccl0:snco0}

We use the angle brackets (`\texttt{<}' and `\texttt{>}') to denote a 
parameter which must occur and be completed with the information
indicated.  For example, we would use \texttt{<winfname>} to indicate
that the name of a file must be provided in a format acceptable to 
Windows.

We use the square brackets (`\texttt{[}' and `\texttt{]}') to denote
an optional parameter.  Square brackets may be nested arbitrarily
deep---for example, `\texttt{[lastname [firstname]]}' would 
indicate that both first name and last name may be omitted, but
the first name may not occur alone without the last name.

In all cases, the parameter types described in Section
\ctinzeroxrefhyphen{}\ref{ctin0:sccl0}
are used.

In some cases it may be necessary to distinguish between the 
\emph{name} of a parameter and the \emph{type} of the parameter.
For example, two parameters may both be of type \texttt{uint32} 
but may serve different functions---one may be, for example,
a dividend and the other a divisor.  In these cases we use
the underscore character (`\texttt{\_}') to separate
the name and the type.  For example, in such a case we may
use a description such as \texttt{divisor\_uint32}.

\subsection{The \texttt{-help} Option}
%Subsection tag: hel0
\label{cdcm0:sccl0:shel0}

\index{help@\texttt{-help}}
\index{-help@\texttt{-help}}
The command-line option \texttt{-help} (which must be used alone with no
other parameters) will cause a full set of help information to be written
to the standard output stream.

Any command line which is not recognized (i.e. that contains no parameters or is
otherwise invalid) will cause a message to be displayed to the effect that
the utility may be re-run with the \texttt{-help} parameter to obtain help
information.

\subsection{The \texttt{-verbose} And \texttt{-debug} Options}
%Subsection tag: ver0
\label{cdcm0:sccl0:sver0}

\index{verbose@\texttt{-verbose}}
\index{-verbose@\texttt{-verbose}}
\index{debug@\texttt{-debug}}
\index{-debug@\texttt{-debug}}
The command-line option \texttt{-verbose} will cause intermediate results and other
useful information to be written to the standard output as the utility runs.
Because it is very often
used, the \texttt{-verbose} option
can always be abbreviated \texttt{-v}.
For utilities which perform arithmetic, these intermediate results may be useful
in verifying hand calculations or for other purposes.

The \texttt{-debug} option will cause debugging information to be written to 
the standard output.  Because the \texttt{-debug} option is very rarely used,
it does not have an abbreviated form.  The debugging information consists of 
information that may be useful in diagnosing the internal problem if a utility
ever is found to contain a software defect.

The \texttt{-verbose} and \texttt{-debug} options are potentially orthogonal.
The information output enabled by the \texttt{-verbose} option may be different
than the information output enabled by the \texttt{-debug} option.  The options
may be used together.

\subsection{The \texttt{-noformat} Option}
%Subsection tag: nfo0
\label{cdcm0:sccl0:snfo0}

\index{noformat@\texttt{-noformat}}
\index{-noformat@\texttt{-noformat}}
The command-line option \texttt{-noformat} will cause formatting of the output to be
suppressed.  Because it is very often used, this option can always be abbreviated
\texttt{-nf}.

Normally, each command will format the output to be very aesthetic and
human-readable.  This involves adding commas and comments and splitting
long integers across multiple lines.  However, when piping data from one
utility to another or spawning these utilities from a script or other program,
it may be desirable to suppress all but the output data.

The \texttt{-verbose} and \texttt{-debug} options override (i.e. cancel)
the \texttt{-noformat} option.  The \texttt{-noformat} option will not be
honored if it appears on the same command line as the 
\texttt{-verbose} option or the \texttt{-debug} option.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Invocation Of The Utilities}
%Section tag: INV0

The most common way to invoke any of these command-line utilities is
to open a console box (in Windows), and then to run these utilities
from the command line or from a batch file.

These utilities could also be run from a Tcl/Tk script, or spawned from
a Windows application.

These utilities do not write to the standard error stream (only to the
standard output), so output can always be redirected.

These utilities will generate a return code of 0 if no errors are detected, or
a return code of 4 if any errors are detected.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{File CRC And Hash Function Utilities}
%Section tag: CHF0
\label{cdcm0:schf0}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{crc32} Utility}
%Subection tag: CRC0
\label{cdcm0:schf0:scrc0}

\index{crc32@\emph{crc32}}
\begin{dosutilcommandname}{crc32}%
calculates the CRC-32 and file size (in bytes) of a file.
The CRC-32 is written to the standard output in hexadecimal
notation, and the file size is written to the standard output
in decimal notation with commas.
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{crc32}{winfname [$<$options$>$]}
\dosutilcommandsynopsisline{crc32}{-help}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{crc32} utility calculates the CRC-32 and length of a file.
This utility relies on C-language code obtained from a web page
maintained by \index{Ellingson, Richard A.}Richard A. Ellingson 
\cite{bibref:w:ellingsoncrc32pages}.
The utility was checked against the values calculated by 
\index{WinZip@\emph{WinZip}}\emph{WinZip}
\cite{bibref:s:winzip}.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>crc32 t1.bin
0x9567CF44 (116,785,153)

C:\>crc32 t1.bin -noformat
9567CF44
116785153
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{crc32} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:scrc0:scrc0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Arbitrary-Length Integer Utilities}
%Section tag: ALI0
\label{cdcm0:sali0}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{intadd} Utility}
%Subection tag: ADD0
\label{cdcm0:sali0:sadd0}

\index{intadd@\emph{intadd}}
\begin{dosutilcommandname}{intadd}%
adds two integers.  (Mnemonic:  \emph{int}eger
\emph{add}ition.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{intadd}{sint sint [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{intadd} utility calculates the sum of two integers.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>intadd 1e20 4912471263493214
------------------------------------------------------------------------------
                arg1:           100,000,000,000,000,000,000   (     21 digits)
------------------------------------------------------------------------------
                arg2:                 4,912,471,263,493,214   (     16 digits)
------------------------------------------------------------------------------
         arg1 + arg2:           100,004,912,471,263,493,214   (     21 digits)
------------------------------------------------------------------------------
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint intadd} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sadd0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{intsub} Utility}
%Subection tag: SUB0
\label{cdcm0:sali0:ssub0}

\index{intsub@\emph{intsub}}
\begin{dosutilcommandname}{intsub}%
subtracts two integers.  (Mnemonic:  \emph{int}eger
\emph{sub}traction.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{intsub}{sint sint [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{intsub} utility calculates the difference of two integers.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>intsub 1e110 99
------------------------------------------------------------------------------
                arg1:                                   100,  (    111 digits)
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000
------------------------------------------------------------------------------
                arg2:                                    99   (      2 digits)
------------------------------------------------------------------------------
         arg1 - arg2:                                    99,  (    110 digits)
                        999,999,999,999,999,999,999,999,999,
                        999,999,999,999,999,999,999,999,999,
                        999,999,999,999,999,999,999,999,999,
                        999,999,999,999,999,999,999,999,901
------------------------------------------------------------------------------

C:\>intsub 1e110 99 -nf
10000000000000000000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000
99
99999999999999999999999999999999999999999999999999999999999999999999999999999999
999999999999999999999999999901
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint intsub} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:ssub0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{intmul} Utility}
%Subsection tag: MUL0
\label{cdcm0:sali0:smul0}

\index{intmul@\emph{intmul}}
\begin{dosutilcommandname}{intmul}%
calculates the product of
two integers.  (Mnemonic:  \emph{int}eger
\emph{mul}tiplication.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{intmul}{sint sint [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{intmul} utility calculates product of two 
integers.
\end{dosutilcommanddescription}


\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>intmul -916439216486321439672164132964 4321846.2864e28
------------------------------------------------------------------------------
                arg1: -                                 916,  (     30 digits)
                        439,216,486,321,439,672,164,132,964
------------------------------------------------------------------------------
                arg2:                            43,218,462,  (     35 digits)
                        864,000,000,000,000,000,000,000,000
------------------------------------------------------------------------------
         arg1 * arg2: -                      39,607,094,244,  (     65 digits)
                        827,339,704,438,441,915,017,392,248,
                        896,000,000,000,000,000,000,000,000
------------------------------------------------------------------------------

C:\>intmul -916439216486321439672164132964 4321846.2864e28 -nf
-916439216486321439672164132964
43218462864000000000000000000000000
-39607094244827339704438441915017392248896000000000000000000000000
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint intmul} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:smul0}.
\end{dosutilcommandseealso}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{intdiv} Utility}
%Subsection tag: DIV0
\label{cdcm0:sali0:sdiv0}

\index{intdiv@\emph{intdiv}}
\begin{dosutilcommandname}{intdiv}%
calculates the integer quotient (i.e. without remainder) of 
two integers.
(Mnemonic:  \emph{int}eger
\emph{div}ision.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{intdiv}{sint sint [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{intdiv} utility calculates the integer quotient
of two integers.  The mapping that is made is 
more precisely described in 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sdiv0} in the
description of the \emph{arbint intdiv} Tcl extension.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>intdiv 296491826436721 91843682163
------------------------------------------------------------------------------
                arg1:                   296,491,826,436,721   (     15 digits)
------------------------------------------------------------------------------
                arg2:                        91,843,682,163   (     11 digits)
------------------------------------------------------------------------------
         arg1 / arg2:                                 3,228   (      4 digits)
------------------------------------------------------------------------------

C:\>intdiv 296491826436721 91843682163 -nf
296491826436721
91843682163
3228
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint intdiv} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sdiv0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{intmod} Utility}
%Subsection tag: MOD0
\label{cdcm0:sali0:smod0}

\index{intmod@\emph{intmod}}
\begin{dosutilcommandname}{intmod}%
calculates the integer modulo (i.e. remainder of division) of 
two integers.
(Mnemonic:  \emph{int}eger
\emph{mod}ulo.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{intmod}{sint sint [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{intmod} utility calculates the integer modulo
of two integers.  The mapping that is made is 
more precisely described in 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:smod0} in the
description of the \emph{arbint intmod} Tcl extension.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>intmod 2836549213654 15432154
------------------------------------------------------------------------------
                arg1:                     2,836,549,213,654   (     13 digits)
------------------------------------------------------------------------------
                arg2:                            15,432,154   (      8 digits)
------------------------------------------------------------------------------
         arg1 % arg2:                            11,283,376   (      8 digits)
------------------------------------------------------------------------------

C:\>intmod 2836549213654 0
------------------------------------------------------------------------------
                arg1:                     2,836,549,213,654   (     13 digits)
------------------------------------------------------------------------------
                arg2:                                     0   (      1 digit )
------------------------------------------------------------------------------
         arg1 % arg2:                GMP_INTS_EF_INTOVF_POS
------------------------------------------------------------------------------

C:\>intmod 2836549213654 0 -nf
2836549213654
0
GMP_INTS_EF_INTOVF_POS
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint intmod} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:smod0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{intgcd} Utility}
%Subsection tag: GCD0
\label{cdcm0:sali0:sgcd0}

\index{intgcd@\emph{intgcd}}
\begin{dosutilcommandname}{intgcd}%
calculates the g.c.d. of two arbitrary integers using
Euclid's algorithm.  (Mnemonic:  \emph{int}eger
\emph{g}reatest \emph{c}ommon \emph{d}ivisor.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{intgcd}{sint\_1 sint\_2 [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{intgcd} utility calculates the g.c.d. of two
integers.

If either or both integers are 0, the result will be 1.
If either or both integers are negative, the absolute 
value of the negative argument(s) will be used in the
calculation of the g.c.d.

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

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>intgcd 8326413249250 12935482154386850
------------------------------------------------------------------------------
                arg1:                     8,326,413,249,250   (     13 digits)
------------------------------------------------------------------------------
                arg2:                12,935,482,154,386,850   (     17 digits)
------------------------------------------------------------------------------
     gcd(arg1, arg2):                                    50   (      2 digits)
------------------------------------------------------------------------------

C:\>intgcd 8326413249250 12935482154386850 -nf
8326413249250
12935482154386850
50
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint intgcd} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sgcd0}.
\end{dosutilcommandseealso}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{intlcm} Utility}
%Subsection tag: LCM0
\label{cdcm0:sali0:slcm0}

\index{intlcm@\emph{intlcm}}
\begin{dosutilcommandname}{intlcm}%
calculates the l.c.m. (least common multiple)
of two integers.  (Mnemonic:  \emph{int}eger
\emph{l}east \emph{c}ommon \emph{m}ultiple.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{intlcm}{sint\_1 sint\_2 [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{intlcm} utility calculates the l.c.m. of two
integers.

The mapping from arguments to output and the details
of how the l.c.m. is calculated are described
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:slcm0}.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>intlcm 12 69
------------------------------------------------------------------------------
                arg1:                                    12   (      2 digits)
------------------------------------------------------------------------------
                arg2:                                    69   (      2 digits)
------------------------------------------------------------------------------
     lcm(arg1, arg2):                                   276   (      3 digits)
------------------------------------------------------------------------------
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint intlcm} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:slcm0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{intexp} Utility}
%Subsection tag: IXP0
\label{cdcm0:sali0:sixp0}

\index{intexp@\emph{intexp}}
\begin{dosutilcommandname}{intexp}%
exponentiates a signed integer to a non-negative integer
power.  (Mnemonic:  \emph{int}eger
\emph{exp}onent.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{intexp}{sint\_base uint32\_exponent [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{intexp} utility exponentiates an integer to a non-negative
integer power.  For convenience and simplicity, $0^0$ produces 1,
which is inconsistent with the mathematical definition; but all other
exponentiations are as expected.  The mapping is more precisely described
with the \emph{arbint intexp} Tcl extension in 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sixp0}.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>intexp -22 41
------------------------------------------------------------------------------
                base: -                                  22   (      2 digits)
------------------------------------------------------------------------------
            exponent:                                    41   (      2 digits)
------------------------------------------------------------------------------
    base ** exponent: -                                  10,  (     56 digits)
                        947,877,107,572,929,152,919,737,180,
                        202,022,857,988,400,441,953,615,872
------------------------------------------------------------------------------

C:\>intexp -22 41 -nf
-22
41
-10947877107572929152919737180202022857988400441953615872
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint intexp} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sixp0}.
\end{dosutilcommandseealso}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{intfac} Utility}
%Subsection tag: IFC0
\label{cdcm0:sali0:sifc0}

\index{intfac@\emph{intfac}}
\begin{dosutilcommandname}{intfac}%
calculates the \index{factorial function}factorial of a non-negative
integer.  (Mnemonic:  \emph{int}eger
\emph{fac}torial.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{intfac}{uint32 [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{intfac} utility calculates the factorial of 
a non-negative integer.  0! is defined to be 1.

This utility is useful for calculating the factorial of 
integers where the result would be quite large (larger than
could be displayed on a pocket calculator, for example).
\end{dosutilcommanddescription}

\begin{dosutilcommandremarks}
At the present time (07/2001, Version 1.04), the \emph{intfac} utility
is constrained by the division operations required to convert from the
binary internal integer format to a base-10 ASCII representation.
The \emph{intfac} utility will not calculate factorials of over about
1,000 decimal digits without a fair delay.  In the future, algorithmic
improvements may raise this limit.
\end{dosutilcommandremarks}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>intfac 47
------------------------------------------------------------------------------
                 arg:                                    47   (      2 digits)
------------------------------------------------------------------------------
                arg!:                               258,623,  (     60 digits)
                        241,511,168,180,642,964,355,153,611,
                        979,969,197,632,389,120,000,000,000
------------------------------------------------------------------------------

C:\>intfac 47 -noformat
47
258623241511168180642964355153611979969197632389120000000000
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint intfac} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sfac0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Rational Number Arithmetic Utilities}
%Section tag: RNU0
\label{cdcm0:srnu0}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{rnadd} Utility}
%Subsection tag: RNA0
\label{cdcm0:srnu0:srna0}

\index{rnadd@\emph{rnadd}}
\begin{dosutilcommandname}{rnadd}%
adds two rational numbers to produce a normalized rational result.  
(Mnemonic:  \emph{r}ational \emph{n}umber
\emph{add}ition.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{rnadd}{srn srn [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{rnadd} utility calculates the sum of two arbitrary
rational numbers.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>rnadd 3.29 42/67
------------------------------------------------------------------------------
            arg1_num:                                   329   (      3 digits)
------------------------------------------------------------------------------
            arg1_den:                                   100   (      3 digits)
------------------------------------------------------------------------------
            arg2_num:                                    42   (      2 digits)
------------------------------------------------------------------------------
            arg2_den:                                    67   (      2 digits)
------------------------------------------------------------------------------
          result_num:                                26,243   (      5 digits)
------------------------------------------------------------------------------
          result_den:                                 6,700   (      4 digits)
------------------------------------------------------------------------------
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint rnadd} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:srne0:srad0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{rnsub} Utility}
%Subsection tag: RSB0
\label{cdcm0:srnu0:srsb0}

\index{rnsub@\emph{rnsub}}
\begin{dosutilcommandname}{rnsub}%
subtracts two rational numbers to produce a normalized rational result.  
(Mnemonic:  \emph{r}ational \emph{n}umber
\emph{sub}traction.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{rnsub}{srn srn [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{rnsub} utility calculates the difference of two arbitrary
rational numbers.  The second argument is subtracted from the first,
i.e. $arg_2 - arg_1$ is calculated.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>rnsub 3.29 42/67
------------------------------------------------------------------------------
            arg1_num:                                   329   (      3 digits)
------------------------------------------------------------------------------
            arg1_den:                                   100   (      3 digits)
------------------------------------------------------------------------------
            arg2_num:                                    42   (      2 digits)
------------------------------------------------------------------------------
            arg2_den:                                    67   (      2 digits)
------------------------------------------------------------------------------
          result_num:                                17,843   (      5 digits)
------------------------------------------------------------------------------
          result_den:                                 6,700   (      4 digits)
------------------------------------------------------------------------------
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint rnsub} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:srne0:srsb0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{rnmul} Utility}
%Subsection tag: RMU0
\label{cdcm0:srnu0:srmu0}

\index{rnmul@\emph{rnmul}}
\begin{dosutilcommandname}{rnmul}%
calculates the product of two rational numbers.
(Mnemonic:  \emph{r}ational
\emph{n}umber \emph{mul}tiplication.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{rnmul}{srn srn [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{rnmul} utility calculates the product
of two rational numbers.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
E:\>rnmul 3.14 64/207
------------------------------------------------------------------------------
            arg1_num:                                   314   (      3 digits)
------------------------------------------------------------------------------
            arg1_den:                                   100   (      3 digits)
------------------------------------------------------------------------------
            arg2_num:                                    64   (      2 digits)
------------------------------------------------------------------------------
            arg2_den:                                   207   (      3 digits)
------------------------------------------------------------------------------
          result_num:                                 5,024   (      4 digits)
------------------------------------------------------------------------------
          result_den:                                 5,175   (      4 digits)
------------------------------------------------------------------------------
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint rnmul} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:srne0:srmu0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{rndiv} Utility}
%Subsection tag: RDV0
\label{cdcm0:srnu0:srdv0}

\index{rndiv@\emph{rndiv}}
\begin{dosutilcommandname}{rndiv}%
calculates the quotient of two rational numbers.
(Mnemonic:  \emph{r}ational
\emph{n}umber \emph{div}ision.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{rndiv}{srn srn [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{rnmul} utility calculates the quotient
of two rational numbers.  The first argument is divided
by the second; i.e. the quotient $arg_1 / arg_2$ is calculated.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
E:\>rndiv 3.14 34/291
------------------------------------------------------------------------------
            arg1_num:                                   314   (      3 digits)
------------------------------------------------------------------------------
            arg1_den:                                   100   (      3 digits)
------------------------------------------------------------------------------
            arg2_num:                                    34   (      2 digits)
------------------------------------------------------------------------------
            arg2_den:                                   291   (      3 digits)
------------------------------------------------------------------------------
          result_num:                                45,687   (      5 digits)
------------------------------------------------------------------------------
          result_den:                                 1,700   (      4 digits)
------------------------------------------------------------------------------
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint rndiv} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:srne0:srdv0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{rndeq} Utility}
%Subsection tag: RNQ0
\label{cdcm0:srnu0:srnq0}

\index{rndeq@\emph{rndeq}}
\begin{dosutilcommandname}{rndeq}%
calculates the decimal equivalent of a rational number.
(Mnemonic:  \emph{r}ational \emph{n}umber
\emph{d}ecimal \emph{eq}uivalent.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{rndeq}{srn [$<$options$>$]}
\dosutilcommandsynopsisline{rndeq}{srn uint [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{rndeq} utility calculates the decimal equivalent
of a rational number using a large integer
algorithm.

Let $a/b$ be a rational number that we wish to express
as a decimal number, let $N$ be an integral power
of 10, and let $x$ be an integer chosen so that $x/N$
is an approximation to $a/b$.

If we choose

\begin{equation}
\label{eq:cdcm0:sali0:srnq0:01}
x = sgn \left( {\frac{a}{b}} \right)
\left\lfloor {\left| \frac{a}{b} \right| N} \right\rfloor ,
\end{equation}

it can be shown that

\begin{equation}
\label{eq:cdcm0:sali0:srnq0:02}
\left| {\frac{a}{b}} \right| - \frac{1}{N}
<
\frac{\left\lfloor {\left| {\frac{a}{b}} \right| N} \right\rfloor}{N}
\leq
\left|{\frac{a}{b}}\right|.
\end{equation}

In other words, the result if $x$ is chosen as specified in
(\ref{eq:cdcm0:sali0:srnq0:01}), $x/N$ will be at or up to one numerator
count less in magnitude than $a/b$.  Stated differently,
$x/N$ is ``truncated down'' in magnitude.

The \emph{rndeq} utility performs the mapping implied by 
(\ref{eq:cdcm0:sali0:srnq0:01}) and
(\ref{eq:cdcm0:sali0:srnq0:02}), by default using
$N=10^{108}$.  The value of $N=10^{108}$ was chosen
because it produces an attractive display format at
27 digits per line, and also places the imaginary decimal
point between lines so it is easier to interpret the output of
this utility.  An example is interpreted in the sample invocations
below.

This utility will accept an optional second parameter, which
is a value of $N$ to override the default of $10^{108}$.  This
optional second parameter can be used to provide more decimal places,
or to provide a different type of mapping.\footnote{Please be aware that integers
may be specified using scientific notation.  For example, to effectively double 
the number of decimal places displayed by \texttt{rndeq} in the 
invocation example below, one might enter the command line
\texttt{rndeq 5345/319 1e216}.  We would regret it if this fact were unknown
and some desperate user were to enter the digit ``1'' followed by
216 zeros!}

It is not required that the second parameter, if supplied, be a power of
10---the mappings described by the equations above will be carried
out with \emph{any} supplied denominator.  
However, it is not intuitively obvious how this utility would be
useful with a denominator that is not a power of 10.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>rndeq 5345/319
------------------------------------------------------------------------------
             arg_num:                                 5,345   (      4 digits)
------------------------------------------------------------------------------
             arg_den:                                   319   (      3 digits)
------------------------------------------------------------------------------
             dap_num:                                    16,  (    110 digits)
                        755,485,893,416,927,899,686,520,376,
                        175,548,589,341,692,789,968,652,037,
                        617,554,858,934,169,278,996,865,203,
                        761,755,485,893,416,927,899,686,520
------------------------------------------------------------------------------
             dap_den:                                     1,  (    109 digits)
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000
------------------------------------------------------------------------------
\end{verbatim}
\end{scriptsize}

It can be seen from the sample invocation above that 
5345/319$\approx$16.755---note how the imaginary decimal point is placed
between lines of \texttt{dap\_num}.  It can also be seen that the
decimal representation repeats, i.e.

\begin{equation}
\frac{5345}{319} = 16.\overline{7554858934169278996865203761}.
\end{equation}
\end{dosutilcommandsampleinvocations}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{rnred} Utility}
%Subsection tag: RNR0
\label{cdcm0:srnu0:srnr0}

\index{rnred@\emph{rnred}}
\begin{dosutilcommandname}{rnred}%
reduces a rational number to lowest terms and normalizes it.
(Mnemonic:  \emph{r}ational
\emph{n}umber \emph{red}uce and normalize.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{rnred}{srn [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{rnred} reduces a rational number to its lowest terms
and normalizes it.  This process is the same process
described in the description of the \emph{arbint rnred} Tcl
extension, Section \cxtnzeroxrefhyphen{}\ref{cxtn0:srne0:srnr0}.
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>rnred 422.414
------------------------------------------------------------------------------
           numerator:                               211,207   (      6 digits)
------------------------------------------------------------------------------
         denominator:                                   500   (      3 digits)
------------------------------------------------------------------------------

C:\>rnred 422.414 -nf
211207
500
\end{verbatim}
\end{scriptsize}
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint rnred} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:srne0:srnr0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section[Number Theory, CF, And Approximation Utilities]
        {Number Theory, Continued Fraction, And Best Rational Approximation
         Utilities}
%Section tag: nth0
\label{cdcm0:snth0}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{cfratnum} Utility}
%Subsection tag: CFR0
\label{cdcm0:snth0:scfr0}

\index{cfratnum@\emph{cfratnum}}
\begin{dosutilcommandname}{cfratnum}%
calculates the continued fraction partial quotients and convergents
of a non-negative rational number.  (Mnemonic:  \emph{c}ontinued
\emph{f}raction partial quotients and convergents of
a \emph{rat}ional \emph{num}ber.)
\end{dosutilcommandname}

\begin{dosutilcommandsynopsis}
\dosutilcommandsynopsisline{cfratnum}{urn [$<$options$>$]}
\end{dosutilcommandsynopsis}

\begin{dosutilcommanddescription}
The \emph{cfratnum} utility calculates the continued fraction
partial quotients and convergents of a non-negative rational number.
This information can be useful in a variety of contexts, including
finding best rational approximations.

Additionally, this DOS utility provides a decimal approximation
of each convergent, using a denominator of 
$10^{108}$ (see the description of the \emph{rndeq} utility, Section 
\ref{cdcm0:srnu0:srnq0}).
\end{dosutilcommanddescription}

\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\>cfratnum 3.14
******************************************************************************
*******************   Continued Fraction Representation    *******************
******************************************************************************
     Input Numerator:                                   314   (      3 digits)
------------------------------------------------------------------------------
   Input Denominator:                                   100   (      3 digits)
------------------------------------------------------------------------------
         dividend(0):                                   314   (      3 digits)
------------------------------------------------------------------------------
          divisor(0):                                   100   (      3 digits)
------------------------------------------------------------------------------
                a(0):                                     3   (      1 digit )
------------------------------------------------------------------------------
                p(0):                                     3   (      1 digit )
------------------------------------------------------------------------------
                q(0):                                     1   (      1 digit )
------------------------------------------------------------------------------
            dap_h(0):                                     3,  (    109 digits)
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000
------------------------------------------------------------------------------
            dap_k(0):                                     1,  (    109 digits)
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000
------------------------------------------------------------------------------
         dividend(1):                                   100   (      3 digits)
------------------------------------------------------------------------------
          divisor(1):                                    14   (      2 digits)
------------------------------------------------------------------------------
                a(1):                                     7   (      1 digit )
------------------------------------------------------------------------------
                p(1):                                    22   (      2 digits)
------------------------------------------------------------------------------
                q(1):                                     7   (      1 digit )
------------------------------------------------------------------------------
            dap_h(1):                                     3,  (    109 digits)
                        142,857,142,857,142,857,142,857,142,
                        857,142,857,142,857,142,857,142,857,
                        142,857,142,857,142,857,142,857,142,
                        857,142,857,142,857,142,857,142,857
------------------------------------------------------------------------------
            dap_k(1):                                     1,  (    109 digits)
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000
------------------------------------------------------------------------------
         dividend(2):                                    14   (      2 digits)
------------------------------------------------------------------------------
          divisor(2):                                     2   (      1 digit )
------------------------------------------------------------------------------
                a(2):                                     7   (      1 digit )
------------------------------------------------------------------------------
                p(2):                                   157   (      3 digits)
------------------------------------------------------------------------------
                q(2):                                    50   (      2 digits)
------------------------------------------------------------------------------
            dap_h(2):                                     3,  (    109 digits)
                        140,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000
------------------------------------------------------------------------------
            dap_k(2):                                     1,  (    109 digits)
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000
------------------------------------------------------------------------------
\end{verbatim}
\end{scriptsize}

Note in the sample invocation above that each convergent
also includes a decimal approximation.  For example,
in the invocation above, it can be seen that 
22/7 $\approx$ 3.142857142857 \ldots{}.

Note also that at each round of calculation of partial
quotients and convergents, the remainder is not shown because
it becomes the divisor of the next round, and so it would be
redundant to show it.  Note also that the final non-zero remainder
(which is the g.c.d. of the numerator and denominator) 
appears as the final divisor.  In the sample
invocation above, it can be seen that the g.c.d. of
314 and 100 is the integer labeled as 
\texttt{divisor(2)}, which has the value of 2.
\end{dosutilcommandsampleinvocations}

\begin{dosutilcommandseealso}
See also the \emph{arbint cfratnum} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:snth0:scfr0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{The \emph{cfbrapab} Utility}
%Subsection tag: BRA0
\label{cdcm0:snth0:sbra0}

\index{cfbrapab@\emph{cfbrapab}}
\begin{dosutilcommandname}{cfbrapab}%
calculates the best rational approximation to a
rational
number in the Farey series of order
$k_{MAX}$, or in a rectangular region of the integer lattice
defined by $k \leq k_{MAX}$ and $h \leq h_{MAX}$.
(Mnemonic:  \emph{c}ontinued
\emph{f}raction \emph{b}est \emph{r}ational \emph{ap}proximation
in $F_{a, \overline{b}}$.)
\end{dosutilcommandname}

\begin{dosutilcommanddescription}
Except for display format,
this utility behaves the same way and
accepts the same options as the \emph{arbint cfbrapab}
Tcl extension, described in Section \cxtnzeroxrefhyphen{}\ref{cxtn0:snth0:sbra0}.
Please see the documentation of this Tcl extension, which also applies
to this DOS command-line utility.
\end{dosutilcommanddescription}


\begin{dosutilcommandsampleinvocations}
\begin{scriptsize}
\begin{verbatim}
C:\swprojs\cfbrapab\Release>cfbrapab 1.6093 255 255
------------------------------------------------------------------------------
MAJOR MODE:  Finding closest rational number(s) under the constraints.
------------------------------------------------------------------------------
   RI_IN   Numerator:                                16,093   (      5 digits)
------------------------------------------------------------------------------
   RI_IN Denominator:                                10,000   (      5 digits)
------------------------------------------------------------------------------
               K_MAX:                                   255   (      3 digits)
------------------------------------------------------------------------------
               H_MAX:                                   255   (      3 digits)
------------------------------------------------------------------------------
      approx_num(-1):                                   243   (      3 digits)
------------------------------------------------------------------------------
      approx_den(-1):                                   151   (      3 digits)
------------------------------------------------------------------------------
         dap_num(-1):                                     1,  (    109 digits)
                        609,271,523,178,807,947,019,867,549,
                        668,874,172,185,430,463,576,158,940,
                        397,350,993,377,483,443,708,609,271,
                        523,178,807,947,019,867,549,668,874
------------------------------------------------------------------------------
         dap_den(-1):                                     1,  (    109 digits)
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000,
                        000,000,000,000,000,000,000,000,000
------------------------------------------------------------------------------
       error_num(-1): -                                  43   (      2 digits)
------------------------------------------------------------------------------
       error_den(-1):                             1,510,000   (      7 digits)
------------------------------------------------------------------------------
\end{verbatim}
\end{scriptsize}

Note in the sample invocation above that the 
decimal equivalent of the approximation is also provided.
Note also that the different parameters of this utility produce
different output formats which are not documented here, for
brevity.  For example, using the \texttt{-pred} or \texttt{-succ}
options does not produce decimal approximation information, because
these options are not normally used for approximation---such
behaviors are inconsequential and not documented.
\end{dosutilcommandsampleinvocations}


\begin{dosutilcommandseealso}
This extension uses the continued fraction
algorithms presented in Chapter \ccfrzeroxrefhyphen{}\ref{ccfr0}.
See also the \emph{arbint cfbrapab} Tcl extension, 
Section \cxtnzeroxrefhyphen{}\ref{cxtn0:snth0:sbra0}.
\end{dosutilcommandseealso}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Authors And Acknowledgements}
%Section tag: ACK0


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Exercises}
%Section tag: EXE0


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\noindent\begin{figure}[!b]
\noindent\rule[-0.25in]{\textwidth}{1pt}
\begin{tiny}
\begin{verbatim}
$HeadURL$
$Revision$
$Date$
$Author$
\end{verbatim}
\end{tiny}
\noindent\rule[0.25in]{\textwidth}{1pt}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%End of file C_DCM0.TEX
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision URL Header