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 
compiledin commands added to the language. These extensions have advantages 
compiledin commands added to the language. These extensions have advantages 
20 
for performance, because they allow the highfrequency interactions to occur 
for performance, because they allow the highfrequency interactions to occur 
21 
in compiled code, and the lowerfrequency interactions to occur in 
in compiled code, and the lowerfrequency 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 commandline 
(described in this chapter) and the DOS commandline 
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 commandline utilities. 
and the DOS commandline 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 lowercase letter identifying a service release which fixes defects 
\emph{x} is an optional lowercase 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 $12^{32}$ that two versions of IjuScripter or IjuConsole 
establish with a probability of about $12^{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 $12^{32}$ that two versions of IjuScripter or IjuConsole 
establish with a probability of about $12^{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 CRC32 of a file or string. This CRC can be reliably used to obtain 
generates the CRC32 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 CRC32 of the binary contents of a file 
The \emph{crc32} command forms the CRC32 of the binary contents of a file 
185 
or of the binary contents of a string. The CRC32 is useful as a digital 
or of the binary contents of a string. The CRC32 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 $12^{32}$ to determine 
files are different, or with a probability of about $12^{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 CRC32 is always returned as a 10character ASCII string 
In the invocations below, the CRC32 is always returned as a 10character 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 32bit CRC32, and \emph{``0x''} is a constant 2character prefix 
of the 32bit CRC32, and \emph{``0x''} is a constant 2character 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 uppercase. 
in the hexadecimal representation will be uppercase. 
203 
\end{itemize} 
\end{itemize} 
204 


205 
\tclcommanddescsynopsisline{crc32}{filename} 
\tclcommanddescsynopsisline{crc32}{filename} 
206 
\begin{tclcommandinternaldescription} 
\begin{tclcommandinternaldescription} 
207 
Returns the CRC32 of \emph{filename}, treated as an ordered collection of bytes (i.e. 
Returns the CRC32 of \emph{filename}, treated as an ordered collection of bytes (i.e. 
208 
newline characters and file termination characters are not processedthe file is 
newline characters and file termination characters are not processedthe 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 CRC32 of \emph{binarystringval}, treated as an ordered collection of bytes (i.e. 
Returns the CRC32 of \emph{binarystringval}, treated as an ordered collection of bytes (i.e. 
216 
newline characters and string termination characters are not honoredthe string is 
newline characters and string termination characters are not honoredthe 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 nonASCII strings.} 
terminator. However, the \emph{crc32} extension will also correctly process nonASCII 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 CRC32 state machine. The client is required 
correct initial state vector of the CRC32 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 10character ASCII string as described above. 
calculated CRC, and will return a 10character 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 formsthere is no difference 
(1) The ``piecemeal'' forms are as efficient as the file and string formsthere 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 nonidentical files are identical yet further. Two files might be 
assuming two nonidentical files are identical yet further. Two files might be 
261 
assumed identical if they have the same size and the same CRC32. 
assumed identical if they have the same size and the same CRC32. 
262 
\end{tclcommandusagenotes} 
\end{tclcommandusagenotes} 
263 


264 
\begin{tclcommandacknowledgements} 
\begin{tclcommandacknowledgements} 
265 
The \emph{crc32} command was implemented using ideas and Clanguage 
The \emph{crc32} command was implemented using ideas and Clanguage 
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 pseudorandom integers using the power residue 
generates pseudorandom 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. 6971). 
(\cite{bibref:b:LeonGarciaProb}, pp. 6971). 
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 pseudorandom positive integers 
The \emph{rngPwrResRndA} command generates pseudorandom 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_{i1} mod M, 
Z_i = \alpha Z_{i1} 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{ArbitraryLength Integer Extensions} 
\section{ArbitraryLength 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 ArbitraryLength Integer Extensions} 
\subsection{Error And Overflow Behavior Of ArbitraryLength 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 arbitrarylength integers includes flags 
The underlying data structure of arbitrarylength 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 ``notanumber'' flags. They indicate that the result is not 
``NAN'', or ``notanumber'' 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 approximatethey don't \emph{precisely} indicate the 
error flags are only approximatethey 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 arbitrarylength integer extensions described 
Note also that each of the separate arbitrarylength integer extensions described 
427 
in this section are a ``subextension'' to the \texttt{arbint} extension. It 
in this section are a ``subextension'' 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 
arbitrarylength integer operation. All valid integers will create 
arbitrarylength 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 ``humanfriendly'' output. The input to this extension 
format a string for more ``humanfriendly'' 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 commandline utility, 
See also the \emph{intadd} DOS commandline 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 commandline utility, 
See also the \emph{intsub} DOS commandline 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 commandline utility, 
See also the \emph{intmul} DOS commandline 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 commandline utility, 
See also the \emph{intdiv} DOS commandline 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 commandline utility, 
See also the \emph{intmod} DOS commandline 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 nonnegative 
This extension exponentiates an integer to a nonnegative 
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. 461462. 
in \cite{bibref:b:knuthclassic2ndedvol2}, pp. 461462. 
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 32bit integer. 
arbint intexp: "69" is not a recognized unsigned 32bit 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 commandline utility, 
See also the \emph{intexp} DOS commandline 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 
nonnegative integers that will not fit in 32 bits will generate 
nonnegative 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 commandline utility, 
See also the \emph{intfac} DOS commandline 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 commandline utility, 
See also the \emph{intgcd} DOS commandline 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 commandline utility, 
See also the \emph{intlcm} DOS commandline 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 
freelythe output of any of the extensions is suitable as input 
freelythe 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 unexpectedthe 
Note that one behavior above may be unexpectedthe 
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 commandline utility, 
See also the \emph{rnred} DOS commandline 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 commandline utility, 
See also the \emph{rnadd} DOS commandline 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 commandline utility, 
See also the \emph{rnsub} DOS commandline 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 commandline utility, 
See also the \emph{rnmul} DOS commandline 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 commandline utility, 
See also the \emph{rnmul} DOS commandline 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 nonnegative rational number. 
a nonnegative 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 nonnegative rational number. The results are 
of a nonnegative 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 commandline utility, 
See also the \emph{cfratnum} DOS commandline 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 interestthe reduced form of the specified number 
series of interestthe 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 slashseparated integers, separated 
will be formatted as integer indices and slashseparated 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 commandline utility, 
See also the \emph{cfratnum} DOS commandline 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 subextension)@\emph{const} (Tcl \emph{arbint} subextension)} 
\index{const (Tcl arbint subextension)@\emph{const} (Tcl \emph{arbint} subextension)} 
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 email the authors if you would like additional useful 
Please email 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 email addresses. The volume of 
their area(s) of contribution, and email 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 JanHinnerk Reichert's 
% Global corrections to typeface of "gcd" made as per JanHinnerk 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 checkin. Substantial progress. 
% Safety checkin. 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 commandline utility. 
% Completion of CFRATNUM Tcl extension and DOS commandline 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 commandline utilities, such as addition, subtraction, 
% as DOS commandline 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 commandline utility finished. 
% INTFAC extension and commandline 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 MultiVolume Book (A)/Chapter, XTN0, IjuScripterIjuConsole TclTk Extensions 
% Updated in $/uC Software MultiVolume Book (A)/Chapter, XTN0, IjuScripterIjuConsole TclTk 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 MultiVolume Book (A)/Chapter, XTN0, IjuScripterIjuConsole TclTk Extensions 
% Updated in $/uC Software MultiVolume Book (A)/Chapter, XTN0, IjuScripterIjuConsole TclTk 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 MultiVolume Book (A)/Chapter, XTN0, IjuScripterIjuConsole TclTk Extensions 
% Created in $/uC Software MultiVolume Book (A)/Chapter, XTN0, IjuScripterIjuConsole TclTk Extensions 
1814 
% Initial checkin. 
% Initial checkin. 
1815 
% 
% 
1816 
%End of file C_XTN0.TEX 
%End of file C_XTN0.TEX 