%$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 $ \chapter[\cxtnzeroshorttitle{}]{\cxtnzerolongtitle{}} \label{cxtn0} \beginchapterquote{``One way to prevent progress is by arguing that any first step is unfair to somebody.''} {Unknown} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Introduction} %Section Tag: INT0 \label{cxtn0:sint0} The Tcl scripting language provides for \emph{extensions}, which are compiled-in commands added to the language. These extensions have advantages for performance, because they allow the high-frequency interactions to occur in compiled code, and the lower-frequency interactions to occur in a Tcl script. This chapter describes the extensions that have been added to the Tcl interpreters which are part of \emph{The Iju Tool Set}. Many of the parameter formats are common between the Tcl extensions (described in this chapter) and the DOS command-line utilities (described in Chapter \cdcmzeroxrefhyphen{}\ref{cdcm0}). For this reason, to avoid redundancy of documentation, the parameter formats described in Section \ctinzeroxrefhyphen{}\ref{ctin0:sccl0} apply both to the Tcl extensions and the DOS command-line utilities. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Version Control Extensions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{vcinfo} \index{vcinfo@\emph{vcinfo}} \begin{tclcommandname}{vcinfo}% retrieves embedded static version and version control information for IjuScripter or IjuConsole. This allows a script to determine which version of script interpreter it is running under. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{vcinfo}{-ijutoolsversion} \tclcommandsynopsisline{vcinfo}{?-crconly? -fileversion filename} \tclcommandsynopsisline{vcinfo}{?-crconly? -extensionversion extensionname} \tclcommandsynopsisline{vcinfo}{-buildmanifest} \end{tclcommandsynopsis} \begin{tclcommanddescription} The \emph{vcinfo} command returns information about the version of the IjuScripter or IjuConsole executable program, about the version of a specific source file, or [collectively] about the version of all files which [directly] contribute to the behavior of an embedded Tcl/Tk extension. This command can be used to inquire about the version of the executable program or certain of its components. Most commonly, this command is used to help assure reproducibility of a script's behavior by coding a script so that it will run only under a specific version(s) of executable. \tclcommanddescsynopsisline{vcinfo}{-ijutoolsversion} \begin{tclcommandinternaldescription} Returns a string identifying the version number of the IjuScripter or IjuConsole executable. The string will be of the form ``vm.nx'', where \emph{v} is the letter ``v'', \emph{m} is the major version number, \emph{n} is the minor version number, and \emph{x} is an optional lower-case letter identifying a service release which fixes defects but adds no new functionality. For example, a return value of ``v1.03'' would identify version 1.03. A return value of ``v1.03c'' would identify the third service release to version 1.03; with the service release designed to correct defects present in version 1.03b, but adding no new functionality. \end{tclcommandinternaldescription} \tclcommanddescsynopsisline{vcinfo}{-fileversion filename} \begin{tclcommandinternaldescription} (Not yet implemented.) Returns a string with version control information for the file \emph{filename}, which must be part of the IjuScripter or IjuConsole build. An error is generated if a \emph{filename} which is not part of the build is supplied. This form of the \emph{vcinfo} command is not normally used from a script. \end{tclcommandinternaldescription} \tclcommanddescsynopsisline{vcinfo}{-crconly -fileversion filename} \begin{tclcommandinternaldescription} (Not yet implemented.) Returns the CRC32 of the the string result of the command above. Note that the value returned is the CRC of the version control information embedded in the file rather than the CRC of the file. \emph{filename} must be part of the IjuScripter or IjuConsole build, and an error is generated if a \emph{filename} which is not part of the build is supplied. This form is useful because it supplies a terse result of eight hexadecimal digits which can easily establish with a probability of about $1-2^{-32}$ that two versions of IjuScripter or IjuConsole have the same file component; or establish with unity probability that they do not. \end{tclcommandinternaldescription} \tclcommanddescsynopsisline{vcinfo}{-extensionversion extensionname} \begin{tclcommandinternaldescription} (Not yet implemented.) Returns a string with version control information for all files which contribute directly to the behavior of the Tcl extension \emph{extensionname}, which must be part of the IjuScripter or IjuConsole static build. An error is generated if an \emph{extensionname} which is not part of the build is supplied. \end{tclcommandinternaldescription} \tclcommanddescsynopsisline{vcinfo}{-crconly -extensionversion extensionname} \begin{tclcommandinternaldescription} (Not yet implemented.) Returns the CRC32 of the the string result of the command above. Note that the value returned is the CRC of the version control information embedded in the file(s) rather than the CRC(s) of the file(s). \emph{extensionname} must be part of the IjuScripter or IjuConsole build, and an error is generated if an \emph{extensionname} which is not part of the build is supplied. This form is useful because it supplies a terse result of eight hexadecimal digits which can easily establish with a probability of about $1-2^{-32}$ that two versions of IjuScripter or IjuConsole have the same extension component(s); or establish with unity probability that they do not. \end{tclcommandinternaldescription} \tclcommanddescsynopsisline{vcinfo}{-crconly -buildmanifest} \begin{tclcommandinternaldescription} (Not yet implemented.) Returns the full combined build manifest of IjuScripter and IjuConsole. This includes size and CRC information for every file involved in the build. This form of \emph{vcinfo} is provided for assistance in defect diagnosis. \end{tclcommandinternaldescription} \end{tclcommanddescription} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{File Transformation Extensions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{CRC, Checksum, And Hash Extensions} %Section Tag: CRC0 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{crc32} %Subsection Tag: CRC0 \label{cxtn0:scrc0:scrc0} \index{crc32@\emph{crc32}} \begin{tclcommandname}{crc32}% generates the CRC-32 of a file or string. This CRC can be reliably used to obtain digital signatures of files or data. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{crc32}{filename} \tclcommandsynopsisline{crc32}{-string binarystringval} Note: as of 01/01/01, the ``stateful'' forms below are not yet implemented. \tclcommandsynopsisline{crc32}{-initialstate} \tclcommandsynopsisline{crc32}{-advancestate state filename} \tclcommandsynopsisline{crc32}{-advancestate -string state binarystringval} \tclcommandsynopsisline{crc32}{-crcfromstate state} \end{tclcommandsynopsis} \begin{tclcommanddescription} The \emph{crc32} command forms the CRC-32 of the binary contents of a file or of the binary contents of a string. The CRC-32 is useful as a digital signature, and can be used with unity probability to determine that two files are different, or with a probability of about $1-2^{-32}$ to determine that two files are almost certainly identical. In the invocations below, the CRC-32 is always returned as a 10-character ASCII string of the form \emph{``0xDDDDDDDD''}, where \emph{``DDDDDDDD''} is the hexadecimal representation of the 32-bit CRC-32, and \emph{``0x''} is a constant 2-character prefix (the ``zero'' digit followed by ``x'') which is included for aesthetics. It is guaranteed that: \begin{itemize} \item The string returned will be exclusively ASCII. \item The string will have a length of exactly 10 characters. \item The first two characters of the string will be \emph{``0x''}. \item The hexadecimal representation will be exactly 8 characters, and any letters in the hexadecimal representation will be upper-case. \end{itemize} \tclcommanddescsynopsisline{crc32}{filename} \begin{tclcommandinternaldescription} Returns the CRC-32 of \emph{filename}, treated as an ordered collection of bytes (i.e. newline characters and file termination characters are not processed---the file is treated as a binary file). \emph{filename} must be specified in the form accepted by the Tcl internals (forward slashes only). \end{tclcommandinternaldescription} \tclcommanddescsynopsisline{crc32}{-string binarystringval} \begin{tclcommandinternaldescription} Returns the CRC-32 of \emph{binarystringval}, treated as an ordered collection of bytes (i.e. newline characters and string termination characters are not honored---the string is treated as a binary string).\footnote{For an ASCII string, the \emph{crc32} extension will behave as expected, and will process all characters up to but not including the zero terminator. However, the \emph{crc32} extension will also correctly process non-ASCII strings.} \end{tclcommandinternaldescription} \tclcommanddescsynopsisline{crc32}{-initialstate} \tclcommanddescsynopsisline{crc32}{-advancestate state filename} \tclcommanddescsynopsisline{crc32}{-advancestate -string state filename} \tclcommanddescsynopsisline{crc32}{-crcfromstate state} \begin{tclcommandinternaldescription} The four forms above are designed to allow ``running CRCs'' to be calculated; in which the CRC is calculated piecemeal. These forms allow the caller to retain the internal state vector of the CRC calculation algorithm. The first form, \emph{crc32 -initialstate}, returns an ASCII representation of the correct initial state vector of the CRC-32 state machine. The client is required to obtain this initial state before beginning a piecemeal CRC calculation. Although the returned string is a constant (it will always be the same), representational details may change in future versions of the \emph{crc32} extension, and so a caller should never make assumptions about what this invocation will return, as these assumptions may render a script incompatible with future versions of \emph{crc32}. The second and third forms, \emph{crc32 -advancestate state filename} and \emph{crc32 -advancestate -string state filename}, apply a file or a binary string to \emph{state} to produce a new \emph{state}, which is returned. This new \emph{state} must be retained by the caller and used in subsequent calls. The final form, \emph{crc32 -crcfromstate state}, maps from the state vector to the calculated CRC, and will return a 10-character ASCII string as described above. \end{tclcommandinternaldescription} \end{tclcommanddescription} \begin{tclcommandusagenotes} (1) The ``piecemeal'' forms are as efficient as the file and string forms---there is no difference in the internal algorithms. The primary cost of the piecemeal forms is in importing and exporting the algorithm state vector to/from an ASCII string. Thus, the piecemeal forms become less efficient when small files or strings are processed, as there are more exports and imports of the state vector. When using the piecemeal forms, processing the data in larger chunks will give better performance. (2) If the \emph{crc32} command is used to signature files, it is recommended that the \texttt{file size} command also be used to lower the probability of falsely assuming two non-identical files are identical yet further. Two files might be assumed identical if they have the same size and the same CRC-32. \end{tclcommandusagenotes} \begin{tclcommandacknowledgements} The \emph{crc32} command was implemented using ideas and C-language code from a website (\cite{bibref:w:ellingsoncrc32pages}) provided by Richard A. Ellingson\index{Ellingson, Richard A.} \cite{bibref:i:richardaellingson}. I am especially grateful to Mr. Ellingson for providing these materials publicly and free of charge. \end{tclcommandacknowledgements} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Random Number Generation Extensions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{rngPwrResRndA} \index{rngPwrResRndA@\emph{rngPwrResRndA}} \begin{tclcommandname}{rngPwrResRndA}% generates pseudo-random integers using the power residue method with $\alpha = 7^5 = 16,807$ and $M = 2^{31}-1 = 2,147,483,647$, providing a period of $M - 1 = 2^{31}-2 = 2,147,483,646$ (\cite{bibref:b:LeonGarciaProb}, pp. 69-71). \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{rngPwrResRndA}{} \tclcommandsynopsisline{rngPwrResRndA}{$N$} \end{tclcommandsynopsis} \begin{tclcommanddescription} The \emph{rngPwrResRndA} command generates pseudo-random positive integers using the [power residue] recursive formula \begin{equation} \label{cxtn0:rngPwrResRndA:eq00} Z_i = \alpha Z_{i-1} mod M, \end{equation} with $(\alpha, M)$ chosen as $(\alpha = 7^5=16,807, M = 2^{31}-1 = 2,147,483,647)$, as indicated above. With these choices of $(\alpha, M)$, the sequence has a period of $M - 1 = 2^{31}-2 = 2,147,483,646$ and good statistical properties. The basis for choosing $(\alpha, M)$ has its origins in number theory, and won't be discussed here. We refer the reader to \cite{bibref:b:LeonGarciaProb} and to mathematical papers on the power residue method. This extension maintains one internal seed value, which is initialized to 1,578,127,215 at Tcl/Tk startup.\footnote{There is no scientific reason for the choice of the integer 1,578,127,215 as the startup value. It was chosen arbitrarily with no rationale.} It is not possible to set the internal seed to an arbitrary desired value. The single internal seed value is adequate for most applications which simply require random numbers. If an application requires control over the seed or requires multiple seeds, the ability of this extension to generate the successor of an integer using (\ref{cxtn0:rngPwrResRndA:eq00}) can be used to achieve this functionality in a script. \tclcommanddescsynopsisline{rngPwrResRndA}{} \begin{tclcommandinternaldescription} Buffers the current seed for a return value, then advances this seed using (\ref{cxtn0:rngPwrResRndA:eq00}). Note that the ``old'' value is the value returned, so that after Tcl/Tk startup the first value returned will be 1,578,127,215. \end{tclcommandinternaldescription} \tclcommanddescsynopsisline{rngPwrResRndA}{$N$} \begin{tclcommandinternaldescription} Forms the successor of $N$ using (\ref{cxtn0:rngPwrResRndA:eq00}) and returns this successor. The single internal seed value is not affected. \end{tclcommandinternaldescription} \end{tclcommanddescription} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Arbitrary-Length Integer Extensions} %Section Tag: SARB0 \label{cxtn0:sarb0} Starting with Version 1.05 of \emph{The Iju Tool Set}, \emph{IjuScripter} and \emph{IjuConsole} contain a limited\footnote{By \emph{limited} we mean that the library was consolidated and simplified. The GNU MP library has as its explicit design goal speed over clarity, and uses many advanced algorithms, such as Karatsuba multiplication and special algorithms for the greatest common divisor of integers. The library was simplified to regain clarity at the expense of efficiency before its incorporation into \emph{The Iju Tool Set}.} version of the \index{GNU!Multiple Precision Arithmetic Library (GMP)}\emph{GNU Multiple Precision Library} \cite{bibref:s:gnumultipleprecisionarithmeticlibrary}. The version of the library incorporated into the tools has been modified not to process integers larger than about 100,000 decimal digits. We feel that this limit is sufficiently high for any practical applications, and also that the computational speed will become unbearable long before the data size limit is approached. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Error And Overflow Behavior Of Arbitrary-Length Integer Extensions} %Subsection Tag: EAB0 \label{cxtn0:sarb0:seab0} The underlying data structure of arbitrary-length integers includes flags to indicate that an arithmetic error has occured. Essentially, these flags are ``NAN'', or ``not-a-number'' flags. They indicate that the result is not an integer. These error flags propagate. Combining a NAN value with a valid integer through a binary operation always results in a NAN value. Naturally, the result of a unary operation on a NAN value is also a NAN value. The nature of NAN propagation is that the first arithmetic operation that creates an error using valid integers as input will generate an overflow error (one of the first two flags listed below). Subsequent operations that use these original errors as input will generate outputs which are ``taint'' errors (the second set of two flags listed below). At the lowest level (in the innards of the `C' code), these flags are bits within an integer. However, for use within Tcl (where all data is string data), these error flags are assigned symbolic strings to indicate the nature of the error. Note that the error flags are only approximate---they don't \emph{precisely} indicate the nature of the error. However, combined with propagation mechanisms, they are adequate to prevent the interpretation of invalid data as valid data. Any result that is predicated on an invalid result will itself be invalid. The four possible error strings are enumerated below. If any Tcl long integer function creates an erroneous result, the result will be assigned one of these four symbolic error strings rather than a string of digits. \begin{itemize} \item \index{GMP\_INTS\_EF\_INTOVF\_POS@\texttt{GMP\_INTS\_EF\_INTOVF\_POS}} \texttt{GMP\_INTS\_EF\_INTOVF\_POS}---the result is too positive (i.e. too large in a positive direction). This error flag is also produced by an attempted division by zero, regardless of the sign of the dividend. \item \index{GMP\_INTS\_EF\_INTOVF\_NEG@\texttt{GMP\_INTS\_EF\_INTOVF\_NEG}} \texttt{GMP\_INTS\_EF\_INTOVF\_NEG}---the result is too negative (i.e. too large in a negative direction). \item \index{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS@\texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS}} \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS}---the result has been ``tainted'' by combination with an integer which has the \texttt{GMP\_INTS\_EF\_INTOVF\_POS} flag set. \item \index{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG@\texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG}} \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG}---the result has been ``tainted'' by combination with an integer which has the \texttt{GMP\_INTS\_EF\_INTOVF\_NEG} flag set. \end{itemize} Note that the functions which operate on arbitrary length integers will never produce an exception or a fatal error. Instead, they will mark results as NAN, and these NAN results will propagate. This mechanism provides for graceful failures, and also allows complex calculations to be performed without the necessity of checking for errors after every calculation step. Note also that each of the separate arbitrary-length integer extensions described in this section are a ``sub-extension'' to the \texttt{arbint} extension. It should also be noted that many of these extensions perform the same function as a DOS utility with the same name (see Chapter \cdcmzeroxrefhyphen{}\ref{cdcm0}). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint iseflag} Extension} \index{arbint iseflag@\emph{arbint iseflag}} \index{iseflag@\emph{iseflag}} \begin{tclcommandname}{arbint iseflag}% identifies a string as an arbitrary integer error flag (or not) and returns an integer value categorizing the string. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint iseflag }{stringarg} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension returns: \begin{itemize} \item ``0'' if the string argument supplied is not a recognized error flag. \item ``1'' if the string argument supplied is recognized as the\\ \texttt{GMP\_INTS\_EF\_INTOVF\_POS} error flag. \item ``2'' if the string argument supplied is recognized as the\\ \texttt{GMP\_INTS\_EF\_INTOVF\_NEG} error flag. \item ``3'' if the string argument supplied is recognized as the\\ \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS} error flag. \item ``4'' if the string argument supplied is recognized as the\\ \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG} error flag. \end{itemize} This extension is most often used to classify the output of an arbitrary-length integer operation. All valid integers will create a value of zero if passed to this extension as an argument. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint iseflag GMP_INTS_EF_INTOVF_NEG 2 % arbint iseflag 249,422 0 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also Section \ref{cxtn0:sarb0:seab0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint commanate} Extension} %Subsection Tag: COM0 \label{cxtn0:sarb0:scom0} \index{arbint commanate@\emph{arbint commanate}} \index{commanate@\emph{commanate}} \begin{tclcommandname}{arbint commanate}% inserts comma characters (`,') into a string as necessary to make it a properly formatted integer with commas. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint commanate}{sint} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension adds commas to an integer to make it a properly formatted integer with commas. This extension is normally used to format a string for more ``human-friendly'' output. The input to this extension must be either: \begin{itemize} \item A integer with no commas, as a string of digits (i.e. scientific notation is not allowed). The only valid representation for zero is ``0''. \item An integer with all commas properly placed (i.e. it is allowed to ``recommanate'' an integer that is already ``commanated''). \item One of the four symbolic NAN strings described in Section \ref{cxtn0:sarb0:seab0}. (Such a string will not be modified and will be returned unmodified from this extension.) \end{itemize} Any string that cannot be parsed as described above will result in an error. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint intfac 129 4974504222477287440390234150412680963965661113713884314596886402265216893219635 5119328515747917449637889876686464600208839390308261862352651828829226610077151 044469167497022952331930501120000000000000000000000000000000 % arbint commanate [arbint intfac 129] 49,745,042,224,772,874,403,902,341,504,126,809,639,656,611,137,138,843,145,968, 864,022,652,168,932,196,355,119,328,515,747,917,449,637,889,876,686,464,600,208 ,839,390,308,261,862,352,651,828,829,226,610,077,151,044,469,167,497,022,952,33 1,930,501,120,000,000,000,000,000,000,000,000,000,000 % arbint commanate GMP_INTS_EF_INTOVF_POS GMP_INTS_EF_INTOVF_POS \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint decommanate} Extension} %Subsection Tag: dco0 \label{cxtn0:sarb0:sdco0} \index{arbint decommanate@\emph{arbint decommanate}} \index{decommanate@\emph{decommanate}} \begin{tclcommandname}{arbint decommanate}% removes comma characters (`,') from a properly formatted integer. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint decommanate}{sint} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension removes commas from a properly formatted integer. The input to this extension must be either: \begin{itemize} \item A integer with no commas, as a string of digits (i.e. scientific notation is not allowed). The only valid representation for zero is ``0''. (Note that it is allowed to ``decommanate'' an integer that contains no commas.) \item An integer with all commas properly placed. \item One of the four symbolic NAN strings described in Section \ref{cxtn0:sarb0:seab0}. (Such a string will not be modified and will be returned unmodified from this extension.) \end{itemize} Any string that cannot be parsed as described above will result in an error. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint intfac 129 4974504222477287440390234150412680963965661113713884314596886402265216893219635 5119328515747917449637889876686464600208839390308261862352651828829226610077151 044469167497022952331930501120000000000000000000000000000000 % arbint commanate [arbint intfac 129] 49,745,042,224,772,874,403,902,341,504,126,809,639,656,611,137,138,843,145,968, 864,022,652,168,932,196,355,119,328,515,747,917,449,637,889,876,686,464,600,208 ,839,390,308,261,862,352,651,828,829,226,610,077,151,044,469,167,497,022,952,33 1,930,501,120,000,000,000,000,000,000,000,000,000,000 % set number [arbint commanate [arbint intfac 129]] 49,745,042,224,772,874,403,902,341,504,126,809,639,656,611,137,138,843,145,968, 864,022,652,168,932,196,355,119,328,515,747,917,449,637,889,876,686,464,600,208 ,839,390,308,261,862,352,651,828,829,226,610,077,151,044,469,167,497,022,952,33 1,930,501,120,000,000,000,000,000,000,000,000,000,000 % arbint decommanate $number 4974504222477287440390234150412680963965661113713884314596886402265216893219635 5119328515747917449637889876686464600208839390308261862352651828829226610077151 044469167497022952331930501120000000000000000000000000000000 % arbint decommanate GMP_INTS_EF_INTOVF_POS GMP_INTS_EF_INTOVF_POS \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint intcmp} Extension} %Subsection Tag: add0 \label{cxtn0:sarb0:scmp0} \index{arbint intcmp@\emph{arbint intcmp}} \index{intcmp@\emph{intcmp}} \begin{tclcommandname}{arbint intcmp}% compares two arbitrary integers and returns a result indicating their relative ordering. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint intcmp}{sint\_a sint\_b} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension compares \emph{sint\_a} and \emph{sint\_b} and returns $\{-1, 0, 1\}$ if \emph{sint\_a} $\{ <, =, > \}$ \emph{sint\_b}. This extension is used to compare arbitrarily large integers in Tcl scripts. Because NAN tags (see Section \ref{cxtn0:sarb0:seab0}) cannot be logically compared, this extension will signal an error if either parameter is a NAN tag. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint intcmp -5 -3 -1 % arbint intcmp -5 -5 0 % arbint intcmp 7 5 1 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{arbint rncmp} Tcl extension, Section \ref{cxtn0:srne0:srcm0}, which performs a similar function for arbitrary rational numbers. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint intadd} Extension} %Subsection Tag: add0 \label{cxtn0:sarb0:sadd0} \index{arbint intadd@\emph{arbint intadd}} \index{intadd@\emph{intadd}} \begin{tclcommandname}{arbint intadd}% calculates and returns as a string the sum of two integers. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint intadd}{sint sint} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension returns the sum of two integer arguments, or one of the NAN tags described in Section \ref{cxtn0:sarb0:seab0} if an overflow occurs. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint intadd 1e20 21643215482123164 100021643215482123164 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{intadd} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sadd0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint intsub} Extension} %Subsection Tag: mod0 \label{cxtn0:sarb0:ssub0} \index{arbint intsub@\emph{arbint intsub}} \index{intsub@\emph{intsub}} \begin{tclcommandname}{arbint intsub}% calculates and returns as a string the difference of two integers. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint intsub}{sint sint} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension returns the difference of two integer arguments, or one of the NAN tags described in Section \ref{cxtn0:sarb0:seab0} if an overflow occurs. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint intsub 123846129436219 1e25 -9999999999876153870563781 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{intsub} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:ssub0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint intmul} Extension} %Subsection Tag: mul0 \label{cxtn0:sarb0:smul0} \index{arbint intmul@\emph{arbint intmul}} \index{intmul@\emph{intmul}} \begin{tclcommandname}{arbint intmul}% calculates and returns as a string the product of two integers. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint intmul}{sint sint} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension returns the product of two integer arguments. The result of this extension will always be either a NAN tag (see Section \ref{cxtn0:sarb0:seab0}) or an integer. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint intmul -329749813264962165493214963541976325 4.36463214521843123e38 -143923663485602892702423181098245942606484617030062975000000000000000000000 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{intmul} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:smul0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint intdiv} Extension} %Subsection Tag: div0 \label{cxtn0:sarb0:sdiv0} \index{arbint intdiv@\emph{arbint intdiv}} \index{intdiv@\emph{intdiv}} \begin{tclcommandname}{arbint intdiv}% calculates and returns as a string the quotient of two integers. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint intdiv}{sint\_dividend sint\_divisor} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension returns the quotient of two integer arguments. The first integer argument is interpreted to be the dividend, and the second the divisor. The quotient is without remainder, i.e. what is actually returned is \begin{equation} sgn(dividend \cdot divisor) \left\lfloor{\frac{|dividend|}{|divisor|}}\right\rfloor , \end{equation} or one of the NAN tags described in Section \ref{cxtn0:sarb0:seab0} if division by zero is attempted. Note that division by zero is not an error (as far as a Tcl script is concerned): the only outcome is that the result will be assigned a symbolic NAN tag rather than a string of digits representing an integer. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint intdiv 2364832165653218648321543215848236458124 2854871354812543821 828349817467869034672 % arbint intdiv 2364832165653218648321543215848236458124 0 GMP_INTS_EF_INTOVF_POS \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{intdiv} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sdiv0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint intmod} Extension} %Subsection Tag: mod0 \label{cxtn0:sarb0:smod0} \index{arbint intmod@\emph{arbint intmod}} \index{intmod@\emph{intmod}} \begin{tclcommandname}{arbint intmod}% calculates and returns as a string the modulo of two integers. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint intmod}{sint\_dividend sint\_divisor} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension returns the remainder resulting from the division of two integer arguments. The first integer argument is interpreted to be the dividend, and the second the divisor. The sign of the remainder is always chosen so that the following relationship holds: \begin{equation} dividend \; div \; divisor + \frac{dividend \; mod \; divisor}{divisor} = \frac{dividend}{divisor}, \end{equation} where the \emph{div} operator is as explained in Section \ref{cxtn0:sarb0:sdiv0} for the \emph{arbint intdiv} extension. If division by zero is attempted, this extension returns one of the NAN tags described in Section \ref{cxtn0:sarb0:seab0}. Note that division by zero is not an error (as far as a Tcl script is concerned): the only outcome is that the result will be assigned a symbolic NAN tag rather than a string of digits representing an integer. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint intmod 264321654632432421 2175438321654 1547674828113 % arbint intmod 264321654632432421 0 GMP_INTS_EF_INTOVF_POS \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{intmod} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:smod0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint intexp} Extension} %Subsection Tag: exp0 \label{cxtn0:sarb0:sixp0} \index{arbint intexp@\emph{arbint intexp}} \index{intexp@\emph{intexp}} \begin{tclcommandname}{arbint intexp}% computes and returns as a string one integer exponentiated to the power of another, $base^{exponent}$. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint intexp}{sint\_base uint32\_exponent} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension exponentiates an integer to a non-negative power. For simplicity and convenience, $0^0$ will return 1, although this is inconsistent with the mathematical definition. All other exponentiations are as expected. The method used to exponentiate is simple squaring and multiplying based on the bit pattern of the exponent, as discussed in \cite{bibref:b:knuthclassic2ndedvol2}, pp. 461-462. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint intexp 47 69 2370021018513446695324337468306899241173950476009917473665218657220346081293500 4143894985892600403244809901800125167 % arbint intexp 1 0 1 % arbint intexp 0 0 1 % arbint intexp 0 1 0 % arbint intexp 0 19237498 0 % arbint intexp -47 69 -237002101851344669532433746830689924117395047600991747366521865722034608129350 04143894985892600403244809901800125167 % arbint intexp -47 -69 arbint intexp: "-69" is not a recognized unsigned 32-bit integer. % arbint intexp 193461926436214 99999999 GMP_INTS_EF_INTOVF_TAINT_POS \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{intexp} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sixp0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint intfac} Extension} %Subsection Tag: fac0 \label{cxtn0:sarb0:sfac0} \index{arbint intfac@\emph{arbint intfac}} \index{intfac@\emph{intfac}} \begin{tclcommandname}{arbint intfac}% computes and returns as a string the factorial ($!$) of the integer argument supplied. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint intfac}{uint32} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension returns the factorial of an integer argument. Any of the symbolic NAN strings described in Section \ref{cxtn0:sarb0:seab0} will cause a return value of an appropriate symbolic NAN string. Strings that cannot be parsed as integers or NAN strings, strings that represent negative integers, and strings that represent non-negative integers that will not fit in 32 bits will generate an error. As of this writing, 200! requires about 1 second to compute on a 600MHz PC. Although this function will calculate factorials of any size up to 100,000 digits, it is not recommended to use this function above about 200! as the increase in computation time appears to be exponential with respect to the argument. This may improve in the future as algorithmic enhancements are made. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint intfac 129 4974504222477287440390234150412680963965661113713884314596886402265216893219635 5119328515747917449637889876686464600208839390308261862352651828829226610077151 044469167497022952331930501120000000000000000000000000000000 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{intfac} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sifc0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint intgcd} Extension} %Subsection Tag: gcd0 \label{cxtn0:sarb0:sgcd0} \index{arbint intgcd@\emph{arbint intgcd}} \index{intgcd@\emph{intgcd}} \begin{tclcommandname}{arbint intgcd}% calculates and returns as a string the g.c.d. (greatest common divisor) of two integers. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint intgcd}{sint sint} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension returns the g.c.d. of two integer arguments. If either argument is 0, the result will be 1. If either argument is negative, the absolute value of the argument will be used in its place. The result of this extension will always be either a NAN tag (see Section \ref{cxtn0:sarb0:seab0}) or an integer greater than or equal to 1. The algorithm employed is the \emph{Modern Euclidian Algorithm} as described in \cite{bibref:b:knuthclassic2ndedvol2}, p. 337. Although faster algorithms for computer implementation do exist, this is the simplest and most direct algorithm. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint intgcd 263130836933693530167218012160000000 503580 4620 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{intgcd} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sgcd0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint intlcm} Extension} %Subsection Tag: lcm0 \label{cxtn0:sarb0:slcm0} \index{arbint intgcd@\emph{arbint intlcm}} \index{intlcm@\emph{intlcm}} \begin{tclcommandname}{arbint intlcm}% calculates and returns as a string the l.c.m. (least common multiple) of two integers. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint intlcm}{sint sint} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension returns the l.c.m. of two integer arguments. If either argument is 0, the argument will be treated as if it were 1. If either argument is negative, the absolute value of the argument will be used in its place. The result of this extension will always be either a NAN tag (see Section \ref{cxtn0:sarb0:seab0}) or an integer greater than or equal to 1. The algorithm employed is to calculate the g.c.d. of the arguments using the \emph{Modern Euclidian Algorithm} as described in \cite{bibref:b:knuthclassic2ndedvol2}, p. 337; then to divide the product of the arguments by their g.c.d., as implied by \cite{bibref:b:knuthclassic2ndedvol2}, p. 334, Equation 10. Both sides of this equation can be divided by $\gcd(u,v)$ to yield \begin{equation} lcm(u,v) = \frac{uv}{\gcd(u,v)}, \end{equation} and this is the relationship used to calculated the l.c.m. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint intlcm 64 100 1600 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{intlcm} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:slcm0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Rational Number Extensions} %Section Tag: RNE0 This section describes extensions that implement rational number arithmetic. In most cases, the rational number extensions described in this section are liberal in the representations of rational numbers they accept, but always produce results as integer components separated by the forward slash character. This means that the rational number extensions described in this section can exchange data freely---the output of any of the extensions is suitable as input for another extension. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint rnred} Extension} %Subsection Tag: RNR0 \label{cxtn0:srne0:srnr0} \index{arbint rnred@\emph{arbint rnred}} \index{rnred@\emph{rnred}} \begin{tclcommandname}{arbint rnred}% reduces a rational number to lowest terms and normalizes it. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint rnred}{srn} \end{tclcommandsynopsis} \begin{tclcommanddescription} The \emph{arbint rnred} extension reduces a rational number to its lowest terms and normalizes it. By \emph{reducing} a rational number and normalizing it, we mean the application of the following rules. \begin{enumerate} \item Any number with a numerator of zero is given the representation 0/1, i.e. 0/1 is the canonical representation of zero. \item Any number with a denominator of zero is given the representation 1/0, i.e. 1/0 is the canonical representation of ``division by zero''. \item Rational numbers which are effectively positive are normalized to have a positve numerator and positive denominator. \item Rational numbers which are effectively negative are normalized to have a negative numerator and positive denominator. \item Any common factors are removed from the numerator and denominator, i.e. the numerator and denominator are made coprime. \end{enumerate} Note that one behavior above may be unexpected---the \emph{arbint rnred} extension \emph{will} accept a rational number specified with a denominator of zero, and will normalize it to 1/0. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint rnred 422.414 211207/500 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{rnred} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srnr0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint rnadd} Extension} %Subsection Tag: RAD0 \label{cxtn0:srne0:srad0} \index{arbint rnadd@\emph{arbint rnadd}} \index{rnadd@\emph{rnadd}} \begin{tclcommandname}{arbint rnadd}% adds two rational numbers to produce a normalized rational result. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint rnadd}{srn srn} \end{tclcommandsynopsis} \begin{tclcommanddescription} The \emph{arbint rnadd} extension adds two rational numbers to produce a normalized rational result. If either of the two rational input arguments has a denominator of zero, the string ``NAN'' will be returned. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint rnadd 3.1415 64/259 1755297/518000 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{rnadd} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srna0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint rnsub} Extension} %Subsection Tag: RSB0 \label{cxtn0:srne0:srsb0} \index{arbint rnsub@\emph{arbint rnsub}} \index{rnsub@\emph{rnsub}} \begin{tclcommandname}{arbint rnsub}% subtracts two rational numbers to produce a normalized rational result. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint rnsub}{srn\_arg1 srn\_arg2} \end{tclcommandsynopsis} \begin{tclcommanddescription} The \emph{arbint rnsub} extension subtracts two rational numbers to produce a normalized rational result. The second argument is subtracted from the first, i.e. the result $arg_2 - arg_1$ is formed. If either of the two rational input arguments has a denominator of zero, the string ``NAN'' will be returned. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint rnsub 3.129 122/451 1289179/451000 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{rnsub} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srsb0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint rnmul} Extension} %Subsection Tag: RMU0 \label{cxtn0:srne0:srmu0} \index{arbint rnmul@\emph{arbint rnmul}} \index{rnmul@\emph{rnmul}} \begin{tclcommandname}{arbint rnmul}% multiplies two rational numbers to produce a normalized rational result. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint rnmul}{srn srn} \end{tclcommandsynopsis} \begin{tclcommanddescription} The \emph{arbint rnmul} extension multiplies two rational numbers to produce a normalized rational result. If either of the two rational input arguments has a denominator of zero, the string ``NAN'' will be returned. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint rnmul 3.14 32/491 2512/12275 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{rnmul} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srmu0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint rndiv} Extension} %Subsection Tag: RDV0 \label{cxtn0:srne0:srdv0} \index{arbint rndiv@\emph{arbint rndiv}} \index{rndiv@\emph{rndiv}} \begin{tclcommandname}{arbint rndiv}% divides two rational numbers to produce a normalized rational result. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint rndiv}{srn srn} \end{tclcommandsynopsis} \begin{tclcommanddescription} The \emph{arbint rndiv} extension divides two rational numbers to produce a normalized rational result. If either of the two rational input arguments has a denominator of zero, or if the divisor is zero, the string ``NAN'' will be returned. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint rndiv 3.14 32/491 77087/1600 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{rnmul} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srdv0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint rncmp} Extension} %Subsection Tag: RCM0 \label{cxtn0:srne0:srcm0} \index{arbint rncmp@\emph{arbint rncmp}} \index{rncmp@\emph{rncmp}} \begin{tclcommandname}{arbint rncmp}% compares two rational numbers. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint rncmp}{srn\_arg1 srn\_arg2} \end{tclcommandsynopsis} \begin{tclcommanddescription} The \emph{arbint rncmp} extension compares two rational numbers and returns $\{-1, 0, 1\}$ if $arg_1$ $\{<, =, >\}$ $arg_2$. The rational numbers do not need to be reduced or normalized in any way. Any combination of signs on the numerators and denominators is permitted, and the numerators and denominators are not required to be coprime. If for any reason the extension cannot compare the rational numbers, an error message will be returned and the extension will return \texttt{TCL\_ERROR}, which will normally cause a script to fail. The reason for the error return is that if the two rational number cannot be compared, in most cases it is logically impossible for a script to continue. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint rncmp -4/-7 0.5 1 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{arbint intcmp} Tcl extension, Section \ref{cxtn0:sarb0:scmp0}, which performs a similar function for arbitrary integers. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Number Theory Extensions} %Section Tag: NTH0 \label{cxtn0:snth0} This section describes extensions that are related to number theory. Extensions that deal with continued fractions are included in this category because of the relationship between continued fractions and number theory. Any extensions related to number theory that must process large integers are still a subextension of \texttt{arbint}.\footnote{This was done to avoid creating an excessive number of software modules and Tcl extensions.} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint cfratnum} Extension} %Subsection Tag: CFR0 \label{cxtn0:snth0:scfr0} \index{arbint cfratnum@\emph{arbint cfratnum}} \index{cfratnum@\emph{cfratnum}} \begin{tclcommandname}{arbint cfratnum}% calculates the partial quotients and convergents of a non-negative rational number. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint cfratnum}{urn} \end{tclcommandsynopsis} \begin{tclcommanddescription} This extension calculates the partial quotients and convergents of of a non-negative rational number. The results are returned as a string containing integers separated by spaces. The integers are arranged in consecutive triplets of the form ``$a_k \; p_k \; q_k$''. Such a string can be converted to a list and processed from a Tcl script. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint cfratnum 3.14 3 3 1 7 22 7 7 157 50 \end{verbatim} \end{scriptsize} In the sample invocation above, note that $a_0 = 3$, $p_0 = 3$, $q_0 = 1$, $a_1 = 7$, $p_1 = 22$, $q_1 = 7$, $a_2 = 7$, $p_2 = 157$, and $q_2 = 50$. \end{tclcommandsampleinvocations} \begin{tclcommandseealso} See also the \emph{cfratnum} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:snth0:scfr0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint cfbrapab} Extension} %Subsection Tag: BRA0 \label{cxtn0:snth0:sbra0} \index{arbint cfbrapab@\emph{arbint cfbrapab}} \index{cfbrapab@\emph{cfbrapab}} \begin{tclcommandname}{arbint cfbrapab}% finds best rational approximations to a supplied rational number in either the Farey series of order $k_{MAX}$ (denoted $F_{k_{MAX}}$), or in a rectangular region of the integer lattice bounded by $k \leq k_{MAX}$ and $h \leq h_{MAX}$ (denoted $F_{k_{MAX}, \overline{h_{MAX}}}$). \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint cfbrapab}{srn uint\_kmax [options]} \tclcommandsynopsisline{arbint cfbrapab}{srn uint\_kmax uint\_hmax [options]} \end{tclcommandsynopsis} \begin{tclcommanddescription} When used without options, this extension returns the closest rational number to the specified rational number in $F_{k_{MAX}}$ (if only $k_{MAX}$ is specified) or in $F_{k_{MAX}, \overline{h_{MAX}}}$ (if both $k_{MAX}$ and $h_{MAX}$ are specified). If the rational number specified is already in the series of interest, its reduced form is returned. If the rational number supplied is equidistant from the two closest formable rational numbers in the series of interest, the neighbor of smaller magnitude (absolute value) is returned. When operating in $F_{k_{MAX}}$, there are no practical constraints on the size of rational numbers that this extension can approximate. However, when operating in $F_{k_{MAX}, \overline{h_{MAX}}}$, this extension will not accept rational numbers outside the interval $[-h_{MAX}, h_{MAX}]$ (note that $-h_{MAX}/1$ and $h_{MAX}/1$ are the smallest and largest numbers that can be formed when the numerator of the rational approximations is constrained). Any attempt to approximate a rational number outside $[-h_{MAX}, h_{MAX}]$ will result in a Tcl error, which will normally terminate a script. The \texttt{-neversmaller} and \texttt{-neverlarger} options cause the extension to always choose the larger and smaller neighbors (rather than the closer neighbor), respectively. These options are useful when approximations are desired that do not underestimate or overestimate the function of interest for large values in the domain. These parameters do not affect the behavior if the rational number supplied is already in the series of interest---the reduced form of the specified number is returned in the case of equality. The \texttt{-neversmaller} and \texttt{-neverlarger} options must be used alone, with no other options. The \texttt{-pred} and \texttt{-succ} options cause this extension to calculate either the predecessor or successor to the rational number specified in the series of interest. If the number specified is already in series of interest, its predecessor or successor is returned. If the number specified is not in the series of interest, the left or right neighbor is returned. If no predecessor, successor, or left or right neighbor exist, an error is generated. These options (\texttt{-pred} or \texttt{-succ}) must be used alone, with no other options. The normal behavior of this extension is to return a single rational number, as described above. The \texttt{-n \emph{uint32\_count}} option will cause the extension to return \emph{count} rational numbers on each side of the rational number specified. If the rational number specified is already in the series of interest, it will be returned as well, normally\footnote{If the set of returned rational numbers is not clipped at $-h_{MAX}/1$ or $h_{MAX}/1$.} resulting in an odd number of rational numbers returned. If the rational number specified is not already in the series of interest, an even number of rational numbers will normally be returned. The rational numbers returned are prefixed with integer indices, which indicate their ordinal distance from the rational number to be approximated (see the invocation examples below). The index of 0 is reserved for the reduced form of the rational number specified, and and a rational number with this index will be in the output only if the rational number supplied was already in the series of interest. The rational numbers returned will be formatted as integer indices and slash-separated integers, separated by single spaces and arranged in ascending order.. If the number of rational numbers requested by this option exceeds the number available, the sequence will simply be truncated at $-h_{MAX}/1$ or $h_{MAX}/1$, as appropriate. Any request for more than 10,000 neighbors (on each side) will be clipped to 10,000. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} \begin{scriptsize} \begin{verbatim} % arbint cfbrapab 1.6093 255 346/215 % arbint cfbrapab 1.6093 255 255 243/151 % arbint cfbrapab 1.6093 255 255 -neversmaller 103/64 % arbint cfbrapab 1.6093 255 255 -neverlarger 243/151 % arbint cfbrapab 1.6093 255 255 -n 20 -20 143/89 -19 188/117 -18 233/145 -17 45/28 -16 217/135 -15 172/107 -14 127/79 -13 209/130 -12 82/51 -11 201/125 -10 119/74 -9 156/97 -8 193/120 -7 230/143 -6 37/23 -5 251/156 -4 214/133 -3 177/110 -2 140/87 -1 243/151 1 103/64 2 169/105 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 182/113 12 211/131 13 240/149 14 29/18 15 253/157 16 224/139 17 195/121 18 166/103 19 137/85 20 245/152 % arbint cfbrapab 1.6093 255 255 -succ 103/64 % arbint cfbrapab 1.6093 255 255 -pred 243/151 % arbint cfbrapab 2/3 255 255 -pred 169/254 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} \begin{tclcommandseealso} This extension uses the continued fraction algorithms presented in Chapter \ccfrzeroxrefhyphen{}\ref{ccfr0}. See also the \emph{cfratnum} DOS command-line utility, Section \cdcmzeroxrefhyphen{}\ref{cdcm0:snth0:sbra0}. \end{tclcommandseealso} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The \texttt{arbint const} Extension} %Subsection Tag: CEX0 \label{cxtn0:snth0:scex0} \index{arbint const@\emph{arbint const}} \index{const (Tcl arbint sub-extension)@\emph{const} (Tcl \emph{arbint} sub-extension)} \begin{tclcommandname}{arbint const}% returns a string representing the value of important mathematical and conversion constants (such as the value of $\pi$ or $e$, or the conversion factor from miles to kilometers). \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{arbint const}{const\_tag} \tclcommandsynopsisline{arbint const}{const\_tag uint32\_ndigits} \end{tclcommandsynopsis} \begin{tclcommanddescription} The \emph{const} subextension returns the value (as a string) of constants that may be useful in engineering work. Such constants may include mathematically significant numbers (such as \index{pi@$\pi$ (transcendental constant)}$\pi$ or \index{e@$e$ (transcendental constant)}$e$), or useful conversion factors (the conversion factor from miles to kilometers, for example). These string constants can be used in calculations involving rational numbers. All constants are simply tabulated as character strings within the `C' source code. Mathematically significant numbers (which, to the best of the author's knowledge are always irrational and usually transcendental, as mathematicians don't seem to have any lasting interest in specific integers or rational numbers) are available to about 1,000 significant digits, and have been obtained from various web pages. It is reasoned that 1,000 significant digits should be adequate for engineering applications. Measurement unit conversion constants have typically been obtained from \emph{NIST Special Publication 811} \cite{bibref:b:nistsp811:1995ed}. These constants are always tabulated with their full precision, since no physical constant can be precise to more than several decimal places. If the number of significant figures is not specified, each constant is returned as a string with a default number of decimal places (typically about 30). In most cases, the default number of decimal places provides more than enough precision for engineering work. However, an optional parameter allows more or fewer digits to be obtained, up to the maximum number tabulated internally in the software. The default number of decimal places is a compromise between calculation speed and accuracy. It is felt in most cases that the default number of decimal places provides excellent accuracy and good calculation speed. Please e-mail the authors if you would like additional useful constants included. Because the list of tabulated constants may grow and shrink, it would not be a sound decision to document the constants which are included here. Instead, use \emph{arbint const} with an invalid tag, and the software itself will list all of the internally tabulated constants and their significance. \end{tclcommanddescription} \begin{tclcommandsampleinvocations} Please note that the sample invocation below was created using v1.05 of the tool set. The list of constants may have grown since this example was created. Please poll the software directly by using \emph{arbint const} with an invalid tag to obtain the list of constants and their significance. \begin{scriptsize} \begin{verbatim} % arbint const xxx arbint const: "xxx" is not a recognized constant. Available constants are: e (1000 digits available) Historically significant transcendental constant. Digits obtained from http://fermi.udw.ac.za/physics/e.html on 08/17/01. g_si (6 digits available) Gravitational acceleration in SI units, meters per second**2. Obtained from NIST Special Publication 811 on 08/17/01. in2m (3 digits available) Multiplicative conversion factor from inches to meters. Obtained from NIST Special Publication 811 on 08/17/01. mi2km (7 digits available) Multiplicative conversion factor from miles to kilometers. Obtained from NIST Special Publication 811 on 08/17/01. pi (1201 digits available) Transcendental constant supplying ratio of a circle's circumference to its diameter. Digits obtained from http://www.joyofpi.com/ pi.htm on 08/17/01. sqrt5 (1040 digits available) The square root of 5. Digits obtained from http://home.earthlink.net/~maryski/sqrt51000000.txt on 08/17/01. % arbint const pi 3.14159265358979323846264338327 % arbint const pi 100 3.141592653589793238462643383279502884197169399375105820974944592307816406286208998628034825342117067 % arbint const pi 10 3.141592653 % arbint cfbrapab [arbint const pi 100] 65535 65535 65298/20785 \end{verbatim} \end{scriptsize} \end{tclcommandsampleinvocations} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Miscellaneous Extensions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{credits} \index{credits@\emph{credits}} \begin{tclcommandname}{credits}% returns information about authorship of software components. \end{tclcommandname} \begin{tclcommandsynopsis} \tclcommandsynopsisline{credits}{} \tclcommandsynopsisline{credits}{searchstring} \end{tclcommandsynopsis} \begin{tclcommanddescription} The \emph{credits} command returns a list of contributors to the tools, their area(s) of contribution, and e-mail addresses. The volume of information returned can be reduced by using an optional \emph{searchstring}. \tclcommanddescsynopsisline{credits}{} \begin{tclcommandinternaldescription} Returns the complete list of contributors to the tools and their area(s) of contribution. \end{tclcommandinternaldescription} \tclcommanddescsynopsisline{credits}{searchstring} \begin{tclcommandinternaldescription} Returns all credit records containing \emph{searchstring}. Most commonly, this option is used to search for information about a specific command by using the command name as the \emph{searchstring}, or about a specific individual by using a component of the individual's name as the \emph{searchstring}. \end{tclcommandinternaldescription} \end{tclcommanddescription} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \noindent\begin{figure}[!b] \noindent\rule[-0.25in]{\textwidth}{1pt} \begin{tiny} \begin{verbatim} $RCSfile: c_xtn0.tex,v $ $Source: /home/dashley/cvsrep/e3ft_gpl01/e3ft_gpl01/dtaipubs/esrgubka/c_xtn0/c_xtn0.tex,v $ $Revision: 1.11 $ $Author: dtashley $ $Date: 2003/04/03 19:49:36 $ \end{verbatim} \end{tiny} \noindent\rule[0.25in]{\textwidth}{1pt} \end{figure} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % $Log: c_xtn0.tex,v $ % Revision 1.11 2003/04/03 19:49:36 dtashley % Global corrections to typeface of "gcd" made as per Jan-Hinnerk Reichert's % recommendation. % % Revision 1.10 2001/08/18 18:37:56 dtashley % Preparation for v1.05 release. % % Revision 1.9 2001/08/16 19:53:27 dtashley % Beginning to prepare for v1.05 release. % % Revision 1.8 2001/08/12 10:15:33 dtashley % Safety check-in. Substantial progress. % % Revision 1.7 2001/08/10 00:56:07 dtashley % Completion of basic rational number arithmetic utilities and extensions. % % Revision 1.6 2001/08/08 02:25:03 dtashley % Completion of RNRED utility and ARBINT RNRED Tcl extension. % % Revision 1.5 2001/08/07 10:46:44 dtashley % Completion of CFRATNUM Tcl extension and DOS command-line utility. % % Revision 1.4 2001/08/01 03:37:39 dtashley % Finished most primitive integer operations, both as Tcl extensions and % as DOS command-line utilities, such as addition, subtraction, % multiplication, division, and modulo. % % Revision 1.3 2001/07/30 02:54:17 dtashley % INTFAC extension and command-line utility finished. % % Revision 1.2 2001/07/01 20:50:58 dtashley % Move out of binary mode for use with CVS. % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % $History: c_xtn0.tex $ % % ***************** Version 3 ***************** % User: Dashley1 Date: 2/10/01 Time: 2:03a % Updated in $/uC Software Multi-Volume Book (A)/Chapter, XTN0, IjuScripter-IjuConsole Tcl-Tk Extensions % Completion of Farey series chapter. % % ***************** Version 2 ***************** % User: Dashley1 Date: 1/01/01 Time: 8:13p % Updated in $/uC Software Multi-Volume Book (A)/Chapter, XTN0, IjuScripter-IjuConsole Tcl-Tk Extensions % Edits. % % ***************** Version 1 ***************** % User: Dashley1 Date: 12/31/00 Time: 9:34p % Created in $/uC Software Multi-Volume Book (A)/Chapter, XTN0, IjuScripter-IjuConsole Tcl-Tk Extensions % Initial check-in. % %End of file C_XTN0.TEX