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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

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

Legend:
Removed from v.139  
changed lines
  Added in v.140

dashley@gmail.com
ViewVC Help
Powered by ViewVC 1.1.25