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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 278 - (show annotations) (download) (as text)
Wed Aug 14 23:10:36 2019 UTC (4 years, 6 months ago) by dashley
File MIME type: application/x-tex
File size: 70523 byte(s)
Change keyword substitution (migration from cvs to svn).
1 %$Header$
2
3 \chapter[\cxtnzeroshorttitle{}]{\cxtnzerolongtitle{}}
4
5 \label{cxtn0}
6
7 \beginchapterquote{``One way to prevent progress is by arguing that any first
8 step is unfair to somebody.''}
9 {Unknown}
10
11 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
14 \section{Introduction}
15 %Section Tag: INT0
16 \label{cxtn0:sint0}
17
18 The Tcl scripting language provides for \emph{extensions}, which are
19 compiled-in commands added to the language. These extensions have advantages
20 for performance, because they allow the high-frequency interactions to occur
21 in compiled code, and the lower-frequency interactions to occur in
22 a Tcl script.
23
24 This chapter describes the extensions that have been added to the Tcl
25 interpreters which are part of \emph{The Iju Tool Set}.
26
27 Many of the parameter formats are common between the Tcl extensions
28 (described in this chapter) and the DOS command-line
29 utilities (described in Chapter
30 \cdcmzeroxrefhyphen{}\ref{cdcm0}). For this reason, to avoid
31 redundancy of documentation, the parameter formats described
32 in Section \ctinzeroxrefhyphen{}\ref{ctin0:sccl0} apply both to the
33 Tcl extensions
34 and the DOS command-line utilities.
35
36
37
38 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
39 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
40 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
41 \section{Version Control Extensions}
42
43
44 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
45 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
46 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
47 \subsection{vcinfo}
48
49 \index{vcinfo@\emph{vcinfo}}
50 \begin{tclcommandname}{vcinfo}%
51 retrieves embedded static version and version control information for
52 IjuScripter or IjuConsole.
53 This allows a script to determine which version of script interpreter it is
54 running under.
55 \end{tclcommandname}
56
57 \begin{tclcommandsynopsis}
58 \tclcommandsynopsisline{vcinfo}{-ijutoolsversion}
59 \tclcommandsynopsisline{vcinfo}{?-crconly? -fileversion filename}
60 \tclcommandsynopsisline{vcinfo}{?-crconly? -extensionversion extensionname}
61 \tclcommandsynopsisline{vcinfo}{-buildmanifest}
62 \end{tclcommandsynopsis}
63
64 \begin{tclcommanddescription}
65 The \emph{vcinfo} command returns information about the version of the
66 IjuScripter or IjuConsole executable program, about the version of
67 a specific source file, or [collectively] about the version of all files
68 which [directly] contribute to the behavior of an embedded Tcl/Tk extension.
69 This command can be used to
70 inquire about the version of the executable program or certain of its
71 components.
72
73 Most commonly, this command is used to help assure reproducibility
74 of a script's behavior by coding a script so that it will
75 run only under a specific version(s) of executable.
76
77 \tclcommanddescsynopsisline{vcinfo}{-ijutoolsversion}
78 \begin{tclcommandinternaldescription}
79 Returns a string identifying the version number of the IjuScripter or IjuConsole
80 executable. The string will be of the form ``vm.nx'', where \emph{v} is the letter
81 ``v'', \emph{m} is the major version number, \emph{n} is the minor version number, and
82 \emph{x} is an optional lower-case letter identifying a service release which fixes defects
83 but adds no new functionality.
84
85 For example, a return value of ``v1.03'' would identify version 1.03. A return
86 value of ``v1.03c'' would identify the third service release to version 1.03; with
87 the service release designed to correct defects present in version 1.03b, but adding
88 no new functionality.
89 \end{tclcommandinternaldescription}
90
91 \tclcommanddescsynopsisline{vcinfo}{-fileversion filename}
92 \begin{tclcommandinternaldescription}
93 (Not yet implemented.) Returns a string with version control information for the file
94 \emph{filename}, which must be part of the IjuScripter or IjuConsole build.
95 An error is generated if a \emph{filename} which is not part of the build
96 is supplied. This form of the \emph{vcinfo} command is not normally used from a script.
97 \end{tclcommandinternaldescription}
98
99 \tclcommanddescsynopsisline{vcinfo}{-crconly -fileversion filename}
100 \begin{tclcommandinternaldescription}
101 (Not yet implemented.) Returns the CRC32 of the the string result of the command above.
102 Note that the value returned is the CRC of the version control information embedded in the file
103 rather than the CRC of the file.
104 \emph{filename} must be part of the IjuScripter or IjuConsole build, and
105 an error is generated if a \emph{filename} which is not part of the build is supplied.
106 This form is
107 useful because it supplies a terse result of eight hexadecimal digits which can easily
108 establish with a probability of about $1-2^{-32}$ that two versions of IjuScripter or IjuConsole
109 have the same file component; or establish with unity probability that they do not.
110 \end{tclcommandinternaldescription}
111
112 \tclcommanddescsynopsisline{vcinfo}{-extensionversion extensionname}
113 \begin{tclcommandinternaldescription}
114 (Not yet implemented.) Returns a string with version control information for all
115 files which contribute directly to the behavior of the Tcl extension \emph{extensionname},
116 which must be part of the IjuScripter or IjuConsole static build.
117 An error is generated if an \emph{extensionname} which is not part of the build
118 is supplied.
119 \end{tclcommandinternaldescription}
120
121 \tclcommanddescsynopsisline{vcinfo}{-crconly -extensionversion extensionname}
122 \begin{tclcommandinternaldescription}
123 (Not yet implemented.) Returns the CRC32 of the the string result of the command above.
124 Note that the value returned is the CRC of the version control information embedded in the file(s)
125 rather than the CRC(s) of the file(s).
126 \emph{extensionname} must be part of the IjuScripter or IjuConsole build, and
127 an error is generated if an \emph{extensionname} which is not part of the build is supplied.
128 This form is
129 useful because it supplies a terse result of eight hexadecimal digits which can easily
130 establish with a probability of about $1-2^{-32}$ that two versions of IjuScripter or IjuConsole
131 have the same extension component(s); or establish with unity probability that they do not.
132 \end{tclcommandinternaldescription}
133
134 \tclcommanddescsynopsisline{vcinfo}{-crconly -buildmanifest}
135 \begin{tclcommandinternaldescription}
136 (Not yet implemented.) Returns the full combined build manifest of IjuScripter and IjuConsole.
137 This includes size and CRC information for every file involved in the build. This form
138 of \emph{vcinfo} is provided for assistance in defect diagnosis.
139 \end{tclcommandinternaldescription}
140
141 \end{tclcommanddescription}
142
143
144 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
145 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
146 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
147 \section{File Transformation Extensions}
148
149
150 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
151 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
152 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
153 \section{CRC, Checksum, And Hash Extensions}
154 %Section Tag: CRC0
155
156
157 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
158 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
159 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
160 \subsection{crc32}
161 %Subsection Tag: CRC0
162 \label{cxtn0:scrc0:scrc0}
163
164
165 \index{crc32@\emph{crc32}}
166 \begin{tclcommandname}{crc32}%
167 generates the CRC-32 of a file or string. This CRC can be reliably used to obtain
168 digital signatures of files or data.
169 \end{tclcommandname}
170
171 \begin{tclcommandsynopsis}
172 \tclcommandsynopsisline{crc32}{filename}
173 \tclcommandsynopsisline{crc32}{-string binarystringval}
174
175 Note: as of 01/01/01, the ``stateful'' forms below are not yet implemented.
176
177 \tclcommandsynopsisline{crc32}{-initialstate}
178 \tclcommandsynopsisline{crc32}{-advancestate state filename}
179 \tclcommandsynopsisline{crc32}{-advancestate -string state binarystringval}
180 \tclcommandsynopsisline{crc32}{-crcfromstate state}
181 \end{tclcommandsynopsis}
182
183 \begin{tclcommanddescription}
184 The \emph{crc32} command forms the CRC-32 of the binary contents of a file
185 or of the binary contents of a string. The CRC-32 is useful as a digital
186 signature, and can be used with unity probability to determine that two
187 files are different, or with a probability of about $1-2^{-32}$ to determine
188 that two files are almost certainly identical.
189
190 In the invocations below, the CRC-32 is always returned as a 10-character ASCII string
191 of the form \emph{``0xDDDDDDDD''}, where \emph{``DDDDDDDD''} is the hexadecimal representation
192 of the 32-bit CRC-32, and \emph{``0x''} is a constant 2-character prefix
193 (the ``zero'' digit followed by ``x'') which is included for
194 aesthetics. It is guaranteed that:
195
196 \begin{itemize}
197 \item The string returned will be exclusively ASCII.
198 \item The string will have a length of exactly 10 characters.
199 \item The first two characters of the string will be \emph{``0x''}.
200 \item The hexadecimal representation
201 will be exactly 8 characters, and any letters
202 in the hexadecimal representation will be upper-case.
203 \end{itemize}
204
205 \tclcommanddescsynopsisline{crc32}{filename}
206 \begin{tclcommandinternaldescription}
207 Returns the CRC-32 of \emph{filename}, treated as an ordered collection of bytes (i.e.
208 newline characters and file termination characters are not processed---the file is
209 treated as a binary file). \emph{filename} must be specified in the form accepted by
210 the Tcl internals (forward slashes only).
211 \end{tclcommandinternaldescription}
212
213 \tclcommanddescsynopsisline{crc32}{-string binarystringval}
214 \begin{tclcommandinternaldescription}
215 Returns the CRC-32 of \emph{binarystringval}, treated as an ordered collection of bytes (i.e.
216 newline characters and string termination characters are not honored---the string is
217 treated as a binary string).\footnote{For an ASCII string, the \emph{crc32} extension will
218 behave as expected, and will process all characters up to but not including the zero
219 terminator. However, the \emph{crc32} extension will also correctly process non-ASCII strings.}
220 \end{tclcommandinternaldescription}
221
222 \tclcommanddescsynopsisline{crc32}{-initialstate}
223 \tclcommanddescsynopsisline{crc32}{-advancestate state filename}
224 \tclcommanddescsynopsisline{crc32}{-advancestate -string state filename}
225 \tclcommanddescsynopsisline{crc32}{-crcfromstate state}
226 \begin{tclcommandinternaldescription}
227 The four forms above are designed to allow ``running CRCs'' to be calculated; in which
228 the CRC is calculated piecemeal. These forms allow the caller to retain the internal
229 state vector of the CRC calculation algorithm.
230
231 The first form, \emph{crc32 -initialstate}, returns an ASCII representation of the
232 correct initial state vector of the CRC-32 state machine. The client is required
233 to obtain this initial state before beginning a piecemeal CRC calculation. Although the
234 returned string is a constant (it will always be the same), representational details
235 may change in future versions of the \emph{crc32} extension, and so a caller should never
236 make assumptions about what this invocation will return, as these assumptions may
237 render a script incompatible with future versions of \emph{crc32}.
238
239 The second and third forms, \emph{crc32 -advancestate state filename}
240 and \emph{crc32 -advancestate -string state filename}, apply a file or a binary string
241 to \emph{state} to produce a new \emph{state}, which is returned. This new \emph{state}
242 must be retained by the caller and used in subsequent calls.
243
244 The final form, \emph{crc32 -crcfromstate state}, maps from the state vector to the
245 calculated CRC, and will return a 10-character ASCII string as described above.
246 \end{tclcommandinternaldescription}
247 \end{tclcommanddescription}
248
249 \begin{tclcommandusagenotes}
250 (1) The ``piecemeal'' forms are as efficient as the file and string forms---there is no difference
251 in the internal algorithms. The primary cost of the piecemeal forms is in importing and
252 exporting the algorithm state vector to/from an ASCII string.
253 Thus, the piecemeal forms become less efficient when
254 small files or strings are processed, as there are more exports and imports
255 of the state vector. When using the piecemeal forms, processing the data in
256 larger chunks will give better performance.
257
258 (2) If the \emph{crc32} command is used to signature files, it is recommended that
259 the \texttt{file size} command also be used to lower the probability of falsely
260 assuming two non-identical files are identical yet further. Two files might be
261 assumed identical if they have the same size and the same CRC-32.
262 \end{tclcommandusagenotes}
263
264 \begin{tclcommandacknowledgements}
265 The \emph{crc32} command was implemented using ideas and C-language
266 code from a website (\cite{bibref:w:ellingsoncrc32pages})
267 provided by Richard A. Ellingson\index{Ellingson, Richard A.}
268 \cite{bibref:i:richardaellingson}. I am especially
269 grateful to Mr. Ellingson for providing these materials publicly
270 and free of charge.
271 \end{tclcommandacknowledgements}
272
273 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
274 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
275 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
276 \section{Random Number Generation Extensions}
277
278
279 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
280 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
281 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
282 \subsection{rngPwrResRndA}
283
284 \index{rngPwrResRndA@\emph{rngPwrResRndA}}
285 \begin{tclcommandname}{rngPwrResRndA}%
286 generates pseudo-random integers using the power residue
287 method with $\alpha = 7^5 = 16,807$ and
288 $M = 2^{31}-1 = 2,147,483,647$, providing a period of $M - 1 = 2^{31}-2 = 2,147,483,646$
289 (\cite{bibref:b:LeonGarciaProb}, pp. 69-71).
290 \end{tclcommandname}
291
292 \begin{tclcommandsynopsis}
293 \tclcommandsynopsisline{rngPwrResRndA}{}
294 \tclcommandsynopsisline{rngPwrResRndA}{$N$}
295 \end{tclcommandsynopsis}
296
297 \begin{tclcommanddescription}
298 The \emph{rngPwrResRndA} command generates pseudo-random positive integers
299 using the [power residue] recursive formula
300
301 \begin{equation}
302 \label{cxtn0:rngPwrResRndA:eq00}
303 Z_i = \alpha Z_{i-1} mod M,
304 \end{equation}
305
306 with $(\alpha, M)$ chosen as $(\alpha = 7^5=16,807, M = 2^{31}-1 = 2,147,483,647)$, as
307 indicated above. With these choices of $(\alpha, M)$, the sequence has a period
308 of $M - 1 = 2^{31}-2 = 2,147,483,646$ and good statistical properties.
309
310 The basis for choosing $(\alpha, M)$ has its origins in number theory, and won't
311 be discussed here. We refer the reader to \cite{bibref:b:LeonGarciaProb}
312 and to mathematical papers on the power residue method.
313
314 This extension maintains one internal seed value, which is initialized to
315 1,578,127,215 at Tcl/Tk startup.\footnote{There is no scientific
316 reason for the choice of the integer 1,578,127,215 as the
317 startup value. It was chosen arbitrarily with no rationale.}
318 It is not possible to set the internal
319 seed to an arbitrary desired value. The single internal seed value is adequate
320 for most applications which simply require random numbers. If an
321 application requires control over the seed or requires multiple seeds, the ability
322 of this extension to generate the successor of an integer using
323 (\ref{cxtn0:rngPwrResRndA:eq00}) can be used to achieve this functionality in a
324 script.
325
326
327 \tclcommanddescsynopsisline{rngPwrResRndA}{}
328 \begin{tclcommandinternaldescription}
329 Buffers the current seed for a return value, then advances this seed using
330 (\ref{cxtn0:rngPwrResRndA:eq00}). Note that the ``old'' value is the value
331 returned, so that after Tcl/Tk startup the first value
332 returned will be 1,578,127,215.
333 \end{tclcommandinternaldescription}
334
335 \tclcommanddescsynopsisline{rngPwrResRndA}{$N$}
336 \begin{tclcommandinternaldescription}
337 Forms the successor of $N$ using (\ref{cxtn0:rngPwrResRndA:eq00}) and
338 returns this successor. The single internal seed value is not affected.
339 \end{tclcommandinternaldescription}
340
341 \end{tclcommanddescription}
342
343
344 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
345 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
346 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
347 \section{Arbitrary-Length Integer Extensions}
348 %Section Tag: SARB0
349 \label{cxtn0:sarb0}
350
351 Starting with Version 1.05 of \emph{The Iju Tool Set}, \emph{IjuScripter} and
352 \emph{IjuConsole} contain a limited\footnote{By \emph{limited} we mean that
353 the library was consolidated and simplified. The GNU MP library has as its
354 explicit design goal speed over clarity, and uses many advanced algorithms,
355 such as Karatsuba multiplication and special algorithms for the
356 greatest common divisor of integers. The library was simplified to regain
357 clarity at the expense of efficiency before its incorporation into
358 \emph{The Iju Tool Set}.} version of the
359 \index{GNU!Multiple Precision Arithmetic Library (GMP)}\emph{GNU Multiple Precision
360 Library} \cite{bibref:s:gnumultipleprecisionarithmeticlibrary}.
361 The version of the library incorporated into the tools has been
362 modified not to process integers larger than about 100,000 decimal digits.
363 We feel that this limit is sufficiently high for any practical applications,
364 and also that the computational speed will become unbearable long before the
365 data size limit is approached.
366
367
368 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
369 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
370 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
371 \subsection{Error And Overflow Behavior Of Arbitrary-Length Integer Extensions}
372 %Subsection Tag: EAB0
373 \label{cxtn0:sarb0:seab0}
374
375 The underlying data structure of arbitrary-length integers includes flags
376 to indicate that an arithmetic error has occured. Essentially, these flags are
377 ``NAN'', or ``not-a-number'' flags. They indicate that the result is not
378 an integer. These error flags propagate. Combining a NAN value with a
379 valid integer through a binary operation always results in a NAN value. Naturally,
380 the result of a unary operation on a NAN value is also a NAN value.
381 The nature of NAN propagation is that the first arithmetic operation that
382 creates an error using valid integers as input will generate an overflow error (one of
383 the first two flags listed below).
384 Subsequent operations that use these original errors as input will generate
385 outputs which are ``taint'' errors (the second set of two flags listed below).
386
387 At the lowest level (in the innards of the `C' code), these flags are
388 bits within an integer. However, for use within Tcl (where all data is string data), these
389 error flags are assigned symbolic strings to indicate the nature of the error. Note that the
390 error flags are only approximate---they don't \emph{precisely} indicate the
391 nature of the error. However, combined with propagation mechanisms,
392 they are adequate to prevent the interpretation
393 of invalid data as valid data. Any result that is predicated on an invalid
394 result will itself be invalid.
395
396 The four possible error strings are enumerated below. If any Tcl long integer
397 function creates an erroneous result, the result will be assigned one of these
398 four symbolic error strings rather than a string of digits.
399
400 \begin{itemize}
401 \item \index{GMP\_INTS\_EF\_INTOVF\_POS@\texttt{GMP\_INTS\_EF\_INTOVF\_POS}}
402 \texttt{GMP\_INTS\_EF\_INTOVF\_POS}---the result is too positive (i.e. too
403 large in a positive direction). This error flag is also produced
404 by an attempted division by zero, regardless of the sign of the
405 dividend.
406 \item \index{GMP\_INTS\_EF\_INTOVF\_NEG@\texttt{GMP\_INTS\_EF\_INTOVF\_NEG}}
407 \texttt{GMP\_INTS\_EF\_INTOVF\_NEG}---the result is too negative (i.e. too
408 large in a negative direction).
409 \item \index{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS@\texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS}}
410 \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS}---the result has been ``tainted''
411 by combination with an integer which has the
412 \texttt{GMP\_INTS\_EF\_INTOVF\_POS} flag set.
413 \item \index{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG@\texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG}}
414 \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG}---the result has been
415 ``tainted'' by combination with an integer which has the
416 \texttt{GMP\_INTS\_EF\_INTOVF\_NEG} flag set.
417 \end{itemize}
418
419 Note that the functions which operate on arbitrary length integers will
420 never produce an exception or a fatal error. Instead, they will mark
421 results as NAN, and these NAN results will propagate.
422 This mechanism provides for graceful failures, and also allows complex
423 calculations to be performed without the necessity of checking for
424 errors after every calculation step.
425
426 Note also that each of the separate arbitrary-length integer extensions described
427 in this section are a ``sub-extension'' to the \texttt{arbint} extension. It
428 should also be noted
429 that many of these extensions perform the same function as a DOS
430 utility with the same name (see Chapter \cdcmzeroxrefhyphen{}\ref{cdcm0}).
431
432
433 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
434 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
435 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
436 \subsection{The \texttt{arbint iseflag} Extension}
437
438 \index{arbint iseflag@\emph{arbint iseflag}}
439 \index{iseflag@\emph{iseflag}}
440 \begin{tclcommandname}{arbint iseflag}%
441 identifies a string as an arbitrary integer error flag (or not) and
442 returns an integer value categorizing the string.
443 \end{tclcommandname}
444
445 \begin{tclcommandsynopsis}
446 \tclcommandsynopsisline{arbint iseflag }{stringarg}
447 \end{tclcommandsynopsis}
448
449 \begin{tclcommanddescription}
450 This extension returns:
451 \begin{itemize}
452 \item ``0'' if the string argument supplied is not a recognized
453 error flag.
454 \item ``1'' if the string argument supplied is recognized as the\\
455 \texttt{GMP\_INTS\_EF\_INTOVF\_POS}
456 error flag.
457 \item ``2'' if the string argument supplied is recognized as the\\
458 \texttt{GMP\_INTS\_EF\_INTOVF\_NEG}
459 error flag.
460 \item ``3'' if the string argument supplied is recognized as the\\
461 \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS}
462 error flag.
463 \item ``4'' if the string argument supplied is recognized as the\\
464 \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG}
465 error flag.
466 \end{itemize}
467
468 This extension is most often used to classify the output of an
469 arbitrary-length integer operation. All valid integers will create
470 a value of zero if passed to this extension as an argument.
471 \end{tclcommanddescription}
472
473 \begin{tclcommandsampleinvocations}
474 \begin{scriptsize}
475 \begin{verbatim}
476 % arbint iseflag GMP_INTS_EF_INTOVF_NEG
477 2
478 % arbint iseflag 249,422
479 0
480 \end{verbatim}
481 \end{scriptsize}
482 \end{tclcommandsampleinvocations}
483
484 \begin{tclcommandseealso}
485 See also Section \ref{cxtn0:sarb0:seab0}.
486 \end{tclcommandseealso}
487
488
489 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
490 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
491 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
492 \subsection{The \texttt{arbint commanate} Extension}
493 %Subsection Tag: COM0
494 \label{cxtn0:sarb0:scom0}
495
496 \index{arbint commanate@\emph{arbint commanate}}
497 \index{commanate@\emph{commanate}}
498 \begin{tclcommandname}{arbint commanate}%
499 inserts comma characters (`,') into a string as necessary to
500 make it a properly formatted integer with commas.
501 \end{tclcommandname}
502
503 \begin{tclcommandsynopsis}
504 \tclcommandsynopsisline{arbint commanate}{sint}
505 \end{tclcommandsynopsis}
506
507 \begin{tclcommanddescription}
508 This extension adds commas to an integer to make it a properly
509 formatted integer with commas. This extension is normally used to
510 format a string for more ``human-friendly'' output. The input to this extension
511 must be either:
512
513 \begin{itemize}
514 \item A integer with no commas, as a string of digits (i.e.
515 scientific notation is not allowed). The only valid representation
516 for zero is ``0''.
517 \item An integer with all commas properly placed (i.e. it is
518 allowed to ``recommanate'' an integer that is already
519 ``commanated'').
520 \item One of the four symbolic NAN strings described in
521 Section \ref{cxtn0:sarb0:seab0}. (Such a string
522 will not be modified and will be returned unmodified from
523 this extension.)
524 \end{itemize}
525
526 Any string that cannot be parsed as described above will result in
527 an error.
528 \end{tclcommanddescription}
529
530 \begin{tclcommandsampleinvocations}
531 \begin{scriptsize}
532 \begin{verbatim}
533 % arbint intfac 129
534 4974504222477287440390234150412680963965661113713884314596886402265216893219635
535 5119328515747917449637889876686464600208839390308261862352651828829226610077151
536 044469167497022952331930501120000000000000000000000000000000
537 % arbint commanate [arbint intfac 129]
538 49,745,042,224,772,874,403,902,341,504,126,809,639,656,611,137,138,843,145,968,
539 864,022,652,168,932,196,355,119,328,515,747,917,449,637,889,876,686,464,600,208
540 ,839,390,308,261,862,352,651,828,829,226,610,077,151,044,469,167,497,022,952,33
541 1,930,501,120,000,000,000,000,000,000,000,000,000,000
542 % arbint commanate GMP_INTS_EF_INTOVF_POS
543 GMP_INTS_EF_INTOVF_POS
544 \end{verbatim}
545 \end{scriptsize}
546 \end{tclcommandsampleinvocations}
547
548
549 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
550 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
551 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
552 \subsection{The \texttt{arbint decommanate} Extension}
553 %Subsection Tag: dco0
554 \label{cxtn0:sarb0:sdco0}
555
556 \index{arbint decommanate@\emph{arbint decommanate}}
557 \index{decommanate@\emph{decommanate}}
558 \begin{tclcommandname}{arbint decommanate}%
559 removes comma characters (`,') from a properly
560 formatted integer.
561 \end{tclcommandname}
562
563 \begin{tclcommandsynopsis}
564 \tclcommandsynopsisline{arbint decommanate}{sint}
565 \end{tclcommandsynopsis}
566
567 \begin{tclcommanddescription}
568 This extension removes commas from a properly formatted integer.
569 The input to this extension
570 must be either:
571
572 \begin{itemize}
573 \item A integer with no commas, as a string of digits (i.e.
574 scientific notation is not allowed). The only valid representation
575 for zero is ``0''. (Note that it is allowed to ``decommanate''
576 an integer that contains no commas.)
577 \item An integer with all commas properly placed.
578 \item One of the four symbolic NAN strings described in
579 Section \ref{cxtn0:sarb0:seab0}. (Such a string
580 will not be modified and will be returned unmodified from
581 this extension.)
582 \end{itemize}
583
584 Any string that cannot be parsed as described above will result in
585 an error.
586 \end{tclcommanddescription}
587
588 \begin{tclcommandsampleinvocations}
589 \begin{scriptsize}
590 \begin{verbatim}
591 % arbint intfac 129
592 4974504222477287440390234150412680963965661113713884314596886402265216893219635
593 5119328515747917449637889876686464600208839390308261862352651828829226610077151
594 044469167497022952331930501120000000000000000000000000000000
595 % arbint commanate [arbint intfac 129]
596 49,745,042,224,772,874,403,902,341,504,126,809,639,656,611,137,138,843,145,968,
597 864,022,652,168,932,196,355,119,328,515,747,917,449,637,889,876,686,464,600,208
598 ,839,390,308,261,862,352,651,828,829,226,610,077,151,044,469,167,497,022,952,33
599 1,930,501,120,000,000,000,000,000,000,000,000,000,000
600 % set number [arbint commanate [arbint intfac 129]]
601 49,745,042,224,772,874,403,902,341,504,126,809,639,656,611,137,138,843,145,968,
602 864,022,652,168,932,196,355,119,328,515,747,917,449,637,889,876,686,464,600,208
603 ,839,390,308,261,862,352,651,828,829,226,610,077,151,044,469,167,497,022,952,33
604 1,930,501,120,000,000,000,000,000,000,000,000,000,000
605 % arbint decommanate $number
606 4974504222477287440390234150412680963965661113713884314596886402265216893219635
607 5119328515747917449637889876686464600208839390308261862352651828829226610077151
608 044469167497022952331930501120000000000000000000000000000000
609 % arbint decommanate GMP_INTS_EF_INTOVF_POS
610 GMP_INTS_EF_INTOVF_POS
611 \end{verbatim}
612 \end{scriptsize}
613 \end{tclcommandsampleinvocations}
614
615 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
616 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
617 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
618 \subsection{The \texttt{arbint intcmp} Extension}
619 %Subsection Tag: add0
620 \label{cxtn0:sarb0:scmp0}
621
622 \index{arbint intcmp@\emph{arbint intcmp}}
623 \index{intcmp@\emph{intcmp}}
624 \begin{tclcommandname}{arbint intcmp}%
625 compares two arbitrary integers and returns a result indicating their relative
626 ordering.
627 \end{tclcommandname}
628
629 \begin{tclcommandsynopsis}
630 \tclcommandsynopsisline{arbint intcmp}{sint\_a sint\_b}
631 \end{tclcommandsynopsis}
632
633 \begin{tclcommanddescription}
634 This extension compares \emph{sint\_a} and \emph{sint\_b} and
635 returns $\{-1, 0, 1\}$ if
636 \emph{sint\_a} $\{ <, =, > \}$ \emph{sint\_b}. This extension
637 is used to compare arbitrarily large integers in Tcl scripts.
638 Because NAN tags (see Section \ref{cxtn0:sarb0:seab0})
639 cannot be logically compared,
640 this extension will signal an error if either parameter is
641 a NAN tag.
642 \end{tclcommanddescription}
643
644 \begin{tclcommandsampleinvocations}
645 \begin{scriptsize}
646 \begin{verbatim}
647 % arbint intcmp -5 -3
648 -1
649 % arbint intcmp -5 -5
650 0
651 % arbint intcmp 7 5
652 1
653 \end{verbatim}
654 \end{scriptsize}
655 \end{tclcommandsampleinvocations}
656
657 \begin{tclcommandseealso}
658 See also the \emph{arbint rncmp} Tcl extension,
659 Section \ref{cxtn0:srne0:srcm0}, which performs a similar
660 function for arbitrary rational numbers.
661 \end{tclcommandseealso}
662
663
664 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
665 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
666 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
667 \subsection{The \texttt{arbint intadd} Extension}
668 %Subsection Tag: add0
669 \label{cxtn0:sarb0:sadd0}
670
671 \index{arbint intadd@\emph{arbint intadd}}
672 \index{intadd@\emph{intadd}}
673 \begin{tclcommandname}{arbint intadd}%
674 calculates and returns as a string the sum of two integers.
675 \end{tclcommandname}
676
677 \begin{tclcommandsynopsis}
678 \tclcommandsynopsisline{arbint intadd}{sint sint}
679 \end{tclcommandsynopsis}
680
681 \begin{tclcommanddescription}
682 This extension returns the sum of two integer
683 arguments, or one of the NAN tags described in
684 Section \ref{cxtn0:sarb0:seab0} if an overflow occurs.
685 \end{tclcommanddescription}
686
687 \begin{tclcommandsampleinvocations}
688 \begin{scriptsize}
689 \begin{verbatim}
690 % arbint intadd 1e20 21643215482123164
691 100021643215482123164
692 \end{verbatim}
693 \end{scriptsize}
694 \end{tclcommandsampleinvocations}
695
696 \begin{tclcommandseealso}
697 See also the \emph{intadd} DOS command-line utility,
698 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sadd0}.
699 \end{tclcommandseealso}
700
701 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
702 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
703 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
704 \subsection{The \texttt{arbint intsub} Extension}
705 %Subsection Tag: mod0
706 \label{cxtn0:sarb0:ssub0}
707
708 \index{arbint intsub@\emph{arbint intsub}}
709 \index{intsub@\emph{intsub}}
710 \begin{tclcommandname}{arbint intsub}%
711 calculates and returns as a string the difference of two integers.
712 \end{tclcommandname}
713
714 \begin{tclcommandsynopsis}
715 \tclcommandsynopsisline{arbint intsub}{sint sint}
716 \end{tclcommandsynopsis}
717
718 \begin{tclcommanddescription}
719 This extension returns the difference of two integer
720 arguments, or one of the NAN tags described in
721 Section \ref{cxtn0:sarb0:seab0} if an overflow occurs.
722 \end{tclcommanddescription}
723
724 \begin{tclcommandsampleinvocations}
725 \begin{scriptsize}
726 \begin{verbatim}
727 % arbint intsub 123846129436219 1e25
728 -9999999999876153870563781
729 \end{verbatim}
730 \end{scriptsize}
731 \end{tclcommandsampleinvocations}
732
733 \begin{tclcommandseealso}
734 See also the \emph{intsub} DOS command-line utility,
735 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:ssub0}.
736 \end{tclcommandseealso}
737
738
739 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
740 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
741 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
742 \subsection{The \texttt{arbint intmul} Extension}
743 %Subsection Tag: mul0
744 \label{cxtn0:sarb0:smul0}
745
746 \index{arbint intmul@\emph{arbint intmul}}
747 \index{intmul@\emph{intmul}}
748 \begin{tclcommandname}{arbint intmul}%
749 calculates and returns as a string the product of two integers.
750 \end{tclcommandname}
751
752 \begin{tclcommandsynopsis}
753 \tclcommandsynopsisline{arbint intmul}{sint sint}
754 \end{tclcommandsynopsis}
755
756 \begin{tclcommanddescription}
757 This extension returns the product of two integer arguments.
758 The result of this
759 extension will always be either a NAN tag
760 (see Section \ref{cxtn0:sarb0:seab0})
761 or an integer.
762 \end{tclcommanddescription}
763
764 \begin{tclcommandsampleinvocations}
765 \begin{scriptsize}
766 \begin{verbatim}
767 % arbint intmul -329749813264962165493214963541976325 4.36463214521843123e38
768 -143923663485602892702423181098245942606484617030062975000000000000000000000
769 \end{verbatim}
770 \end{scriptsize}
771 \end{tclcommandsampleinvocations}
772
773 \begin{tclcommandseealso}
774 See also the \emph{intmul} DOS command-line utility,
775 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:smul0}.
776 \end{tclcommandseealso}
777
778
779 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
780 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
781 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
782 \subsection{The \texttt{arbint intdiv} Extension}
783 %Subsection Tag: div0
784 \label{cxtn0:sarb0:sdiv0}
785
786 \index{arbint intdiv@\emph{arbint intdiv}}
787 \index{intdiv@\emph{intdiv}}
788 \begin{tclcommandname}{arbint intdiv}%
789 calculates and returns as a string the quotient of two integers.
790 \end{tclcommandname}
791
792 \begin{tclcommandsynopsis}
793 \tclcommandsynopsisline{arbint intdiv}{sint\_dividend sint\_divisor}
794 \end{tclcommandsynopsis}
795
796 \begin{tclcommanddescription}
797 This extension returns the quotient of two integer arguments.
798 The first integer argument is interpreted to be the dividend,
799 and the second the divisor. The quotient is without remainder,
800 i.e. what is actually returned is
801
802 \begin{equation}
803 sgn(dividend \cdot divisor)
804 \left\lfloor{\frac{|dividend|}{|divisor|}}\right\rfloor ,
805 \end{equation}
806
807 or one of the NAN tags described in
808 Section \ref{cxtn0:sarb0:seab0}
809 if division by zero is attempted. Note that division
810 by zero is not an error (as far as a Tcl script is concerned):
811 the only outcome is that the result will be assigned a symbolic
812 NAN tag rather than a string of digits representing an integer.
813 \end{tclcommanddescription}
814
815 \begin{tclcommandsampleinvocations}
816 \begin{scriptsize}
817 \begin{verbatim}
818 % arbint intdiv 2364832165653218648321543215848236458124 2854871354812543821
819 828349817467869034672
820 % arbint intdiv 2364832165653218648321543215848236458124 0
821 GMP_INTS_EF_INTOVF_POS
822 \end{verbatim}
823 \end{scriptsize}
824 \end{tclcommandsampleinvocations}
825
826 \begin{tclcommandseealso}
827 See also the \emph{intdiv} DOS command-line utility,
828 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sdiv0}.
829 \end{tclcommandseealso}
830
831
832 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
833 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
834 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
835 \subsection{The \texttt{arbint intmod} Extension}
836 %Subsection Tag: mod0
837 \label{cxtn0:sarb0:smod0}
838
839 \index{arbint intmod@\emph{arbint intmod}}
840 \index{intmod@\emph{intmod}}
841 \begin{tclcommandname}{arbint intmod}%
842 calculates and returns as a string the modulo of two integers.
843 \end{tclcommandname}
844
845 \begin{tclcommandsynopsis}
846 \tclcommandsynopsisline{arbint intmod}{sint\_dividend sint\_divisor}
847 \end{tclcommandsynopsis}
848
849 \begin{tclcommanddescription}
850 This extension returns the remainder resulting from the
851 division of two integer arguments.
852 The first integer argument is interpreted to be the dividend,
853 and the second the divisor. The sign of the remainder is always
854 chosen so that the following relationship holds:
855
856 \begin{equation}
857 dividend \; div \; divisor + \frac{dividend \; mod \; divisor}{divisor}
858 = \frac{dividend}{divisor},
859 \end{equation}
860
861 where the \emph{div} operator is as explained in Section
862 \ref{cxtn0:sarb0:sdiv0} for the \emph{arbint intdiv} extension.
863 If division by zero is attempted, this extension
864 returns one of the NAN tags described in
865 Section \ref{cxtn0:sarb0:seab0}. Note that division
866 by zero is not an error (as far as a Tcl script is concerned):
867 the only outcome is that the result will be assigned a symbolic
868 NAN tag rather than a string of digits representing an integer.
869 \end{tclcommanddescription}
870
871 \begin{tclcommandsampleinvocations}
872 \begin{scriptsize}
873 \begin{verbatim}
874 % arbint intmod 264321654632432421 2175438321654
875 1547674828113
876 % arbint intmod 264321654632432421 0
877 GMP_INTS_EF_INTOVF_POS
878 \end{verbatim}
879 \end{scriptsize}
880 \end{tclcommandsampleinvocations}
881
882 \begin{tclcommandseealso}
883 See also the \emph{intmod} DOS command-line utility,
884 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:smod0}.
885 \end{tclcommandseealso}
886
887
888 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
889 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
890 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
891 \subsection{The \texttt{arbint intexp} Extension}
892 %Subsection Tag: exp0
893 \label{cxtn0:sarb0:sixp0}
894
895 \index{arbint intexp@\emph{arbint intexp}}
896 \index{intexp@\emph{intexp}}
897 \begin{tclcommandname}{arbint intexp}%
898 computes and returns as a string one integer
899 exponentiated to the power of another,
900 $base^{exponent}$.
901
902 \end{tclcommandname}
903
904 \begin{tclcommandsynopsis}
905 \tclcommandsynopsisline{arbint intexp}{sint\_base uint32\_exponent}
906 \end{tclcommandsynopsis}
907
908 \begin{tclcommanddescription}
909 This extension exponentiates an integer to a non-negative
910 power. For
911 simplicity and convenience, $0^0$ will return 1, although
912 this is inconsistent with the mathematical definition.
913 All other exponentiations are as expected.
914
915 The method used to exponentiate is simple squaring and multiplying
916 based on the bit pattern of the exponent, as discussed
917 in \cite{bibref:b:knuthclassic2ndedvol2}, pp. 461-462.
918 \end{tclcommanddescription}
919
920 \begin{tclcommandsampleinvocations}
921 \begin{scriptsize}
922 \begin{verbatim}
923 % arbint intexp 47 69
924 2370021018513446695324337468306899241173950476009917473665218657220346081293500
925 4143894985892600403244809901800125167
926 % arbint intexp 1 0
927 1
928 % arbint intexp 0 0
929 1
930 % arbint intexp 0 1
931 0
932 % arbint intexp 0 19237498
933 0
934 % arbint intexp -47 69
935 -237002101851344669532433746830689924117395047600991747366521865722034608129350
936 04143894985892600403244809901800125167
937 % arbint intexp -47 -69
938 arbint intexp: "-69" is not a recognized unsigned 32-bit integer.
939 % arbint intexp 193461926436214 99999999
940 GMP_INTS_EF_INTOVF_TAINT_POS
941 \end{verbatim}
942 \end{scriptsize}
943 \end{tclcommandsampleinvocations}
944
945 \begin{tclcommandseealso}
946 See also the \emph{intexp} DOS command-line utility,
947 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sixp0}.
948 \end{tclcommandseealso}
949
950
951 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
952 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
953 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
954 \subsection{The \texttt{arbint intfac} Extension}
955 %Subsection Tag: fac0
956 \label{cxtn0:sarb0:sfac0}
957
958 \index{arbint intfac@\emph{arbint intfac}}
959 \index{intfac@\emph{intfac}}
960 \begin{tclcommandname}{arbint intfac}%
961 computes and returns as a string the factorial ($!$) of
962 the integer argument supplied.
963 \end{tclcommandname}
964
965 \begin{tclcommandsynopsis}
966 \tclcommandsynopsisline{arbint intfac}{uint32}
967 \end{tclcommandsynopsis}
968
969 \begin{tclcommanddescription}
970 This extension returns the factorial of an integer argument.
971 Any of the symbolic NAN strings described in
972 Section \ref{cxtn0:sarb0:seab0} will cause a return
973 value of an appropriate symbolic NAN string.
974 Strings that cannot be parsed as integers or
975 NAN strings, strings
976 that represent negative integers, and strings that represent
977 non-negative integers that will not fit in 32 bits will generate
978 an error.
979
980 As of this writing, 200! requires about 1 second to compute on a
981 600MHz PC. Although this function will calculate factorials of any size
982 up to 100,000 digits, it is not recommended to use this function above
983 about 200! as the increase in computation time appears to be exponential
984 with respect to the argument. This may improve in the future as algorithmic
985 enhancements are made.
986 \end{tclcommanddescription}
987
988 \begin{tclcommandsampleinvocations}
989 \begin{scriptsize}
990 \begin{verbatim}
991 % arbint intfac 129
992 4974504222477287440390234150412680963965661113713884314596886402265216893219635
993 5119328515747917449637889876686464600208839390308261862352651828829226610077151
994 044469167497022952331930501120000000000000000000000000000000
995 \end{verbatim}
996 \end{scriptsize}
997 \end{tclcommandsampleinvocations}
998
999 \begin{tclcommandseealso}
1000 See also the \emph{intfac} DOS command-line utility,
1001 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sifc0}.
1002 \end{tclcommandseealso}
1003
1004
1005 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1006 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1007 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1008 \subsection{The \texttt{arbint intgcd} Extension}
1009 %Subsection Tag: gcd0
1010 \label{cxtn0:sarb0:sgcd0}
1011
1012 \index{arbint intgcd@\emph{arbint intgcd}}
1013 \index{intgcd@\emph{intgcd}}
1014 \begin{tclcommandname}{arbint intgcd}%
1015 calculates and returns as a string the g.c.d.
1016 (greatest common divisor) of two integers.
1017 \end{tclcommandname}
1018
1019 \begin{tclcommandsynopsis}
1020 \tclcommandsynopsisline{arbint intgcd}{sint sint}
1021 \end{tclcommandsynopsis}
1022
1023 \begin{tclcommanddescription}
1024 This extension returns the g.c.d. of two integer arguments.
1025 If either argument is 0, the result will be 1. If either
1026 argument is negative, the absolute value of the argument
1027 will be used in its place. The result of this
1028 extension will always be either a NAN tag
1029 (see Section \ref{cxtn0:sarb0:seab0})
1030 or an integer greater than or equal to 1.
1031
1032 The algorithm employed is the
1033 \emph{Modern Euclidian Algorithm} as
1034 described in \cite{bibref:b:knuthclassic2ndedvol2}, p. 337.
1035 Although faster algorithms for computer
1036 implementation do exist, this is the simplest
1037 and most direct algorithm.
1038 \end{tclcommanddescription}
1039
1040 \begin{tclcommandsampleinvocations}
1041 \begin{scriptsize}
1042 \begin{verbatim}
1043 % arbint intgcd 263130836933693530167218012160000000 503580
1044 4620
1045 \end{verbatim}
1046 \end{scriptsize}
1047 \end{tclcommandsampleinvocations}
1048
1049 \begin{tclcommandseealso}
1050 See also the \emph{intgcd} DOS command-line utility,
1051 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sgcd0}.
1052 \end{tclcommandseealso}
1053
1054
1055 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1056 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1057 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1058 \subsection{The \texttt{arbint intlcm} Extension}
1059 %Subsection Tag: lcm0
1060 \label{cxtn0:sarb0:slcm0}
1061
1062 \index{arbint intgcd@\emph{arbint intlcm}}
1063 \index{intlcm@\emph{intlcm}}
1064 \begin{tclcommandname}{arbint intlcm}%
1065 calculates and returns as a string the l.c.m.
1066 (least common multiple) of two integers.
1067 \end{tclcommandname}
1068
1069 \begin{tclcommandsynopsis}
1070 \tclcommandsynopsisline{arbint intlcm}{sint sint}
1071 \end{tclcommandsynopsis}
1072
1073 \begin{tclcommanddescription}
1074 This extension returns the l.c.m. of two integer arguments.
1075 If either argument is 0, the argument will be treated as if it
1076 were 1. If either
1077 argument is negative, the absolute value of the argument
1078 will be used in its place. The result of this
1079 extension will always be either a NAN tag
1080 (see Section \ref{cxtn0:sarb0:seab0})
1081 or an integer greater than or equal to 1.
1082
1083 The algorithm employed is to calculate
1084 the g.c.d. of the arguments using the
1085 \emph{Modern Euclidian Algorithm} as
1086 described in \cite{bibref:b:knuthclassic2ndedvol2}, p. 337;
1087 then to divide the product of the arguments by their
1088 g.c.d., as implied by \cite{bibref:b:knuthclassic2ndedvol2},
1089 p. 334, Equation 10. Both sides of this equation can be
1090 divided by $\gcd(u,v)$ to yield
1091
1092 \begin{equation}
1093 lcm(u,v) = \frac{uv}{\gcd(u,v)},
1094 \end{equation}
1095
1096 and this is the relationship used to calculated the l.c.m.
1097 \end{tclcommanddescription}
1098
1099 \begin{tclcommandsampleinvocations}
1100 \begin{scriptsize}
1101 \begin{verbatim}
1102 % arbint intlcm 64 100
1103 1600
1104 \end{verbatim}
1105 \end{scriptsize}
1106 \end{tclcommandsampleinvocations}
1107
1108 \begin{tclcommandseealso}
1109 See also the \emph{intlcm} DOS command-line utility,
1110 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:slcm0}.
1111 \end{tclcommandseealso}
1112
1113
1114 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1115 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1116 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1117 \section{Rational Number Extensions}
1118 %Section Tag: RNE0
1119
1120 This section describes extensions that implement
1121 rational number arithmetic.
1122
1123 In most cases, the rational number extensions described in
1124 this section are liberal in the representations of rational numbers
1125 they accept, but always produce results as integer components
1126 separated by the forward slash character. This means that the
1127 rational number extensions described in this section can exchange data
1128 freely---the output of any of the extensions is suitable as input
1129 for another extension.
1130
1131
1132 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1133 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1134 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1135 \subsection{The \texttt{arbint rnred} Extension}
1136 %Subsection Tag: RNR0
1137 \label{cxtn0:srne0:srnr0}
1138
1139 \index{arbint rnred@\emph{arbint rnred}}
1140 \index{rnred@\emph{rnred}}
1141 \begin{tclcommandname}{arbint rnred}%
1142 reduces a rational number to lowest terms and normalizes it.
1143 \end{tclcommandname}
1144
1145 \begin{tclcommandsynopsis}
1146 \tclcommandsynopsisline{arbint rnred}{srn}
1147 \end{tclcommandsynopsis}
1148
1149 \begin{tclcommanddescription}
1150 The \emph{arbint rnred} extension reduces a rational number to its lowest terms
1151 and normalizes it. By \emph{reducing} a rational number and
1152 normalizing it, we mean the application of the following rules.
1153
1154 \begin{enumerate}
1155 \item Any number with a numerator of zero is given the
1156 representation 0/1, i.e. 0/1 is the canonical
1157 representation of zero.
1158 \item Any number with a denominator of zero is given
1159 the representation 1/0, i.e. 1/0 is the canonical
1160 representation of ``division by zero''.
1161 \item Rational numbers which are effectively positive
1162 are normalized to have a positve numerator and positive
1163 denominator.
1164 \item Rational numbers which are effectively negative are
1165 normalized to have a negative numerator and positive
1166 denominator.
1167 \item Any common factors are removed from the numerator and
1168 denominator, i.e. the numerator and denominator are
1169 made coprime.
1170 \end{enumerate}
1171
1172 Note that one behavior above may be unexpected---the
1173 \emph{arbint rnred} extension \emph{will} accept a rational number
1174 specified with a denominator of zero, and will normalize it to
1175 1/0.
1176 \end{tclcommanddescription}
1177
1178 \begin{tclcommandsampleinvocations}
1179 \begin{scriptsize}
1180 \begin{verbatim}
1181 % arbint rnred 422.414
1182 211207/500
1183 \end{verbatim}
1184 \end{scriptsize}
1185 \end{tclcommandsampleinvocations}
1186
1187 \begin{tclcommandseealso}
1188 See also the \emph{rnred} DOS command-line utility,
1189 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srnr0}.
1190 \end{tclcommandseealso}
1191
1192 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1193 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1194 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1195 \subsection{The \texttt{arbint rnadd} Extension}
1196 %Subsection Tag: RAD0
1197 \label{cxtn0:srne0:srad0}
1198
1199 \index{arbint rnadd@\emph{arbint rnadd}}
1200 \index{rnadd@\emph{rnadd}}
1201 \begin{tclcommandname}{arbint rnadd}%
1202 adds two rational numbers to produce a normalized rational result.
1203 \end{tclcommandname}
1204
1205 \begin{tclcommandsynopsis}
1206 \tclcommandsynopsisline{arbint rnadd}{srn srn}
1207 \end{tclcommandsynopsis}
1208
1209 \begin{tclcommanddescription}
1210 The \emph{arbint rnadd} extension adds two rational numbers to produce a
1211 normalized rational result.
1212
1213 If either of the two rational input arguments has a denominator of zero,
1214 the string ``NAN'' will be returned.
1215 \end{tclcommanddescription}
1216
1217 \begin{tclcommandsampleinvocations}
1218 \begin{scriptsize}
1219 \begin{verbatim}
1220 % arbint rnadd 3.1415 64/259
1221 1755297/518000
1222 \end{verbatim}
1223 \end{scriptsize}
1224 \end{tclcommandsampleinvocations}
1225
1226 \begin{tclcommandseealso}
1227 See also the \emph{rnadd} DOS command-line utility,
1228 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srna0}.
1229 \end{tclcommandseealso}
1230
1231
1232 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1233 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1234 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1235 \subsection{The \texttt{arbint rnsub} Extension}
1236 %Subsection Tag: RSB0
1237 \label{cxtn0:srne0:srsb0}
1238
1239 \index{arbint rnsub@\emph{arbint rnsub}}
1240 \index{rnsub@\emph{rnsub}}
1241 \begin{tclcommandname}{arbint rnsub}%
1242 subtracts two rational numbers to produce a normalized rational result.
1243 \end{tclcommandname}
1244
1245 \begin{tclcommandsynopsis}
1246 \tclcommandsynopsisline{arbint rnsub}{srn\_arg1 srn\_arg2}
1247 \end{tclcommandsynopsis}
1248
1249 \begin{tclcommanddescription}
1250 The \emph{arbint rnsub} extension subtracts two rational numbers to produce a
1251 normalized rational result. The second argument is subtracted from the first, i.e.
1252 the result $arg_2 - arg_1$ is formed.
1253
1254 If either of the two rational input arguments has a denominator of zero,
1255 the string ``NAN'' will be returned.
1256 \end{tclcommanddescription}
1257
1258 \begin{tclcommandsampleinvocations}
1259 \begin{scriptsize}
1260 \begin{verbatim}
1261 % arbint rnsub 3.129 122/451
1262 1289179/451000
1263 \end{verbatim}
1264 \end{scriptsize}
1265 \end{tclcommandsampleinvocations}
1266
1267 \begin{tclcommandseealso}
1268 See also the \emph{rnsub} DOS command-line utility,
1269 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srsb0}.
1270 \end{tclcommandseealso}
1271
1272 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1273 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1274 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1275 \subsection{The \texttt{arbint rnmul} Extension}
1276 %Subsection Tag: RMU0
1277 \label{cxtn0:srne0:srmu0}
1278
1279 \index{arbint rnmul@\emph{arbint rnmul}}
1280 \index{rnmul@\emph{rnmul}}
1281 \begin{tclcommandname}{arbint rnmul}%
1282 multiplies two rational numbers to produce a normalized rational result.
1283 \end{tclcommandname}
1284
1285 \begin{tclcommandsynopsis}
1286 \tclcommandsynopsisline{arbint rnmul}{srn srn}
1287 \end{tclcommandsynopsis}
1288
1289 \begin{tclcommanddescription}
1290 The \emph{arbint rnmul} extension multiplies two rational numbers to produce a
1291 normalized rational result.
1292
1293 If either of the two rational input arguments has a denominator of zero,
1294 the string ``NAN'' will be returned.
1295 \end{tclcommanddescription}
1296
1297 \begin{tclcommandsampleinvocations}
1298 \begin{scriptsize}
1299 \begin{verbatim}
1300 % arbint rnmul 3.14 32/491
1301 2512/12275
1302 \end{verbatim}
1303 \end{scriptsize}
1304 \end{tclcommandsampleinvocations}
1305
1306 \begin{tclcommandseealso}
1307 See also the \emph{rnmul} DOS command-line utility,
1308 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srmu0}.
1309 \end{tclcommandseealso}
1310
1311
1312 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1313 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1314 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1315 \subsection{The \texttt{arbint rndiv} Extension}
1316 %Subsection Tag: RDV0
1317 \label{cxtn0:srne0:srdv0}
1318
1319 \index{arbint rndiv@\emph{arbint rndiv}}
1320 \index{rndiv@\emph{rndiv}}
1321 \begin{tclcommandname}{arbint rndiv}%
1322 divides two rational numbers to produce a normalized rational result.
1323 \end{tclcommandname}
1324
1325 \begin{tclcommandsynopsis}
1326 \tclcommandsynopsisline{arbint rndiv}{srn srn}
1327 \end{tclcommandsynopsis}
1328
1329 \begin{tclcommanddescription}
1330 The \emph{arbint rndiv} extension divides two rational numbers to produce a
1331 normalized rational result.
1332
1333 If either of the two rational input arguments has a denominator of zero, or
1334 if the divisor is zero,
1335 the string ``NAN'' will be returned.
1336 \end{tclcommanddescription}
1337
1338 \begin{tclcommandsampleinvocations}
1339 \begin{scriptsize}
1340 \begin{verbatim}
1341 % arbint rndiv 3.14 32/491
1342 77087/1600
1343 \end{verbatim}
1344 \end{scriptsize}
1345 \end{tclcommandsampleinvocations}
1346
1347 \begin{tclcommandseealso}
1348 See also the \emph{rnmul} DOS command-line utility,
1349 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srdv0}.
1350 \end{tclcommandseealso}
1351
1352
1353 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1354 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1355 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1356 \subsection{The \texttt{arbint rncmp} Extension}
1357 %Subsection Tag: RCM0
1358 \label{cxtn0:srne0:srcm0}
1359
1360 \index{arbint rncmp@\emph{arbint rncmp}}
1361 \index{rncmp@\emph{rncmp}}
1362 \begin{tclcommandname}{arbint rncmp}%
1363 compares two rational numbers.
1364 \end{tclcommandname}
1365
1366 \begin{tclcommandsynopsis}
1367 \tclcommandsynopsisline{arbint rncmp}{srn\_arg1 srn\_arg2}
1368 \end{tclcommandsynopsis}
1369
1370 \begin{tclcommanddescription}
1371 The \emph{arbint rncmp} extension compares two rational numbers
1372 and returns $\{-1, 0, 1\}$ if $arg_1$
1373 $\{<, =, >\}$ $arg_2$.
1374
1375 The rational numbers do not need to be reduced or normalized in any way.
1376 Any combination of signs on the numerators and denominators is permitted,
1377 and the numerators and denominators are not required to be coprime.
1378
1379 If for any reason the extension cannot compare the rational numbers,
1380 an error message will be returned and the extension will return
1381 \texttt{TCL\_ERROR}, which will normally cause a script to fail.
1382 The reason for the error return is that if the two rational number
1383 cannot be compared, in most cases it is logically impossible for a script to
1384 continue.
1385 \end{tclcommanddescription}
1386
1387 \begin{tclcommandsampleinvocations}
1388 \begin{scriptsize}
1389 \begin{verbatim}
1390 % arbint rncmp -4/-7 0.5
1391 1
1392 \end{verbatim}
1393 \end{scriptsize}
1394 \end{tclcommandsampleinvocations}
1395
1396
1397 \begin{tclcommandseealso}
1398 See also the \emph{arbint intcmp} Tcl extension,
1399 Section \ref{cxtn0:sarb0:scmp0}, which performs a similar
1400 function for arbitrary integers.
1401 \end{tclcommandseealso}
1402
1403
1404 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1405 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1406 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1407 \section{Number Theory Extensions}
1408 %Section Tag: NTH0
1409 \label{cxtn0:snth0}
1410
1411 This section describes extensions that are related to number theory.
1412 Extensions that deal with continued fractions are included in this
1413 category because of the relationship between continued fractions
1414 and number theory. Any extensions related to number theory that
1415 must process large integers are
1416 still a subextension of \texttt{arbint}.\footnote{This was done to
1417 avoid creating an excessive number of software modules and
1418 Tcl extensions.}
1419
1420
1421 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1422 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1423 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1424 \subsection{The \texttt{arbint cfratnum} Extension}
1425 %Subsection Tag: CFR0
1426 \label{cxtn0:snth0:scfr0}
1427
1428 \index{arbint cfratnum@\emph{arbint cfratnum}}
1429 \index{cfratnum@\emph{cfratnum}}
1430 \begin{tclcommandname}{arbint cfratnum}%
1431 calculates the partial quotients and convergents of
1432 a non-negative rational number.
1433 \end{tclcommandname}
1434
1435 \begin{tclcommandsynopsis}
1436 \tclcommandsynopsisline{arbint cfratnum}{urn}
1437 \end{tclcommandsynopsis}
1438
1439 \begin{tclcommanddescription}
1440 This extension calculates the partial quotients and convergents of
1441 of a non-negative rational number. The results are
1442 returned as a string containing integers separated by spaces.
1443 The integers are arranged in consecutive triplets of the form
1444 ``$a_k \; p_k \; q_k$''. Such a string can be converted to a
1445 list and processed from a Tcl script.
1446 \end{tclcommanddescription}
1447
1448 \begin{tclcommandsampleinvocations}
1449 \begin{scriptsize}
1450 \begin{verbatim}
1451 % arbint cfratnum 3.14
1452 3 3 1 7 22 7 7 157 50
1453 \end{verbatim}
1454 \end{scriptsize}
1455
1456 In the sample invocation above, note that $a_0 = 3$,
1457 $p_0 = 3$, $q_0 = 1$, $a_1 = 7$, $p_1 = 22$, $q_1 = 7$,
1458 $a_2 = 7$, $p_2 = 157$, and $q_2 = 50$.
1459 \end{tclcommandsampleinvocations}
1460
1461 \begin{tclcommandseealso}
1462 See also the \emph{cfratnum} DOS command-line utility,
1463 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:snth0:scfr0}.
1464 \end{tclcommandseealso}
1465
1466 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1467 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1468 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1469 \subsection{The \texttt{arbint cfbrapab} Extension}
1470 %Subsection Tag: BRA0
1471 \label{cxtn0:snth0:sbra0}
1472
1473 \index{arbint cfbrapab@\emph{arbint cfbrapab}}
1474 \index{cfbrapab@\emph{cfbrapab}}
1475 \begin{tclcommandname}{arbint cfbrapab}%
1476 finds best rational approximations to a supplied rational
1477 number in either the Farey series of order $k_{MAX}$ (denoted
1478 $F_{k_{MAX}}$), or in a rectangular region of the integer lattice
1479 bounded by $k \leq k_{MAX}$ and $h \leq h_{MAX}$
1480 (denoted $F_{k_{MAX}, \overline{h_{MAX}}}$).
1481 \end{tclcommandname}
1482
1483 \begin{tclcommandsynopsis}
1484 \tclcommandsynopsisline{arbint cfbrapab}{srn uint\_kmax [options]}
1485 \tclcommandsynopsisline{arbint cfbrapab}{srn uint\_kmax uint\_hmax [options]}
1486 \end{tclcommandsynopsis}
1487
1488 \begin{tclcommanddescription}
1489 When used without options, this extension returns the closest rational
1490 number to the specified rational number in $F_{k_{MAX}}$ (if only $k_{MAX}$ is
1491 specified) or in $F_{k_{MAX}, \overline{h_{MAX}}}$ (if both
1492 $k_{MAX}$ and $h_{MAX}$ are specified). If the rational number specified
1493 is already in the series of interest, its reduced form is returned.
1494 If the rational number supplied is equidistant from the two closest
1495 formable rational numbers in the series of interest, the neighbor of smaller
1496 magnitude (absolute value) is returned.
1497
1498 When operating in $F_{k_{MAX}}$, there are no practical constraints
1499 on the size of rational numbers that this extension can approximate.
1500 However, when operating in $F_{k_{MAX}, \overline{h_{MAX}}}$,
1501 this extension will not accept rational numbers outside the
1502 interval $[-h_{MAX}, h_{MAX}]$ (note that $-h_{MAX}/1$ and
1503 $h_{MAX}/1$ are the smallest and largest numbers that can be formed
1504 when the numerator of the rational approximations is constrained).
1505 Any attempt to approximate a rational number outside $[-h_{MAX}, h_{MAX}]$
1506 will result in a Tcl error, which will normally terminate a script.
1507
1508 The \texttt{-neversmaller} and \texttt{-neverlarger}
1509 options cause the extension to always choose the larger and
1510 smaller neighbors (rather than the closer neighbor), respectively.
1511 These options are useful when approximations are desired that
1512 do not underestimate or overestimate the function of interest for
1513 large values in the domain. These parameters do not affect
1514 the behavior if the rational number supplied is already in the
1515 series of interest---the reduced form of the specified number
1516 is returned in the case of equality.
1517 The \texttt{-neversmaller} and \texttt{-neverlarger} options
1518 must be used alone, with no other options.
1519
1520 The \texttt{-pred} and \texttt{-succ} options cause this extension
1521 to calculate either the predecessor or successor to the rational
1522 number specified in the series of interest. If the number specified
1523 is already in series of interest, its predecessor or successor
1524 is returned.
1525 If the number specified is not in the series of interest,
1526 the left or right neighbor is returned. If no predecessor,
1527 successor, or left or right neighbor exist, an error is generated.
1528 These options (\texttt{-pred} or \texttt{-succ})
1529 must be used alone, with no other options.
1530
1531 The normal behavior of this extension is to return a single
1532 rational number, as described above.
1533 The \texttt{-n \emph{uint32\_count}} option will cause the extension
1534 to return \emph{count} rational numbers on each side of the
1535 rational number specified. If the rational number specified is already
1536 in the series of interest, it will be returned as well, normally\footnote{If
1537 the set of returned rational numbers is not clipped at $-h_{MAX}/1$ or
1538 $h_{MAX}/1$.} resulting
1539 in an odd number of rational numbers returned. If the rational number
1540 specified is not already in the series of interest, an even number of
1541 rational numbers will normally be returned. The rational
1542 numbers returned are prefixed with integer indices, which
1543 indicate their ordinal distance from the rational number to be approximated
1544 (see the invocation examples below). The index of 0 is reserved for
1545 the reduced form of the rational number specified, and and a rational number with
1546 this index will be in the output only if the rational number supplied was already
1547 in the series of interest.
1548 The rational numbers returned
1549 will be formatted as integer indices and slash-separated integers, separated
1550 by single spaces and arranged in ascending order..
1551 If the number of rational numbers requested by this option exceeds
1552 the number available, the sequence will simply be truncated at
1553 $-h_{MAX}/1$ or $h_{MAX}/1$, as appropriate. Any request for more than
1554 10,000 neighbors (on each side) will be clipped to 10,000.
1555 \end{tclcommanddescription}
1556
1557 \begin{tclcommandsampleinvocations}
1558 \begin{scriptsize}
1559 \begin{verbatim}
1560 % arbint cfbrapab 1.6093 255
1561 346/215
1562 % arbint cfbrapab 1.6093 255 255
1563 243/151
1564 % arbint cfbrapab 1.6093 255 255 -neversmaller
1565 103/64
1566 % arbint cfbrapab 1.6093 255 255 -neverlarger
1567 243/151
1568 % arbint cfbrapab 1.6093 255 255 -n 20
1569 -20 143/89 -19 188/117 -18 233/145 -17 45/28 -16 217/135 -15 172/107 -14 127/79
1570 -13 209/130 -12 82/51 -11 201/125 -10 119/74 -9 156/97 -8 193/120 -7 230/143 -6
1571 37/23 -5 251/156 -4 214/133 -3 177/110 -2 140/87 -1 243/151 1 103/64 2 169/105
1572 3 235/146 4 66/41 5 227/141 6 161/100 7 95/59 8 219/136 9 124/77 10 153/95 11
1573 182/113 12 211/131 13 240/149 14 29/18 15 253/157 16 224/139 17 195/121 18
1574 166/103 19 137/85 20 245/152
1575 % arbint cfbrapab 1.6093 255 255 -succ
1576 103/64
1577 % arbint cfbrapab 1.6093 255 255 -pred
1578 243/151
1579 % arbint cfbrapab 2/3 255 255 -pred
1580 169/254
1581 \end{verbatim}
1582 \end{scriptsize}
1583 \end{tclcommandsampleinvocations}
1584
1585 \begin{tclcommandseealso}
1586 This extension uses the continued fraction
1587 algorithms presented in Chapter \ccfrzeroxrefhyphen{}\ref{ccfr0}.
1588 See also the \emph{cfratnum} DOS command-line utility,
1589 Section \cdcmzeroxrefhyphen{}\ref{cdcm0:snth0:sbra0}.
1590 \end{tclcommandseealso}
1591
1592
1593 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1594 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1595 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1596 \subsection{The \texttt{arbint const} Extension}
1597 %Subsection Tag: CEX0
1598 \label{cxtn0:snth0:scex0}
1599
1600 \index{arbint const@\emph{arbint const}}
1601 \index{const (Tcl arbint sub-extension)@\emph{const} (Tcl \emph{arbint} sub-extension)}
1602 \begin{tclcommandname}{arbint const}%
1603 returns a string representing the value of important
1604 mathematical and conversion constants (such as the value
1605 of $\pi$ or $e$, or the conversion factor from miles to kilometers).
1606 \end{tclcommandname}
1607
1608 \begin{tclcommandsynopsis}
1609 \tclcommandsynopsisline{arbint const}{const\_tag}
1610 \tclcommandsynopsisline{arbint const}{const\_tag uint32\_ndigits}
1611 \end{tclcommandsynopsis}
1612
1613 \begin{tclcommanddescription}
1614 The \emph{const} subextension returns the value (as a string) of
1615 constants that may be useful in engineering work. Such constants
1616 may include mathematically significant numbers (such as
1617 \index{pi@$\pi$ (transcendental constant)}$\pi$ or
1618 \index{e@$e$ (transcendental constant)}$e$), or
1619 useful conversion factors (the conversion factor from
1620 miles to kilometers, for example). These string constants
1621 can be used in calculations involving rational numbers.
1622
1623 All constants are simply tabulated as character strings
1624 within the `C' source code.
1625
1626 Mathematically significant numbers (which, to the best
1627 of the author's knowledge are always irrational and
1628 usually transcendental, as mathematicians
1629 don't seem to have any lasting interest in specific integers
1630 or rational numbers) are available to about 1,000 significant digits,
1631 and have been obtained from various web pages. It is reasoned that
1632 1,000 significant digits should be adequate for engineering applications.
1633
1634 Measurement unit conversion constants have typically been obtained from
1635 \emph{NIST Special Publication 811} \cite{bibref:b:nistsp811:1995ed}.
1636 These constants are always tabulated with their full precision, since
1637 no physical constant can be precise to more than several decimal places.
1638
1639 If the number of significant figures is not specified,
1640 each constant is returned as a string with a default number of
1641 decimal places (typically about 30). In most cases, the default
1642 number of decimal places provides more than enough precision for
1643 engineering work. However, an optional parameter allows more
1644 or fewer digits to be obtained, up to the maximum number tabulated internally
1645 in the software. The default number of decimal places is a compromise
1646 between calculation speed and accuracy. It is felt in most cases that
1647 the default number of decimal places provides excellent accuracy
1648 and good calculation speed.
1649
1650 Please e-mail the authors if you would like additional useful
1651 constants included. Because the list of tabulated constants
1652 may grow and shrink, it would not be a sound decision to document
1653 the constants which are included here. Instead, use
1654 \emph{arbint const} with an invalid tag, and the software itself
1655 will list all of the internally tabulated constants and their
1656 significance.
1657 \end{tclcommanddescription}
1658
1659 \begin{tclcommandsampleinvocations}
1660 Please note that the sample invocation below was created using
1661 v1.05 of the tool set. The list of constants may have grown
1662 since this example was created. Please poll the software directly
1663 by using \emph{arbint const} with an invalid tag to obtain the
1664 list of constants and their significance.
1665 \begin{scriptsize}
1666 \begin{verbatim}
1667 % arbint const xxx
1668 arbint const: "xxx" is not a recognized constant.
1669 Available constants are:
1670 e (1000 digits available)
1671 Historically significant transcendental constant. Digits obtained
1672 from http://fermi.udw.ac.za/physics/e.html on 08/17/01.
1673 g_si (6 digits available)
1674 Gravitational acceleration in SI units, meters per second**2.
1675 Obtained from NIST Special Publication 811 on 08/17/01.
1676 in2m (3 digits available)
1677 Multiplicative conversion factor from inches to meters.
1678 Obtained from NIST Special Publication 811 on 08/17/01.
1679 mi2km (7 digits available)
1680 Multiplicative conversion factor from miles to kilometers.
1681 Obtained from NIST Special Publication 811 on 08/17/01.
1682 pi (1201 digits available)
1683 Transcendental constant supplying ratio of a circle's circumference
1684 to its diameter. Digits obtained from http://www.joyofpi.com/
1685 pi.htm on 08/17/01.
1686 sqrt5 (1040 digits available)
1687 The square root of 5. Digits obtained from
1688 http://home.earthlink.net/~maryski/sqrt51000000.txt on 08/17/01.
1689 % arbint const pi
1690 3.14159265358979323846264338327
1691 % arbint const pi 100
1692 3.141592653589793238462643383279502884197169399375105820974944592307816406286208998628034825342117067
1693 % arbint const pi 10
1694 3.141592653
1695 % arbint cfbrapab [arbint const pi 100] 65535 65535
1696 65298/20785
1697 \end{verbatim}
1698 \end{scriptsize}
1699 \end{tclcommandsampleinvocations}
1700
1701
1702 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1703 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1704 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1705 \section{Miscellaneous Extensions}
1706
1707 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1708 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1709 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1710 \subsection{credits}
1711
1712 \index{credits@\emph{credits}}
1713 \begin{tclcommandname}{credits}%
1714 returns information about authorship of software components.
1715 \end{tclcommandname}
1716
1717 \begin{tclcommandsynopsis}
1718 \tclcommandsynopsisline{credits}{}
1719 \tclcommandsynopsisline{credits}{searchstring}
1720 \end{tclcommandsynopsis}
1721
1722 \begin{tclcommanddescription}
1723 The \emph{credits} command returns a list of contributors to the tools,
1724 their area(s) of contribution, and e-mail addresses. The volume of
1725 information returned can be reduced by using an optional \emph{searchstring}.
1726
1727 \tclcommanddescsynopsisline{credits}{}
1728 \begin{tclcommandinternaldescription}
1729 Returns the complete list of contributors to the tools and their area(s) of contribution.
1730 \end{tclcommandinternaldescription}
1731
1732 \tclcommanddescsynopsisline{credits}{searchstring}
1733 \begin{tclcommandinternaldescription}
1734 Returns all credit records containing \emph{searchstring}.
1735 Most commonly, this option is used to search for information about a specific
1736 command by using the command name as the \emph{searchstring}, or about a
1737 specific individual by using a component of the individual's name as the
1738 \emph{searchstring}.
1739
1740 \end{tclcommandinternaldescription}
1741
1742 \end{tclcommanddescription}
1743
1744 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1745 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1746 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1747 \noindent\begin{figure}[!b]
1748 \noindent\rule[-0.25in]{\textwidth}{1pt}
1749 \begin{tiny}
1750 \begin{verbatim}
1751 $HeadURL$
1752 $Revision$
1753 $Date$
1754 $Author$
1755 \end{verbatim}
1756 \end{tiny}
1757 \noindent\rule[0.25in]{\textwidth}{1pt}
1758 \end{figure}
1759 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1760 %
1761 %End of file C_XTN0.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