/[dtapublic]/pubs/books/ucbka/trunk/c_dcm0/c_dcm0.tex
ViewVC logotype

Annotation of /pubs/books/ucbka/trunk/c_dcm0/c_dcm0.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4 - (hide annotations) (download) (as text)
Thu Oct 6 03:15:02 2016 UTC (8 years ago) by dashley
File MIME type: application/x-tex
File size: 60159 byte(s)
Initial commit after migrating from CVS.
1 dashley 4 %$Header: /home/dashley/cvsrep/e3ft_gpl01/e3ft_gpl01/dtaipubs/esrgubka/c_dcm0/c_dcm0.tex,v 1.13 2001/08/18 18:37:56 dtashley Exp $
2    
3     \chapter{\cdcmzerolongtitle{}}
4    
5     \label{cdcm0}
6    
7    
8     `''---From A Chinese Restaurant
9     Fortune Cookie, 01/26/01
10    
11     \beginchapterquote{``Simplicity of character is the natural result
12     of profound thought.''}
13     {From A Chinese Restaurant fortune cookie, 01/26/01}
14    
15     \section{Introduction}
16     %Section Tag: INT0
17     \label{cdcm0:sint0}
18    
19     \emph{The Iju Tool Set} includes a number of DOS console-mode utilities.
20     Although these utilities present a humble interface (text-only input and output),
21     some are very powerful. Because the internal architecture of the
22     \index{Microsoft \emph{Windows}@Microsoft Windows}\emph{Windows} family of
23     operating systems has changed over the years so that DOS console-mode
24     applications now use the Win32 memory model, these applications can now
25     allocate at least hundreds of megabytes of memory and are generally unfettered
26     in their operation. Despite the humble interface, console-mode applications
27     can now be very powerful indeed.
28    
29     Many of these utilities are very similar to---and sometimes use the
30     same software components as---Tcl/Tk extensions that perform the same
31     functions.
32    
33     The first part of this chapter describes command-line option formats which
34     are common across more than one utility. The second part of the chapter describes
35     each of the utilities in detail.
36    
37    
38     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
39     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
40     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
41    
42     \subsection{Notational Conventions}
43     %Subsection tag: NCO0
44     \label{ctin0:sccl0:snco0}
45    
46     We use the angle brackets (`\texttt{<}' and `\texttt{>}') to denote a
47     parameter which must occur and be completed with the information
48     indicated. For example, we would use \texttt{<winfname>} to indicate
49     that the name of a file must be provided in a format acceptable to
50     Windows.
51    
52     We use the square brackets (`\texttt{[}' and `\texttt{]}') to denote
53     an optional parameter. Square brackets may be nested arbitrarily
54     deep---for example, `\texttt{[lastname [firstname]]}' would
55     indicate that both first name and last name may be omitted, but
56     the first name may not occur alone without the last name.
57    
58     In all cases, the parameter types described in Section
59     \ctinzeroxrefhyphen{}\ref{ctin0:sccl0}
60     are used.
61    
62     In some cases it may be necessary to distinguish between the
63     \emph{name} of a parameter and the \emph{type} of the parameter.
64     For example, two parameters may both be of type \texttt{uint32}
65     but may serve different functions---one may be, for example,
66     a dividend and the other a divisor. In these cases we use
67     the underscore character (`\texttt{\_}') to separate
68     the name and the type. For example, in such a case we may
69     use a description such as \texttt{divisor\_uint32}.
70    
71     \subsection{The \texttt{-help} Option}
72     %Subsection tag: hel0
73     \label{cdcm0:sccl0:shel0}
74    
75     \index{help@\texttt{-help}}
76     \index{-help@\texttt{-help}}
77     The command-line option \texttt{-help} (which must be used alone with no
78     other parameters) will cause a full set of help information to be written
79     to the standard output stream.
80    
81     Any command line which is not recognized (i.e. that contains no parameters or is
82     otherwise invalid) will cause a message to be displayed to the effect that
83     the utility may be re-run with the \texttt{-help} parameter to obtain help
84     information.
85    
86     \subsection{The \texttt{-verbose} And \texttt{-debug} Options}
87     %Subsection tag: ver0
88     \label{cdcm0:sccl0:sver0}
89    
90     \index{verbose@\texttt{-verbose}}
91     \index{-verbose@\texttt{-verbose}}
92     \index{debug@\texttt{-debug}}
93     \index{-debug@\texttt{-debug}}
94     The command-line option \texttt{-verbose} will cause intermediate results and other
95     useful information to be written to the standard output as the utility runs.
96     Because it is very often
97     used, the \texttt{-verbose} option
98     can always be abbreviated \texttt{-v}.
99     For utilities which perform arithmetic, these intermediate results may be useful
100     in verifying hand calculations or for other purposes.
101    
102     The \texttt{-debug} option will cause debugging information to be written to
103     the standard output. Because the \texttt{-debug} option is very rarely used,
104     it does not have an abbreviated form. The debugging information consists of
105     information that may be useful in diagnosing the internal problem if a utility
106     ever is found to contain a software defect.
107    
108     The \texttt{-verbose} and \texttt{-debug} options are potentially orthogonal.
109     The information output enabled by the \texttt{-verbose} option may be different
110     than the information output enabled by the \texttt{-debug} option. The options
111     may be used together.
112    
113     \subsection{The \texttt{-noformat} Option}
114     %Subsection tag: nfo0
115     \label{cdcm0:sccl0:snfo0}
116    
117     \index{noformat@\texttt{-noformat}}
118     \index{-noformat@\texttt{-noformat}}
119     The command-line option \texttt{-noformat} will cause formatting of the output to be
120     suppressed. Because it is very often used, this option can always be abbreviated
121     \texttt{-nf}.
122    
123     Normally, each command will format the output to be very aesthetic and
124     human-readable. This involves adding commas and comments and splitting
125     long integers across multiple lines. However, when piping data from one
126     utility to another or spawning these utilities from a script or other program,
127     it may be desirable to suppress all but the output data.
128    
129     The \texttt{-verbose} and \texttt{-debug} options override (i.e. cancel)
130     the \texttt{-noformat} option. The \texttt{-noformat} option will not be
131     honored if it appears on the same command line as the
132     \texttt{-verbose} option or the \texttt{-debug} option.
133    
134    
135     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
136     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
137     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
138     \section{Invocation Of The Utilities}
139     %Section tag: INV0
140    
141     The most common way to invoke any of these command-line utilities is
142     to open a console box (in Windows), and then to run these utilities
143     from the command line or from a batch file.
144    
145     These utilities could also be run from a Tcl/Tk script, or spawned from
146     a Windows application.
147    
148     These utilities do not write to the standard error stream (only to the
149     standard output), so output can always be redirected.
150    
151     These utilities will generate a return code of 0 if no errors are detected, or
152     a return code of 4 if any errors are detected.
153    
154    
155     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
156     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
157     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
158     \section{File CRC And Hash Function Utilities}
159     %Section tag: CHF0
160     \label{cdcm0:schf0}
161    
162    
163     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
164     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
165     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
166     \subsection{The \emph{crc32} Utility}
167     %Subection tag: CRC0
168     \label{cdcm0:schf0:scrc0}
169    
170     \index{crc32@\emph{crc32}}
171     \begin{dosutilcommandname}{crc32}%
172     calculates the CRC-32 and file size (in bytes) of a file.
173     The CRC-32 is written to the standard output in hexadecimal
174     notation, and the file size is written to the standard output
175     in decimal notation with commas.
176     \end{dosutilcommandname}
177    
178     \begin{dosutilcommandsynopsis}
179     \dosutilcommandsynopsisline{crc32}{winfname [$<$options$>$]}
180     \dosutilcommandsynopsisline{crc32}{-help}
181     \end{dosutilcommandsynopsis}
182    
183     \begin{dosutilcommanddescription}
184     The \emph{crc32} utility calculates the CRC-32 and length of a file.
185     This utility relies on C-language code obtained from a web page
186     maintained by \index{Ellingson, Richard A.}Richard A. Ellingson
187     \cite{bibref:w:ellingsoncrc32pages}.
188     The utility was checked against the values calculated by
189     \index{WinZip@\emph{WinZip}}\emph{WinZip}
190     \cite{bibref:s:winzip}.
191     \end{dosutilcommanddescription}
192    
193     \begin{dosutilcommandsampleinvocations}
194     \begin{scriptsize}
195     \begin{verbatim}
196     C:\>crc32 t1.bin
197     0x9567CF44 (116,785,153)
198    
199     C:\>crc32 t1.bin -noformat
200     9567CF44
201     116785153
202     \end{verbatim}
203     \end{scriptsize}
204     \end{dosutilcommandsampleinvocations}
205    
206     \begin{dosutilcommandseealso}
207     See also the \emph{crc32} Tcl extension,
208     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:scrc0:scrc0}.
209     \end{dosutilcommandseealso}
210    
211    
212     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
213     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
214     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
215     \section{Arbitrary-Length Integer Utilities}
216     %Section tag: ALI0
217     \label{cdcm0:sali0}
218    
219    
220     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
221     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
222     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
223     \subsection{The \emph{intadd} Utility}
224     %Subection tag: ADD0
225     \label{cdcm0:sali0:sadd0}
226    
227     \index{intadd@\emph{intadd}}
228     \begin{dosutilcommandname}{intadd}%
229     adds two integers. (Mnemonic: \emph{int}eger
230     \emph{add}ition.)
231     \end{dosutilcommandname}
232    
233     \begin{dosutilcommandsynopsis}
234     \dosutilcommandsynopsisline{intadd}{sint sint [$<$options$>$]}
235     \end{dosutilcommandsynopsis}
236    
237     \begin{dosutilcommanddescription}
238     The \emph{intadd} utility calculates the sum of two integers.
239     \end{dosutilcommanddescription}
240    
241     \begin{dosutilcommandsampleinvocations}
242     \begin{scriptsize}
243     \begin{verbatim}
244     C:\>intadd 1e20 4912471263493214
245     ------------------------------------------------------------------------------
246     arg1: 100,000,000,000,000,000,000 ( 21 digits)
247     ------------------------------------------------------------------------------
248     arg2: 4,912,471,263,493,214 ( 16 digits)
249     ------------------------------------------------------------------------------
250     arg1 + arg2: 100,004,912,471,263,493,214 ( 21 digits)
251     ------------------------------------------------------------------------------
252     \end{verbatim}
253     \end{scriptsize}
254     \end{dosutilcommandsampleinvocations}
255    
256     \begin{dosutilcommandseealso}
257     See also the \emph{arbint intadd} Tcl extension,
258     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sadd0}.
259     \end{dosutilcommandseealso}
260    
261    
262     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
263     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
264     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
265     \subsection{The \emph{intsub} Utility}
266     %Subection tag: SUB0
267     \label{cdcm0:sali0:ssub0}
268    
269     \index{intsub@\emph{intsub}}
270     \begin{dosutilcommandname}{intsub}%
271     subtracts two integers. (Mnemonic: \emph{int}eger
272     \emph{sub}traction.)
273     \end{dosutilcommandname}
274    
275     \begin{dosutilcommandsynopsis}
276     \dosutilcommandsynopsisline{intsub}{sint sint [$<$options$>$]}
277     \end{dosutilcommandsynopsis}
278    
279     \begin{dosutilcommanddescription}
280     The \emph{intsub} utility calculates the difference of two integers.
281     \end{dosutilcommanddescription}
282    
283     \begin{dosutilcommandsampleinvocations}
284     \begin{scriptsize}
285     \begin{verbatim}
286     C:\>intsub 1e110 99
287     ------------------------------------------------------------------------------
288     arg1: 100, ( 111 digits)
289     000,000,000,000,000,000,000,000,000,
290     000,000,000,000,000,000,000,000,000,
291     000,000,000,000,000,000,000,000,000,
292     000,000,000,000,000,000,000,000,000
293     ------------------------------------------------------------------------------
294     arg2: 99 ( 2 digits)
295     ------------------------------------------------------------------------------
296     arg1 - arg2: 99, ( 110 digits)
297     999,999,999,999,999,999,999,999,999,
298     999,999,999,999,999,999,999,999,999,
299     999,999,999,999,999,999,999,999,999,
300     999,999,999,999,999,999,999,999,901
301     ------------------------------------------------------------------------------
302    
303     C:\>intsub 1e110 99 -nf
304     10000000000000000000000000000000000000000000000000000000000000000000000000000000
305     0000000000000000000000000000000
306     99
307     99999999999999999999999999999999999999999999999999999999999999999999999999999999
308     999999999999999999999999999901
309     \end{verbatim}
310     \end{scriptsize}
311     \end{dosutilcommandsampleinvocations}
312    
313     \begin{dosutilcommandseealso}
314     See also the \emph{arbint intsub} Tcl extension,
315     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:ssub0}.
316     \end{dosutilcommandseealso}
317    
318    
319     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
320     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
321     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
322     \subsection{The \emph{intmul} Utility}
323     %Subsection tag: MUL0
324     \label{cdcm0:sali0:smul0}
325    
326     \index{intmul@\emph{intmul}}
327     \begin{dosutilcommandname}{intmul}%
328     calculates the product of
329     two integers. (Mnemonic: \emph{int}eger
330     \emph{mul}tiplication.)
331     \end{dosutilcommandname}
332    
333     \begin{dosutilcommandsynopsis}
334     \dosutilcommandsynopsisline{intmul}{sint sint [$<$options$>$]}
335     \end{dosutilcommandsynopsis}
336    
337     \begin{dosutilcommanddescription}
338     The \emph{intmul} utility calculates product of two
339     integers.
340     \end{dosutilcommanddescription}
341    
342    
343     \begin{dosutilcommandsampleinvocations}
344     \begin{scriptsize}
345     \begin{verbatim}
346     C:\>intmul -916439216486321439672164132964 4321846.2864e28
347     ------------------------------------------------------------------------------
348     arg1: - 916, ( 30 digits)
349     439,216,486,321,439,672,164,132,964
350     ------------------------------------------------------------------------------
351     arg2: 43,218,462, ( 35 digits)
352     864,000,000,000,000,000,000,000,000
353     ------------------------------------------------------------------------------
354     arg1 * arg2: - 39,607,094,244, ( 65 digits)
355     827,339,704,438,441,915,017,392,248,
356     896,000,000,000,000,000,000,000,000
357     ------------------------------------------------------------------------------
358    
359     C:\>intmul -916439216486321439672164132964 4321846.2864e28 -nf
360     -916439216486321439672164132964
361     43218462864000000000000000000000000
362     -39607094244827339704438441915017392248896000000000000000000000000
363     \end{verbatim}
364     \end{scriptsize}
365     \end{dosutilcommandsampleinvocations}
366    
367     \begin{dosutilcommandseealso}
368     See also the \emph{arbint intmul} Tcl extension,
369     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:smul0}.
370     \end{dosutilcommandseealso}
371    
372     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
373     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
374     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
375     \subsection{The \emph{intdiv} Utility}
376     %Subsection tag: DIV0
377     \label{cdcm0:sali0:sdiv0}
378    
379     \index{intdiv@\emph{intdiv}}
380     \begin{dosutilcommandname}{intdiv}%
381     calculates the integer quotient (i.e. without remainder) of
382     two integers.
383     (Mnemonic: \emph{int}eger
384     \emph{div}ision.)
385     \end{dosutilcommandname}
386    
387     \begin{dosutilcommandsynopsis}
388     \dosutilcommandsynopsisline{intdiv}{sint sint [$<$options$>$]}
389     \end{dosutilcommandsynopsis}
390    
391     \begin{dosutilcommanddescription}
392     The \emph{intdiv} utility calculates the integer quotient
393     of two integers. The mapping that is made is
394     more precisely described in
395     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sdiv0} in the
396     description of the \emph{arbint intdiv} Tcl extension.
397     \end{dosutilcommanddescription}
398    
399     \begin{dosutilcommandsampleinvocations}
400     \begin{scriptsize}
401     \begin{verbatim}
402     C:\>intdiv 296491826436721 91843682163
403     ------------------------------------------------------------------------------
404     arg1: 296,491,826,436,721 ( 15 digits)
405     ------------------------------------------------------------------------------
406     arg2: 91,843,682,163 ( 11 digits)
407     ------------------------------------------------------------------------------
408     arg1 / arg2: 3,228 ( 4 digits)
409     ------------------------------------------------------------------------------
410    
411     C:\>intdiv 296491826436721 91843682163 -nf
412     296491826436721
413     91843682163
414     3228
415     \end{verbatim}
416     \end{scriptsize}
417     \end{dosutilcommandsampleinvocations}
418    
419     \begin{dosutilcommandseealso}
420     See also the \emph{arbint intdiv} Tcl extension,
421     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sdiv0}.
422     \end{dosutilcommandseealso}
423    
424    
425     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
426     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
427     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
428     \subsection{The \emph{intmod} Utility}
429     %Subsection tag: MOD0
430     \label{cdcm0:sali0:smod0}
431    
432     \index{intmod@\emph{intmod}}
433     \begin{dosutilcommandname}{intmod}%
434     calculates the integer modulo (i.e. remainder of division) of
435     two integers.
436     (Mnemonic: \emph{int}eger
437     \emph{mod}ulo.)
438     \end{dosutilcommandname}
439    
440     \begin{dosutilcommandsynopsis}
441     \dosutilcommandsynopsisline{intmod}{sint sint [$<$options$>$]}
442     \end{dosutilcommandsynopsis}
443    
444     \begin{dosutilcommanddescription}
445     The \emph{intmod} utility calculates the integer modulo
446     of two integers. The mapping that is made is
447     more precisely described in
448     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:smod0} in the
449     description of the \emph{arbint intmod} Tcl extension.
450     \end{dosutilcommanddescription}
451    
452     \begin{dosutilcommandsampleinvocations}
453     \begin{scriptsize}
454     \begin{verbatim}
455     C:\>intmod 2836549213654 15432154
456     ------------------------------------------------------------------------------
457     arg1: 2,836,549,213,654 ( 13 digits)
458     ------------------------------------------------------------------------------
459     arg2: 15,432,154 ( 8 digits)
460     ------------------------------------------------------------------------------
461     arg1 % arg2: 11,283,376 ( 8 digits)
462     ------------------------------------------------------------------------------
463    
464     C:\>intmod 2836549213654 0
465     ------------------------------------------------------------------------------
466     arg1: 2,836,549,213,654 ( 13 digits)
467     ------------------------------------------------------------------------------
468     arg2: 0 ( 1 digit )
469     ------------------------------------------------------------------------------
470     arg1 % arg2: GMP_INTS_EF_INTOVF_POS
471     ------------------------------------------------------------------------------
472    
473     C:\>intmod 2836549213654 0 -nf
474     2836549213654
475     0
476     GMP_INTS_EF_INTOVF_POS
477     \end{verbatim}
478     \end{scriptsize}
479     \end{dosutilcommandsampleinvocations}
480    
481     \begin{dosutilcommandseealso}
482     See also the \emph{arbint intmod} Tcl extension,
483     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:smod0}.
484     \end{dosutilcommandseealso}
485    
486    
487     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
488     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
489     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
490     \subsection{The \emph{intgcd} Utility}
491     %Subsection tag: GCD0
492     \label{cdcm0:sali0:sgcd0}
493    
494     \index{intgcd@\emph{intgcd}}
495     \begin{dosutilcommandname}{intgcd}%
496     calculates the g.c.d. of two arbitrary integers using
497     Euclid's algorithm. (Mnemonic: \emph{int}eger
498     \emph{g}reatest \emph{c}ommon \emph{d}ivisor.)
499     \end{dosutilcommandname}
500    
501     \begin{dosutilcommandsynopsis}
502     \dosutilcommandsynopsisline{intgcd}{sint\_1 sint\_2 [$<$options$>$]}
503     \end{dosutilcommandsynopsis}
504    
505     \begin{dosutilcommanddescription}
506     The \emph{intgcd} utility calculates the g.c.d. of two
507     integers.
508    
509     If either or both integers are 0, the result will be 1.
510     If either or both integers are negative, the absolute
511     value of the negative argument(s) will be used in the
512     calculation of the g.c.d.
513    
514     The algorithm employed is the
515     \emph{Modern Euclidian Algorithm} as
516     described in \cite{bibref:b:knuthclassic2ndedvol2}, p. 337.
517     Although faster algorithms for computer
518     implementation do exist, this is the simplest
519     and most direct algorithm.
520     \end{dosutilcommanddescription}
521    
522     \begin{dosutilcommandsampleinvocations}
523     \begin{scriptsize}
524     \begin{verbatim}
525     C:\>intgcd 8326413249250 12935482154386850
526     ------------------------------------------------------------------------------
527     arg1: 8,326,413,249,250 ( 13 digits)
528     ------------------------------------------------------------------------------
529     arg2: 12,935,482,154,386,850 ( 17 digits)
530     ------------------------------------------------------------------------------
531     gcd(arg1, arg2): 50 ( 2 digits)
532     ------------------------------------------------------------------------------
533    
534     C:\>intgcd 8326413249250 12935482154386850 -nf
535     8326413249250
536     12935482154386850
537     50
538     \end{verbatim}
539     \end{scriptsize}
540     \end{dosutilcommandsampleinvocations}
541    
542     \begin{dosutilcommandseealso}
543     See also the \emph{arbint intgcd} Tcl extension,
544     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sgcd0}.
545     \end{dosutilcommandseealso}
546    
547     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
548     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
549     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
550     \subsection{The \emph{intlcm} Utility}
551     %Subsection tag: LCM0
552     \label{cdcm0:sali0:slcm0}
553    
554     \index{intlcm@\emph{intlcm}}
555     \begin{dosutilcommandname}{intlcm}%
556     calculates the l.c.m. (least common multiple)
557     of two integers. (Mnemonic: \emph{int}eger
558     \emph{l}east \emph{c}ommon \emph{m}ultiple.)
559     \end{dosutilcommandname}
560    
561     \begin{dosutilcommandsynopsis}
562     \dosutilcommandsynopsisline{intlcm}{sint\_1 sint\_2 [$<$options$>$]}
563     \end{dosutilcommandsynopsis}
564    
565     \begin{dosutilcommanddescription}
566     The \emph{intlcm} utility calculates the l.c.m. of two
567     integers.
568    
569     The mapping from arguments to output and the details
570     of how the l.c.m. is calculated are described
571     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:slcm0}.
572     \end{dosutilcommanddescription}
573    
574     \begin{dosutilcommandsampleinvocations}
575     \begin{scriptsize}
576     \begin{verbatim}
577     C:\>intlcm 12 69
578     ------------------------------------------------------------------------------
579     arg1: 12 ( 2 digits)
580     ------------------------------------------------------------------------------
581     arg2: 69 ( 2 digits)
582     ------------------------------------------------------------------------------
583     lcm(arg1, arg2): 276 ( 3 digits)
584     ------------------------------------------------------------------------------
585     \end{verbatim}
586     \end{scriptsize}
587     \end{dosutilcommandsampleinvocations}
588    
589     \begin{dosutilcommandseealso}
590     See also the \emph{arbint intlcm} Tcl extension,
591     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:slcm0}.
592     \end{dosutilcommandseealso}
593    
594    
595     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
596     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
597     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
598     \subsection{The \emph{intexp} Utility}
599     %Subsection tag: IXP0
600     \label{cdcm0:sali0:sixp0}
601    
602     \index{intexp@\emph{intexp}}
603     \begin{dosutilcommandname}{intexp}%
604     exponentiates a signed integer to a non-negative integer
605     power. (Mnemonic: \emph{int}eger
606     \emph{exp}onent.)
607     \end{dosutilcommandname}
608    
609     \begin{dosutilcommandsynopsis}
610     \dosutilcommandsynopsisline{intexp}{sint\_base uint32\_exponent [$<$options$>$]}
611     \end{dosutilcommandsynopsis}
612    
613     \begin{dosutilcommanddescription}
614     The \emph{intexp} utility exponentiates an integer to a non-negative
615     integer power. For convenience and simplicity, $0^0$ produces 1,
616     which is inconsistent with the mathematical definition; but all other
617     exponentiations are as expected. The mapping is more precisely described
618     with the \emph{arbint intexp} Tcl extension in
619     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sixp0}.
620     \end{dosutilcommanddescription}
621    
622     \begin{dosutilcommandsampleinvocations}
623     \begin{scriptsize}
624     \begin{verbatim}
625     C:\>intexp -22 41
626     ------------------------------------------------------------------------------
627     base: - 22 ( 2 digits)
628     ------------------------------------------------------------------------------
629     exponent: 41 ( 2 digits)
630     ------------------------------------------------------------------------------
631     base ** exponent: - 10, ( 56 digits)
632     947,877,107,572,929,152,919,737,180,
633     202,022,857,988,400,441,953,615,872
634     ------------------------------------------------------------------------------
635    
636     C:\>intexp -22 41 -nf
637     -22
638     41
639     -10947877107572929152919737180202022857988400441953615872
640     \end{verbatim}
641     \end{scriptsize}
642     \end{dosutilcommandsampleinvocations}
643    
644     \begin{dosutilcommandseealso}
645     See also the \emph{arbint intexp} Tcl extension,
646     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sixp0}.
647     \end{dosutilcommandseealso}
648    
649     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
650     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
651     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
652     \subsection{The \emph{intfac} Utility}
653     %Subsection tag: IFC0
654     \label{cdcm0:sali0:sifc0}
655    
656     \index{intfac@\emph{intfac}}
657     \begin{dosutilcommandname}{intfac}%
658     calculates the \index{factorial function}factorial of a non-negative
659     integer. (Mnemonic: \emph{int}eger
660     \emph{fac}torial.)
661     \end{dosutilcommandname}
662    
663     \begin{dosutilcommandsynopsis}
664     \dosutilcommandsynopsisline{intfac}{uint32 [$<$options$>$]}
665     \end{dosutilcommandsynopsis}
666    
667     \begin{dosutilcommanddescription}
668     The \emph{intfac} utility calculates the factorial of
669     a non-negative integer. 0! is defined to be 1.
670    
671     This utility is useful for calculating the factorial of
672     integers where the result would be quite large (larger than
673     could be displayed on a pocket calculator, for example).
674     \end{dosutilcommanddescription}
675    
676     \begin{dosutilcommandremarks}
677     At the present time (07/2001, Version 1.04), the \emph{intfac} utility
678     is constrained by the division operations required to convert from the
679     binary internal integer format to a base-10 ASCII representation.
680     The \emph{intfac} utility will not calculate factorials of over about
681     1,000 decimal digits without a fair delay. In the future, algorithmic
682     improvements may raise this limit.
683     \end{dosutilcommandremarks}
684    
685     \begin{dosutilcommandsampleinvocations}
686     \begin{scriptsize}
687     \begin{verbatim}
688     C:\>intfac 47
689     ------------------------------------------------------------------------------
690     arg: 47 ( 2 digits)
691     ------------------------------------------------------------------------------
692     arg!: 258,623, ( 60 digits)
693     241,511,168,180,642,964,355,153,611,
694     979,969,197,632,389,120,000,000,000
695     ------------------------------------------------------------------------------
696    
697     C:\>intfac 47 -noformat
698     47
699     258623241511168180642964355153611979969197632389120000000000
700     \end{verbatim}
701     \end{scriptsize}
702     \end{dosutilcommandsampleinvocations}
703    
704     \begin{dosutilcommandseealso}
705     See also the \emph{arbint intfac} Tcl extension,
706     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:sarb0:sfac0}.
707     \end{dosutilcommandseealso}
708    
709    
710     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
711     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
712     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
713     \section{Rational Number Arithmetic Utilities}
714     %Section tag: RNU0
715     \label{cdcm0:srnu0}
716    
717    
718     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
719     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
720     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
721     \subsection{The \emph{rnadd} Utility}
722     %Subsection tag: RNA0
723     \label{cdcm0:srnu0:srna0}
724    
725     \index{rnadd@\emph{rnadd}}
726     \begin{dosutilcommandname}{rnadd}%
727     adds two rational numbers to produce a normalized rational result.
728     (Mnemonic: \emph{r}ational \emph{n}umber
729     \emph{add}ition.)
730     \end{dosutilcommandname}
731    
732     \begin{dosutilcommandsynopsis}
733     \dosutilcommandsynopsisline{rnadd}{srn srn [$<$options$>$]}
734     \end{dosutilcommandsynopsis}
735    
736     \begin{dosutilcommanddescription}
737     The \emph{rnadd} utility calculates the sum of two arbitrary
738     rational numbers.
739     \end{dosutilcommanddescription}
740    
741     \begin{dosutilcommandsampleinvocations}
742     \begin{scriptsize}
743     \begin{verbatim}
744     C:\>rnadd 3.29 42/67
745     ------------------------------------------------------------------------------
746     arg1_num: 329 ( 3 digits)
747     ------------------------------------------------------------------------------
748     arg1_den: 100 ( 3 digits)
749     ------------------------------------------------------------------------------
750     arg2_num: 42 ( 2 digits)
751     ------------------------------------------------------------------------------
752     arg2_den: 67 ( 2 digits)
753     ------------------------------------------------------------------------------
754     result_num: 26,243 ( 5 digits)
755     ------------------------------------------------------------------------------
756     result_den: 6,700 ( 4 digits)
757     ------------------------------------------------------------------------------
758     \end{verbatim}
759     \end{scriptsize}
760     \end{dosutilcommandsampleinvocations}
761    
762     \begin{dosutilcommandseealso}
763     See also the \emph{arbint rnadd} Tcl extension,
764     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:srne0:srad0}.
765     \end{dosutilcommandseealso}
766    
767    
768     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
769     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
770     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
771     \subsection{The \emph{rnsub} Utility}
772     %Subsection tag: RSB0
773     \label{cdcm0:srnu0:srsb0}
774    
775     \index{rnsub@\emph{rnsub}}
776     \begin{dosutilcommandname}{rnsub}%
777     subtracts two rational numbers to produce a normalized rational result.
778     (Mnemonic: \emph{r}ational \emph{n}umber
779     \emph{sub}traction.)
780     \end{dosutilcommandname}
781    
782     \begin{dosutilcommandsynopsis}
783     \dosutilcommandsynopsisline{rnsub}{srn srn [$<$options$>$]}
784     \end{dosutilcommandsynopsis}
785    
786     \begin{dosutilcommanddescription}
787     The \emph{rnsub} utility calculates the difference of two arbitrary
788     rational numbers. The second argument is subtracted from the first,
789     i.e. $arg_2 - arg_1$ is calculated.
790     \end{dosutilcommanddescription}
791    
792     \begin{dosutilcommandsampleinvocations}
793     \begin{scriptsize}
794     \begin{verbatim}
795     C:\>rnsub 3.29 42/67
796     ------------------------------------------------------------------------------
797     arg1_num: 329 ( 3 digits)
798     ------------------------------------------------------------------------------
799     arg1_den: 100 ( 3 digits)
800     ------------------------------------------------------------------------------
801     arg2_num: 42 ( 2 digits)
802     ------------------------------------------------------------------------------
803     arg2_den: 67 ( 2 digits)
804     ------------------------------------------------------------------------------
805     result_num: 17,843 ( 5 digits)
806     ------------------------------------------------------------------------------
807     result_den: 6,700 ( 4 digits)
808     ------------------------------------------------------------------------------
809     \end{verbatim}
810     \end{scriptsize}
811     \end{dosutilcommandsampleinvocations}
812    
813     \begin{dosutilcommandseealso}
814     See also the \emph{arbint rnsub} Tcl extension,
815     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:srne0:srsb0}.
816     \end{dosutilcommandseealso}
817    
818    
819     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
820     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
821     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
822     \subsection{The \emph{rnmul} Utility}
823     %Subsection tag: RMU0
824     \label{cdcm0:srnu0:srmu0}
825    
826     \index{rnmul@\emph{rnmul}}
827     \begin{dosutilcommandname}{rnmul}%
828     calculates the product of two rational numbers.
829     (Mnemonic: \emph{r}ational
830     \emph{n}umber \emph{mul}tiplication.)
831     \end{dosutilcommandname}
832    
833     \begin{dosutilcommandsynopsis}
834     \dosutilcommandsynopsisline{rnmul}{srn srn [$<$options$>$]}
835     \end{dosutilcommandsynopsis}
836    
837     \begin{dosutilcommanddescription}
838     The \emph{rnmul} utility calculates the product
839     of two rational numbers.
840     \end{dosutilcommanddescription}
841    
842     \begin{dosutilcommandsampleinvocations}
843     \begin{scriptsize}
844     \begin{verbatim}
845     E:\>rnmul 3.14 64/207
846     ------------------------------------------------------------------------------
847     arg1_num: 314 ( 3 digits)
848     ------------------------------------------------------------------------------
849     arg1_den: 100 ( 3 digits)
850     ------------------------------------------------------------------------------
851     arg2_num: 64 ( 2 digits)
852     ------------------------------------------------------------------------------
853     arg2_den: 207 ( 3 digits)
854     ------------------------------------------------------------------------------
855     result_num: 5,024 ( 4 digits)
856     ------------------------------------------------------------------------------
857     result_den: 5,175 ( 4 digits)
858     ------------------------------------------------------------------------------
859     \end{verbatim}
860     \end{scriptsize}
861     \end{dosutilcommandsampleinvocations}
862    
863     \begin{dosutilcommandseealso}
864     See also the \emph{arbint rnmul} Tcl extension,
865     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:srne0:srmu0}.
866     \end{dosutilcommandseealso}
867    
868    
869     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
870     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
871     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
872     \subsection{The \emph{rndiv} Utility}
873     %Subsection tag: RDV0
874     \label{cdcm0:srnu0:srdv0}
875    
876     \index{rndiv@\emph{rndiv}}
877     \begin{dosutilcommandname}{rndiv}%
878     calculates the quotient of two rational numbers.
879     (Mnemonic: \emph{r}ational
880     \emph{n}umber \emph{div}ision.)
881     \end{dosutilcommandname}
882    
883     \begin{dosutilcommandsynopsis}
884     \dosutilcommandsynopsisline{rndiv}{srn srn [$<$options$>$]}
885     \end{dosutilcommandsynopsis}
886    
887     \begin{dosutilcommanddescription}
888     The \emph{rnmul} utility calculates the quotient
889     of two rational numbers. The first argument is divided
890     by the second; i.e. the quotient $arg_1 / arg_2$ is calculated.
891     \end{dosutilcommanddescription}
892    
893     \begin{dosutilcommandsampleinvocations}
894     \begin{scriptsize}
895     \begin{verbatim}
896     E:\>rndiv 3.14 34/291
897     ------------------------------------------------------------------------------
898     arg1_num: 314 ( 3 digits)
899     ------------------------------------------------------------------------------
900     arg1_den: 100 ( 3 digits)
901     ------------------------------------------------------------------------------
902     arg2_num: 34 ( 2 digits)
903     ------------------------------------------------------------------------------
904     arg2_den: 291 ( 3 digits)
905     ------------------------------------------------------------------------------
906     result_num: 45,687 ( 5 digits)
907     ------------------------------------------------------------------------------
908     result_den: 1,700 ( 4 digits)
909     ------------------------------------------------------------------------------
910     \end{verbatim}
911     \end{scriptsize}
912     \end{dosutilcommandsampleinvocations}
913    
914     \begin{dosutilcommandseealso}
915     See also the \emph{arbint rndiv} Tcl extension,
916     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:srne0:srdv0}.
917     \end{dosutilcommandseealso}
918    
919    
920     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
921     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
922     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
923     \subsection{The \emph{rndeq} Utility}
924     %Subsection tag: RNQ0
925     \label{cdcm0:srnu0:srnq0}
926    
927     \index{rndeq@\emph{rndeq}}
928     \begin{dosutilcommandname}{rndeq}%
929     calculates the decimal equivalent of a rational number.
930     (Mnemonic: \emph{r}ational \emph{n}umber
931     \emph{d}ecimal \emph{eq}uivalent.)
932     \end{dosutilcommandname}
933    
934     \begin{dosutilcommandsynopsis}
935     \dosutilcommandsynopsisline{rndeq}{srn [$<$options$>$]}
936     \dosutilcommandsynopsisline{rndeq}{srn uint [$<$options$>$]}
937     \end{dosutilcommandsynopsis}
938    
939     \begin{dosutilcommanddescription}
940     The \emph{rndeq} utility calculates the decimal equivalent
941     of a rational number using a large integer
942     algorithm.
943    
944     Let $a/b$ be a rational number that we wish to express
945     as a decimal number, let $N$ be an integral power
946     of 10, and let $x$ be an integer chosen so that $x/N$
947     is an approximation to $a/b$.
948    
949     If we choose
950    
951     \begin{equation}
952     \label{eq:cdcm0:sali0:srnq0:01}
953     x = sgn \left( {\frac{a}{b}} \right)
954     \left\lfloor {\left| \frac{a}{b} \right| N} \right\rfloor ,
955     \end{equation}
956    
957     it can be shown that
958    
959     \begin{equation}
960     \label{eq:cdcm0:sali0:srnq0:02}
961     \left| {\frac{a}{b}} \right| - \frac{1}{N}
962     <
963     \frac{\left\lfloor {\left| {\frac{a}{b}} \right| N} \right\rfloor}{N}
964     \leq
965     \left|{\frac{a}{b}}\right|.
966     \end{equation}
967    
968     In other words, the result if $x$ is chosen as specified in
969     (\ref{eq:cdcm0:sali0:srnq0:01}), $x/N$ will be at or up to one numerator
970     count less in magnitude than $a/b$. Stated differently,
971     $x/N$ is ``truncated down'' in magnitude.
972    
973     The \emph{rndeq} utility performs the mapping implied by
974     (\ref{eq:cdcm0:sali0:srnq0:01}) and
975     (\ref{eq:cdcm0:sali0:srnq0:02}), by default using
976     $N=10^{108}$. The value of $N=10^{108}$ was chosen
977     because it produces an attractive display format at
978     27 digits per line, and also places the imaginary decimal
979     point between lines so it is easier to interpret the output of
980     this utility. An example is interpreted in the sample invocations
981     below.
982    
983     This utility will accept an optional second parameter, which
984     is a value of $N$ to override the default of $10^{108}$. This
985     optional second parameter can be used to provide more decimal places,
986     or to provide a different type of mapping.\footnote{Please be aware that integers
987     may be specified using scientific notation. For example, to effectively double
988     the number of decimal places displayed by \texttt{rndeq} in the
989     invocation example below, one might enter the command line
990     \texttt{rndeq 5345/319 1e216}. We would regret it if this fact were unknown
991     and some desperate user were to enter the digit ``1'' followed by
992     216 zeros!}
993    
994     It is not required that the second parameter, if supplied, be a power of
995     10---the mappings described by the equations above will be carried
996     out with \emph{any} supplied denominator.
997     However, it is not intuitively obvious how this utility would be
998     useful with a denominator that is not a power of 10.
999     \end{dosutilcommanddescription}
1000    
1001     \begin{dosutilcommandsampleinvocations}
1002     \begin{scriptsize}
1003     \begin{verbatim}
1004     C:\>rndeq 5345/319
1005     ------------------------------------------------------------------------------
1006     arg_num: 5,345 ( 4 digits)
1007     ------------------------------------------------------------------------------
1008     arg_den: 319 ( 3 digits)
1009     ------------------------------------------------------------------------------
1010     dap_num: 16, ( 110 digits)
1011     755,485,893,416,927,899,686,520,376,
1012     175,548,589,341,692,789,968,652,037,
1013     617,554,858,934,169,278,996,865,203,
1014     761,755,485,893,416,927,899,686,520
1015     ------------------------------------------------------------------------------
1016     dap_den: 1, ( 109 digits)
1017     000,000,000,000,000,000,000,000,000,
1018     000,000,000,000,000,000,000,000,000,
1019     000,000,000,000,000,000,000,000,000,
1020     000,000,000,000,000,000,000,000,000
1021     ------------------------------------------------------------------------------
1022     \end{verbatim}
1023     \end{scriptsize}
1024    
1025     It can be seen from the sample invocation above that
1026     5345/319$\approx$16.755---note how the imaginary decimal point is placed
1027     between lines of \texttt{dap\_num}. It can also be seen that the
1028     decimal representation repeats, i.e.
1029    
1030     \begin{equation}
1031     \frac{5345}{319} = 16.\overline{7554858934169278996865203761}.
1032     \end{equation}
1033     \end{dosutilcommandsampleinvocations}
1034    
1035    
1036     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1037     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1038     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1039     \subsection{The \emph{rnred} Utility}
1040     %Subsection tag: RNR0
1041     \label{cdcm0:srnu0:srnr0}
1042    
1043     \index{rnred@\emph{rnred}}
1044     \begin{dosutilcommandname}{rnred}%
1045     reduces a rational number to lowest terms and normalizes it.
1046     (Mnemonic: \emph{r}ational
1047     \emph{n}umber \emph{red}uce and normalize.)
1048     \end{dosutilcommandname}
1049    
1050     \begin{dosutilcommandsynopsis}
1051     \dosutilcommandsynopsisline{rnred}{srn [$<$options$>$]}
1052     \end{dosutilcommandsynopsis}
1053    
1054     \begin{dosutilcommanddescription}
1055     The \emph{rnred} reduces a rational number to its lowest terms
1056     and normalizes it. This process is the same process
1057     described in the description of the \emph{arbint rnred} Tcl
1058     extension, Section \cxtnzeroxrefhyphen{}\ref{cxtn0:srne0:srnr0}.
1059     \end{dosutilcommanddescription}
1060    
1061     \begin{dosutilcommandsampleinvocations}
1062     \begin{scriptsize}
1063     \begin{verbatim}
1064     C:\>rnred 422.414
1065     ------------------------------------------------------------------------------
1066     numerator: 211,207 ( 6 digits)
1067     ------------------------------------------------------------------------------
1068     denominator: 500 ( 3 digits)
1069     ------------------------------------------------------------------------------
1070    
1071     C:\>rnred 422.414 -nf
1072     211207
1073     500
1074     \end{verbatim}
1075     \end{scriptsize}
1076     \end{dosutilcommandsampleinvocations}
1077    
1078     \begin{dosutilcommandseealso}
1079     See also the \emph{arbint rnred} Tcl extension,
1080     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:srne0:srnr0}.
1081     \end{dosutilcommandseealso}
1082    
1083    
1084     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1085     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1086     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1087     \section[Number Theory, CF, And Approximation Utilities]
1088     {Number Theory, Continued Fraction, And Best Rational Approximation
1089     Utilities}
1090     %Section tag: nth0
1091     \label{cdcm0:snth0}
1092    
1093    
1094     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1095     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1096     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1097     \subsection{The \emph{cfratnum} Utility}
1098     %Subsection tag: CFR0
1099     \label{cdcm0:snth0:scfr0}
1100    
1101     \index{cfratnum@\emph{cfratnum}}
1102     \begin{dosutilcommandname}{cfratnum}%
1103     calculates the continued fraction partial quotients and convergents
1104     of a non-negative rational number. (Mnemonic: \emph{c}ontinued
1105     \emph{f}raction partial quotients and convergents of
1106     a \emph{rat}ional \emph{num}ber.)
1107     \end{dosutilcommandname}
1108    
1109     \begin{dosutilcommandsynopsis}
1110     \dosutilcommandsynopsisline{cfratnum}{urn [$<$options$>$]}
1111     \end{dosutilcommandsynopsis}
1112    
1113     \begin{dosutilcommanddescription}
1114     The \emph{cfratnum} utility calculates the continued fraction
1115     partial quotients and convergents of a non-negative rational number.
1116     This information can be useful in a variety of contexts, including
1117     finding best rational approximations.
1118    
1119     Additionally, this DOS utility provides a decimal approximation
1120     of each convergent, using a denominator of
1121     $10^{108}$ (see the description of the \emph{rndeq} utility, Section
1122     \ref{cdcm0:srnu0:srnq0}).
1123     \end{dosutilcommanddescription}
1124    
1125     \begin{dosutilcommandsampleinvocations}
1126     \begin{scriptsize}
1127     \begin{verbatim}
1128     C:\>cfratnum 3.14
1129     ******************************************************************************
1130     ******************* Continued Fraction Representation *******************
1131     ******************************************************************************
1132     Input Numerator: 314 ( 3 digits)
1133     ------------------------------------------------------------------------------
1134     Input Denominator: 100 ( 3 digits)
1135     ------------------------------------------------------------------------------
1136     dividend(0): 314 ( 3 digits)
1137     ------------------------------------------------------------------------------
1138     divisor(0): 100 ( 3 digits)
1139     ------------------------------------------------------------------------------
1140     a(0): 3 ( 1 digit )
1141     ------------------------------------------------------------------------------
1142     p(0): 3 ( 1 digit )
1143     ------------------------------------------------------------------------------
1144     q(0): 1 ( 1 digit )
1145     ------------------------------------------------------------------------------
1146     dap_h(0): 3, ( 109 digits)
1147     000,000,000,000,000,000,000,000,000,
1148     000,000,000,000,000,000,000,000,000,
1149     000,000,000,000,000,000,000,000,000,
1150     000,000,000,000,000,000,000,000,000
1151     ------------------------------------------------------------------------------
1152     dap_k(0): 1, ( 109 digits)
1153     000,000,000,000,000,000,000,000,000,
1154     000,000,000,000,000,000,000,000,000,
1155     000,000,000,000,000,000,000,000,000,
1156     000,000,000,000,000,000,000,000,000
1157     ------------------------------------------------------------------------------
1158     dividend(1): 100 ( 3 digits)
1159     ------------------------------------------------------------------------------
1160     divisor(1): 14 ( 2 digits)
1161     ------------------------------------------------------------------------------
1162     a(1): 7 ( 1 digit )
1163     ------------------------------------------------------------------------------
1164     p(1): 22 ( 2 digits)
1165     ------------------------------------------------------------------------------
1166     q(1): 7 ( 1 digit )
1167     ------------------------------------------------------------------------------
1168     dap_h(1): 3, ( 109 digits)
1169     142,857,142,857,142,857,142,857,142,
1170     857,142,857,142,857,142,857,142,857,
1171     142,857,142,857,142,857,142,857,142,
1172     857,142,857,142,857,142,857,142,857
1173     ------------------------------------------------------------------------------
1174     dap_k(1): 1, ( 109 digits)
1175     000,000,000,000,000,000,000,000,000,
1176     000,000,000,000,000,000,000,000,000,
1177     000,000,000,000,000,000,000,000,000,
1178     000,000,000,000,000,000,000,000,000
1179     ------------------------------------------------------------------------------
1180     dividend(2): 14 ( 2 digits)
1181     ------------------------------------------------------------------------------
1182     divisor(2): 2 ( 1 digit )
1183     ------------------------------------------------------------------------------
1184     a(2): 7 ( 1 digit )
1185     ------------------------------------------------------------------------------
1186     p(2): 157 ( 3 digits)
1187     ------------------------------------------------------------------------------
1188     q(2): 50 ( 2 digits)
1189     ------------------------------------------------------------------------------
1190     dap_h(2): 3, ( 109 digits)
1191     140,000,000,000,000,000,000,000,000,
1192     000,000,000,000,000,000,000,000,000,
1193     000,000,000,000,000,000,000,000,000,
1194     000,000,000,000,000,000,000,000,000
1195     ------------------------------------------------------------------------------
1196     dap_k(2): 1, ( 109 digits)
1197     000,000,000,000,000,000,000,000,000,
1198     000,000,000,000,000,000,000,000,000,
1199     000,000,000,000,000,000,000,000,000,
1200     000,000,000,000,000,000,000,000,000
1201     ------------------------------------------------------------------------------
1202     \end{verbatim}
1203     \end{scriptsize}
1204    
1205     Note in the sample invocation above that each convergent
1206     also includes a decimal approximation. For example,
1207     in the invocation above, it can be seen that
1208     22/7 $\approx$ 3.142857142857 \ldots{}.
1209    
1210     Note also that at each round of calculation of partial
1211     quotients and convergents, the remainder is not shown because
1212     it becomes the divisor of the next round, and so it would be
1213     redundant to show it. Note also that the final non-zero remainder
1214     (which is the g.c.d. of the numerator and denominator)
1215     appears as the final divisor. In the sample
1216     invocation above, it can be seen that the g.c.d. of
1217     314 and 100 is the integer labeled as
1218     \texttt{divisor(2)}, which has the value of 2.
1219     \end{dosutilcommandsampleinvocations}
1220    
1221     \begin{dosutilcommandseealso}
1222     See also the \emph{arbint cfratnum} Tcl extension,
1223     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:snth0:scfr0}.
1224     \end{dosutilcommandseealso}
1225    
1226    
1227     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1228     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1229     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1230     \subsection{The \emph{cfbrapab} Utility}
1231     %Subsection tag: BRA0
1232     \label{cdcm0:snth0:sbra0}
1233    
1234     \index{cfbrapab@\emph{cfbrapab}}
1235     \begin{dosutilcommandname}{cfbrapab}%
1236     calculates the best rational approximation to a
1237     rational
1238     number in the Farey series of order
1239     $k_{MAX}$, or in a rectangular region of the integer lattice
1240     defined by $k \leq k_{MAX}$ and $h \leq h_{MAX}$.
1241     (Mnemonic: \emph{c}ontinued
1242     \emph{f}raction \emph{b}est \emph{r}ational \emph{ap}proximation
1243     in $F_{a, \overline{b}}$.)
1244     \end{dosutilcommandname}
1245    
1246     \begin{dosutilcommanddescription}
1247     Except for display format,
1248     this utility behaves the same way and
1249     accepts the same options as the \emph{arbint cfbrapab}
1250     Tcl extension, described in Section \cxtnzeroxrefhyphen{}\ref{cxtn0:snth0:sbra0}.
1251     Please see the documentation of this Tcl extension, which also applies
1252     to this DOS command-line utility.
1253     \end{dosutilcommanddescription}
1254    
1255    
1256     \begin{dosutilcommandsampleinvocations}
1257     \begin{scriptsize}
1258     \begin{verbatim}
1259     C:\swprojs\cfbrapab\Release>cfbrapab 1.6093 255 255
1260     ------------------------------------------------------------------------------
1261     MAJOR MODE: Finding closest rational number(s) under the constraints.
1262     ------------------------------------------------------------------------------
1263     RI_IN Numerator: 16,093 ( 5 digits)
1264     ------------------------------------------------------------------------------
1265     RI_IN Denominator: 10,000 ( 5 digits)
1266     ------------------------------------------------------------------------------
1267     K_MAX: 255 ( 3 digits)
1268     ------------------------------------------------------------------------------
1269     H_MAX: 255 ( 3 digits)
1270     ------------------------------------------------------------------------------
1271     approx_num(-1): 243 ( 3 digits)
1272     ------------------------------------------------------------------------------
1273     approx_den(-1): 151 ( 3 digits)
1274     ------------------------------------------------------------------------------
1275     dap_num(-1): 1, ( 109 digits)
1276     609,271,523,178,807,947,019,867,549,
1277     668,874,172,185,430,463,576,158,940,
1278     397,350,993,377,483,443,708,609,271,
1279     523,178,807,947,019,867,549,668,874
1280     ------------------------------------------------------------------------------
1281     dap_den(-1): 1, ( 109 digits)
1282     000,000,000,000,000,000,000,000,000,
1283     000,000,000,000,000,000,000,000,000,
1284     000,000,000,000,000,000,000,000,000,
1285     000,000,000,000,000,000,000,000,000
1286     ------------------------------------------------------------------------------
1287     error_num(-1): - 43 ( 2 digits)
1288     ------------------------------------------------------------------------------
1289     error_den(-1): 1,510,000 ( 7 digits)
1290     ------------------------------------------------------------------------------
1291     \end{verbatim}
1292     \end{scriptsize}
1293    
1294     Note in the sample invocation above that the
1295     decimal equivalent of the approximation is also provided.
1296     Note also that the different parameters of this utility produce
1297     different output formats which are not documented here, for
1298     brevity. For example, using the \texttt{-pred} or \texttt{-succ}
1299     options does not produce decimal approximation information, because
1300     these options are not normally used for approximation---such
1301     behaviors are inconsequential and not documented.
1302     \end{dosutilcommandsampleinvocations}
1303    
1304    
1305     \begin{dosutilcommandseealso}
1306     This extension uses the continued fraction
1307     algorithms presented in Chapter \ccfrzeroxrefhyphen{}\ref{ccfr0}.
1308     See also the \emph{arbint cfbrapab} Tcl extension,
1309     Section \cxtnzeroxrefhyphen{}\ref{cxtn0:snth0:sbra0}.
1310     \end{dosutilcommandseealso}
1311    
1312    
1313     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1314     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1315     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1316     \section{Authors And Acknowledgements}
1317     %Section tag: ACK0
1318    
1319    
1320     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1321     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1322     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1323     \section{Exercises}
1324     %Section tag: EXE0
1325    
1326    
1327    
1328     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1329    
1330     \noindent\begin{figure}[!b]
1331     \noindent\rule[-0.25in]{\textwidth}{1pt}
1332     \begin{tiny}
1333     \begin{verbatim}
1334     $RCSfile: c_dcm0.tex,v $
1335     $Source: /home/dashley/cvsrep/e3ft_gpl01/e3ft_gpl01/dtaipubs/esrgubka/c_dcm0/c_dcm0.tex,v $
1336     $Revision: 1.13 $
1337     $Author: dtashley $
1338     $Date: 2001/08/18 18:37:56 $
1339     \end{verbatim}
1340     \end{tiny}
1341     \noindent\rule[0.25in]{\textwidth}{1pt}
1342     \end{figure}
1343    
1344     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1345     % $Log: c_dcm0.tex,v $
1346     % Revision 1.13 2001/08/18 18:37:56 dtashley
1347     % Preparation for v1.05 release.
1348     %
1349     % Revision 1.12 2001/08/16 19:53:27 dtashley
1350     % Beginning to prepare for v1.05 release.
1351     %
1352     % Revision 1.11 2001/08/12 10:15:33 dtashley
1353     % Safety check-in. Substantial progress.
1354     %
1355     % Revision 1.10 2001/08/10 00:56:07 dtashley
1356     % Completion of basic rational number arithmetic utilities and extensions.
1357     %
1358     % Revision 1.9 2001/08/08 02:25:03 dtashley
1359     % Completion of RNRED utility and ARBINT RNRED Tcl extension.
1360     %
1361     % Revision 1.8 2001/08/07 10:46:44 dtashley
1362     % Completion of CFRATNUM Tcl extension and DOS command-line utility.
1363     %
1364     % Revision 1.7 2001/08/01 03:37:39 dtashley
1365     % Finished most primitive integer operations, both as Tcl extensions and
1366     % as DOS command-line utilities, such as addition, subtraction,
1367     % multiplication, division, and modulo.
1368     %
1369     % Revision 1.6 2001/07/30 02:54:17 dtashley
1370     % INTFAC extension and command-line utility finished.
1371     %
1372     % Revision 1.5 2001/07/23 21:40:43 dtashley
1373     % Hopefully final changes to the section about convergents as best
1374     % approximations. Tool documentation changes.
1375     %
1376     % Revision 1.4 2001/07/23 06:50:44 dtashley
1377     % Completion of INTFAC command and documentation.
1378     %
1379     % Revision 1.3 2001/07/23 03:30:20 dtashley
1380     % Edits.
1381     %
1382     % Revision 1.2 2001/07/13 06:57:50 dtashley
1383     % Safety check-in.
1384     %
1385     % Revision 1.1 2001/07/11 20:10:30 dtashley
1386     % Chapter on DOS console-mode utilities added.
1387     %
1388     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1389     %End of file C_DCM0.TEX

dashley@gmail.com
ViewVC Help
Powered by ViewVC 1.1.25