%$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{} 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