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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 277 - (show annotations) (download) (as text)
Tue Aug 13 02:35:39 2019 UTC (5 years, 2 months ago) by dashley
File MIME type: application/x-tex
File size: 56975 byte(s)
Change keyword substitution (migration from cvs to svn).
Add quotation.
1 %$Header$
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 $HeadURL$
1335 $Revision$
1336 $Date$
1337 $Author$
1338 \end{verbatim}
1339 \end{tiny}
1340 \noindent\rule[0.25in]{\textwidth}{1pt}
1341 \end{figure}
1342
1343 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1344 %
1345 %End of file C_DCM0.TEX

Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision URL Header

dashley@gmail.com
ViewVC Help
Powered by ViewVC 1.1.25