Parent Directory | Revision Log

Revision **5** -
(**hide annotations**)
(**download**)
(**as text**)

*Thu Oct 6 23:27:41 2016 UTC*
(7 years, 11 months ago)
by *dashley*

File MIME type: application/x-tex

File size: 74604 byte(s)

File MIME type: application/x-tex

File size: 74604 byte(s)

Initial commit after migrating from CVS.

1 | dashley | 5 | %$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 $ |

2 | |||

3 | \chapter[\cxtnzeroshorttitle{}]{\cxtnzerolongtitle{}} | ||

4 | |||

5 | \label{cxtn0} | ||

6 | |||

7 | \beginchapterquote{``One way to prevent progress is by arguing that any first | ||

8 | step is unfair to somebody.''} | ||

9 | {Unknown} | ||

10 | |||

11 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

12 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

13 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

14 | \section{Introduction} | ||

15 | %Section Tag: INT0 | ||

16 | \label{cxtn0:sint0} | ||

17 | |||

18 | The Tcl scripting language provides for \emph{extensions}, which are | ||

19 | compiled-in commands added to the language. These extensions have advantages | ||

20 | for performance, because they allow the high-frequency interactions to occur | ||

21 | in compiled code, and the lower-frequency interactions to occur in | ||

22 | a Tcl script. | ||

23 | |||

24 | This chapter describes the extensions that have been added to the Tcl | ||

25 | interpreters which are part of \emph{The Iju Tool Set}. | ||

26 | |||

27 | Many of the parameter formats are common between the Tcl extensions | ||

28 | (described in this chapter) and the DOS command-line | ||

29 | utilities (described in Chapter | ||

30 | \cdcmzeroxrefhyphen{}\ref{cdcm0}). For this reason, to avoid | ||

31 | redundancy of documentation, the parameter formats described | ||

32 | in Section \ctinzeroxrefhyphen{}\ref{ctin0:sccl0} apply both to the | ||

33 | Tcl extensions | ||

34 | and the DOS command-line utilities. | ||

35 | |||

36 | |||

37 | |||

38 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

39 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

40 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

41 | \section{Version Control Extensions} | ||

42 | |||

43 | |||

44 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

45 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

46 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

47 | \subsection{vcinfo} | ||

48 | |||

49 | \index{vcinfo@\emph{vcinfo}} | ||

50 | \begin{tclcommandname}{vcinfo}% | ||

51 | retrieves embedded static version and version control information for | ||

52 | IjuScripter or IjuConsole. | ||

53 | This allows a script to determine which version of script interpreter it is | ||

54 | running under. | ||

55 | \end{tclcommandname} | ||

56 | |||

57 | \begin{tclcommandsynopsis} | ||

58 | \tclcommandsynopsisline{vcinfo}{-ijutoolsversion} | ||

59 | \tclcommandsynopsisline{vcinfo}{?-crconly? -fileversion filename} | ||

60 | \tclcommandsynopsisline{vcinfo}{?-crconly? -extensionversion extensionname} | ||

61 | \tclcommandsynopsisline{vcinfo}{-buildmanifest} | ||

62 | \end{tclcommandsynopsis} | ||

63 | |||

64 | \begin{tclcommanddescription} | ||

65 | The \emph{vcinfo} command returns information about the version of the | ||

66 | IjuScripter or IjuConsole executable program, about the version of | ||

67 | a specific source file, or [collectively] about the version of all files | ||

68 | which [directly] contribute to the behavior of an embedded Tcl/Tk extension. | ||

69 | This command can be used to | ||

70 | inquire about the version of the executable program or certain of its | ||

71 | components. | ||

72 | |||

73 | Most commonly, this command is used to help assure reproducibility | ||

74 | of a script's behavior by coding a script so that it will | ||

75 | run only under a specific version(s) of executable. | ||

76 | |||

77 | \tclcommanddescsynopsisline{vcinfo}{-ijutoolsversion} | ||

78 | \begin{tclcommandinternaldescription} | ||

79 | Returns a string identifying the version number of the IjuScripter or IjuConsole | ||

80 | executable. The string will be of the form ``vm.nx'', where \emph{v} is the letter | ||

81 | ``v'', \emph{m} is the major version number, \emph{n} is the minor version number, and | ||

82 | \emph{x} is an optional lower-case letter identifying a service release which fixes defects | ||

83 | but adds no new functionality. | ||

84 | |||

85 | For example, a return value of ``v1.03'' would identify version 1.03. A return | ||

86 | value of ``v1.03c'' would identify the third service release to version 1.03; with | ||

87 | the service release designed to correct defects present in version 1.03b, but adding | ||

88 | no new functionality. | ||

89 | \end{tclcommandinternaldescription} | ||

90 | |||

91 | \tclcommanddescsynopsisline{vcinfo}{-fileversion filename} | ||

92 | \begin{tclcommandinternaldescription} | ||

93 | (Not yet implemented.) Returns a string with version control information for the file | ||

94 | \emph{filename}, which must be part of the IjuScripter or IjuConsole build. | ||

95 | An error is generated if a \emph{filename} which is not part of the build | ||

96 | is supplied. This form of the \emph{vcinfo} command is not normally used from a script. | ||

97 | \end{tclcommandinternaldescription} | ||

98 | |||

99 | \tclcommanddescsynopsisline{vcinfo}{-crconly -fileversion filename} | ||

100 | \begin{tclcommandinternaldescription} | ||

101 | (Not yet implemented.) Returns the CRC32 of the the string result of the command above. | ||

102 | Note that the value returned is the CRC of the version control information embedded in the file | ||

103 | rather than the CRC of the file. | ||

104 | \emph{filename} must be part of the IjuScripter or IjuConsole build, and | ||

105 | an error is generated if a \emph{filename} which is not part of the build is supplied. | ||

106 | This form is | ||

107 | useful because it supplies a terse result of eight hexadecimal digits which can easily | ||

108 | establish with a probability of about $1-2^{-32}$ that two versions of IjuScripter or IjuConsole | ||

109 | have the same file component; or establish with unity probability that they do not. | ||

110 | \end{tclcommandinternaldescription} | ||

111 | |||

112 | \tclcommanddescsynopsisline{vcinfo}{-extensionversion extensionname} | ||

113 | \begin{tclcommandinternaldescription} | ||

114 | (Not yet implemented.) Returns a string with version control information for all | ||

115 | files which contribute directly to the behavior of the Tcl extension \emph{extensionname}, | ||

116 | which must be part of the IjuScripter or IjuConsole static build. | ||

117 | An error is generated if an \emph{extensionname} which is not part of the build | ||

118 | is supplied. | ||

119 | \end{tclcommandinternaldescription} | ||

120 | |||

121 | \tclcommanddescsynopsisline{vcinfo}{-crconly -extensionversion extensionname} | ||

122 | \begin{tclcommandinternaldescription} | ||

123 | (Not yet implemented.) Returns the CRC32 of the the string result of the command above. | ||

124 | Note that the value returned is the CRC of the version control information embedded in the file(s) | ||

125 | rather than the CRC(s) of the file(s). | ||

126 | \emph{extensionname} must be part of the IjuScripter or IjuConsole build, and | ||

127 | an error is generated if an \emph{extensionname} which is not part of the build is supplied. | ||

128 | This form is | ||

129 | useful because it supplies a terse result of eight hexadecimal digits which can easily | ||

130 | establish with a probability of about $1-2^{-32}$ that two versions of IjuScripter or IjuConsole | ||

131 | have the same extension component(s); or establish with unity probability that they do not. | ||

132 | \end{tclcommandinternaldescription} | ||

133 | |||

134 | \tclcommanddescsynopsisline{vcinfo}{-crconly -buildmanifest} | ||

135 | \begin{tclcommandinternaldescription} | ||

136 | (Not yet implemented.) Returns the full combined build manifest of IjuScripter and IjuConsole. | ||

137 | This includes size and CRC information for every file involved in the build. This form | ||

138 | of \emph{vcinfo} is provided for assistance in defect diagnosis. | ||

139 | \end{tclcommandinternaldescription} | ||

140 | |||

141 | \end{tclcommanddescription} | ||

142 | |||

143 | |||

144 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

145 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

146 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

147 | \section{File Transformation Extensions} | ||

148 | |||

149 | |||

150 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

151 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

152 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

153 | \section{CRC, Checksum, And Hash Extensions} | ||

154 | %Section Tag: CRC0 | ||

155 | |||

156 | |||

157 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

158 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

159 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

160 | \subsection{crc32} | ||

161 | %Subsection Tag: CRC0 | ||

162 | \label{cxtn0:scrc0:scrc0} | ||

163 | |||

164 | |||

165 | \index{crc32@\emph{crc32}} | ||

166 | \begin{tclcommandname}{crc32}% | ||

167 | generates the CRC-32 of a file or string. This CRC can be reliably used to obtain | ||

168 | digital signatures of files or data. | ||

169 | \end{tclcommandname} | ||

170 | |||

171 | \begin{tclcommandsynopsis} | ||

172 | \tclcommandsynopsisline{crc32}{filename} | ||

173 | \tclcommandsynopsisline{crc32}{-string binarystringval} | ||

174 | |||

175 | Note: as of 01/01/01, the ``stateful'' forms below are not yet implemented. | ||

176 | |||

177 | \tclcommandsynopsisline{crc32}{-initialstate} | ||

178 | \tclcommandsynopsisline{crc32}{-advancestate state filename} | ||

179 | \tclcommandsynopsisline{crc32}{-advancestate -string state binarystringval} | ||

180 | \tclcommandsynopsisline{crc32}{-crcfromstate state} | ||

181 | \end{tclcommandsynopsis} | ||

182 | |||

183 | \begin{tclcommanddescription} | ||

184 | The \emph{crc32} command forms the CRC-32 of the binary contents of a file | ||

185 | or of the binary contents of a string. The CRC-32 is useful as a digital | ||

186 | signature, and can be used with unity probability to determine that two | ||

187 | files are different, or with a probability of about $1-2^{-32}$ to determine | ||

188 | that two files are almost certainly identical. | ||

189 | |||

190 | In the invocations below, the CRC-32 is always returned as a 10-character ASCII string | ||

191 | of the form \emph{``0xDDDDDDDD''}, where \emph{``DDDDDDDD''} is the hexadecimal representation | ||

192 | of the 32-bit CRC-32, and \emph{``0x''} is a constant 2-character prefix | ||

193 | (the ``zero'' digit followed by ``x'') which is included for | ||

194 | aesthetics. It is guaranteed that: | ||

195 | |||

196 | \begin{itemize} | ||

197 | \item The string returned will be exclusively ASCII. | ||

198 | \item The string will have a length of exactly 10 characters. | ||

199 | \item The first two characters of the string will be \emph{``0x''}. | ||

200 | \item The hexadecimal representation | ||

201 | will be exactly 8 characters, and any letters | ||

202 | in the hexadecimal representation will be upper-case. | ||

203 | \end{itemize} | ||

204 | |||

205 | \tclcommanddescsynopsisline{crc32}{filename} | ||

206 | \begin{tclcommandinternaldescription} | ||

207 | Returns the CRC-32 of \emph{filename}, treated as an ordered collection of bytes (i.e. | ||

208 | newline characters and file termination characters are not processed---the file is | ||

209 | treated as a binary file). \emph{filename} must be specified in the form accepted by | ||

210 | the Tcl internals (forward slashes only). | ||

211 | \end{tclcommandinternaldescription} | ||

212 | |||

213 | \tclcommanddescsynopsisline{crc32}{-string binarystringval} | ||

214 | \begin{tclcommandinternaldescription} | ||

215 | Returns the CRC-32 of \emph{binarystringval}, treated as an ordered collection of bytes (i.e. | ||

216 | newline characters and string termination characters are not honored---the string is | ||

217 | treated as a binary string).\footnote{For an ASCII string, the \emph{crc32} extension will | ||

218 | behave as expected, and will process all characters up to but not including the zero | ||

219 | terminator. However, the \emph{crc32} extension will also correctly process non-ASCII strings.} | ||

220 | \end{tclcommandinternaldescription} | ||

221 | |||

222 | \tclcommanddescsynopsisline{crc32}{-initialstate} | ||

223 | \tclcommanddescsynopsisline{crc32}{-advancestate state filename} | ||

224 | \tclcommanddescsynopsisline{crc32}{-advancestate -string state filename} | ||

225 | \tclcommanddescsynopsisline{crc32}{-crcfromstate state} | ||

226 | \begin{tclcommandinternaldescription} | ||

227 | The four forms above are designed to allow ``running CRCs'' to be calculated; in which | ||

228 | the CRC is calculated piecemeal. These forms allow the caller to retain the internal | ||

229 | state vector of the CRC calculation algorithm. | ||

230 | |||

231 | The first form, \emph{crc32 -initialstate}, returns an ASCII representation of the | ||

232 | correct initial state vector of the CRC-32 state machine. The client is required | ||

233 | to obtain this initial state before beginning a piecemeal CRC calculation. Although the | ||

234 | returned string is a constant (it will always be the same), representational details | ||

235 | may change in future versions of the \emph{crc32} extension, and so a caller should never | ||

236 | make assumptions about what this invocation will return, as these assumptions may | ||

237 | render a script incompatible with future versions of \emph{crc32}. | ||

238 | |||

239 | The second and third forms, \emph{crc32 -advancestate state filename} | ||

240 | and \emph{crc32 -advancestate -string state filename}, apply a file or a binary string | ||

241 | to \emph{state} to produce a new \emph{state}, which is returned. This new \emph{state} | ||

242 | must be retained by the caller and used in subsequent calls. | ||

243 | |||

244 | The final form, \emph{crc32 -crcfromstate state}, maps from the state vector to the | ||

245 | calculated CRC, and will return a 10-character ASCII string as described above. | ||

246 | \end{tclcommandinternaldescription} | ||

247 | \end{tclcommanddescription} | ||

248 | |||

249 | \begin{tclcommandusagenotes} | ||

250 | (1) The ``piecemeal'' forms are as efficient as the file and string forms---there is no difference | ||

251 | in the internal algorithms. The primary cost of the piecemeal forms is in importing and | ||

252 | exporting the algorithm state vector to/from an ASCII string. | ||

253 | Thus, the piecemeal forms become less efficient when | ||

254 | small files or strings are processed, as there are more exports and imports | ||

255 | of the state vector. When using the piecemeal forms, processing the data in | ||

256 | larger chunks will give better performance. | ||

257 | |||

258 | (2) If the \emph{crc32} command is used to signature files, it is recommended that | ||

259 | the \texttt{file size} command also be used to lower the probability of falsely | ||

260 | assuming two non-identical files are identical yet further. Two files might be | ||

261 | assumed identical if they have the same size and the same CRC-32. | ||

262 | \end{tclcommandusagenotes} | ||

263 | |||

264 | \begin{tclcommandacknowledgements} | ||

265 | The \emph{crc32} command was implemented using ideas and C-language | ||

266 | code from a website (\cite{bibref:w:ellingsoncrc32pages}) | ||

267 | provided by Richard A. Ellingson\index{Ellingson, Richard A.} | ||

268 | \cite{bibref:i:richardaellingson}. I am especially | ||

269 | grateful to Mr. Ellingson for providing these materials publicly | ||

270 | and free of charge. | ||

271 | \end{tclcommandacknowledgements} | ||

272 | |||

273 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

274 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

275 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

276 | \section{Random Number Generation Extensions} | ||

277 | |||

278 | |||

279 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

280 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

281 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

282 | \subsection{rngPwrResRndA} | ||

283 | |||

284 | \index{rngPwrResRndA@\emph{rngPwrResRndA}} | ||

285 | \begin{tclcommandname}{rngPwrResRndA}% | ||

286 | generates pseudo-random integers using the power residue | ||

287 | method with $\alpha = 7^5 = 16,807$ and | ||

288 | $M = 2^{31}-1 = 2,147,483,647$, providing a period of $M - 1 = 2^{31}-2 = 2,147,483,646$ | ||

289 | (\cite{bibref:b:LeonGarciaProb}, pp. 69-71). | ||

290 | \end{tclcommandname} | ||

291 | |||

292 | \begin{tclcommandsynopsis} | ||

293 | \tclcommandsynopsisline{rngPwrResRndA}{} | ||

294 | \tclcommandsynopsisline{rngPwrResRndA}{$N$} | ||

295 | \end{tclcommandsynopsis} | ||

296 | |||

297 | \begin{tclcommanddescription} | ||

298 | The \emph{rngPwrResRndA} command generates pseudo-random positive integers | ||

299 | using the [power residue] recursive formula | ||

300 | |||

301 | \begin{equation} | ||

302 | \label{cxtn0:rngPwrResRndA:eq00} | ||

303 | Z_i = \alpha Z_{i-1} mod M, | ||

304 | \end{equation} | ||

305 | |||

306 | with $(\alpha, M)$ chosen as $(\alpha = 7^5=16,807, M = 2^{31}-1 = 2,147,483,647)$, as | ||

307 | indicated above. With these choices of $(\alpha, M)$, the sequence has a period | ||

308 | of $M - 1 = 2^{31}-2 = 2,147,483,646$ and good statistical properties. | ||

309 | |||

310 | The basis for choosing $(\alpha, M)$ has its origins in number theory, and won't | ||

311 | be discussed here. We refer the reader to \cite{bibref:b:LeonGarciaProb} | ||

312 | and to mathematical papers on the power residue method. | ||

313 | |||

314 | This extension maintains one internal seed value, which is initialized to | ||

315 | 1,578,127,215 at Tcl/Tk startup.\footnote{There is no scientific | ||

316 | reason for the choice of the integer 1,578,127,215 as the | ||

317 | startup value. It was chosen arbitrarily with no rationale.} | ||

318 | It is not possible to set the internal | ||

319 | seed to an arbitrary desired value. The single internal seed value is adequate | ||

320 | for most applications which simply require random numbers. If an | ||

321 | application requires control over the seed or requires multiple seeds, the ability | ||

322 | of this extension to generate the successor of an integer using | ||

323 | (\ref{cxtn0:rngPwrResRndA:eq00}) can be used to achieve this functionality in a | ||

324 | script. | ||

325 | |||

326 | |||

327 | \tclcommanddescsynopsisline{rngPwrResRndA}{} | ||

328 | \begin{tclcommandinternaldescription} | ||

329 | Buffers the current seed for a return value, then advances this seed using | ||

330 | (\ref{cxtn0:rngPwrResRndA:eq00}). Note that the ``old'' value is the value | ||

331 | returned, so that after Tcl/Tk startup the first value | ||

332 | returned will be 1,578,127,215. | ||

333 | \end{tclcommandinternaldescription} | ||

334 | |||

335 | \tclcommanddescsynopsisline{rngPwrResRndA}{$N$} | ||

336 | \begin{tclcommandinternaldescription} | ||

337 | Forms the successor of $N$ using (\ref{cxtn0:rngPwrResRndA:eq00}) and | ||

338 | returns this successor. The single internal seed value is not affected. | ||

339 | \end{tclcommandinternaldescription} | ||

340 | |||

341 | \end{tclcommanddescription} | ||

342 | |||

343 | |||

344 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

345 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

346 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

347 | \section{Arbitrary-Length Integer Extensions} | ||

348 | %Section Tag: SARB0 | ||

349 | \label{cxtn0:sarb0} | ||

350 | |||

351 | Starting with Version 1.05 of \emph{The Iju Tool Set}, \emph{IjuScripter} and | ||

352 | \emph{IjuConsole} contain a limited\footnote{By \emph{limited} we mean that | ||

353 | the library was consolidated and simplified. The GNU MP library has as its | ||

354 | explicit design goal speed over clarity, and uses many advanced algorithms, | ||

355 | such as Karatsuba multiplication and special algorithms for the | ||

356 | greatest common divisor of integers. The library was simplified to regain | ||

357 | clarity at the expense of efficiency before its incorporation into | ||

358 | \emph{The Iju Tool Set}.} version of the | ||

359 | \index{GNU!Multiple Precision Arithmetic Library (GMP)}\emph{GNU Multiple Precision | ||

360 | Library} \cite{bibref:s:gnumultipleprecisionarithmeticlibrary}. | ||

361 | The version of the library incorporated into the tools has been | ||

362 | modified not to process integers larger than about 100,000 decimal digits. | ||

363 | We feel that this limit is sufficiently high for any practical applications, | ||

364 | and also that the computational speed will become unbearable long before the | ||

365 | data size limit is approached. | ||

366 | |||

367 | |||

368 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

369 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

370 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

371 | \subsection{Error And Overflow Behavior Of Arbitrary-Length Integer Extensions} | ||

372 | %Subsection Tag: EAB0 | ||

373 | \label{cxtn0:sarb0:seab0} | ||

374 | |||

375 | The underlying data structure of arbitrary-length integers includes flags | ||

376 | to indicate that an arithmetic error has occured. Essentially, these flags are | ||

377 | ``NAN'', or ``not-a-number'' flags. They indicate that the result is not | ||

378 | an integer. These error flags propagate. Combining a NAN value with a | ||

379 | valid integer through a binary operation always results in a NAN value. Naturally, | ||

380 | the result of a unary operation on a NAN value is also a NAN value. | ||

381 | The nature of NAN propagation is that the first arithmetic operation that | ||

382 | creates an error using valid integers as input will generate an overflow error (one of | ||

383 | the first two flags listed below). | ||

384 | Subsequent operations that use these original errors as input will generate | ||

385 | outputs which are ``taint'' errors (the second set of two flags listed below). | ||

386 | |||

387 | At the lowest level (in the innards of the `C' code), these flags are | ||

388 | bits within an integer. However, for use within Tcl (where all data is string data), these | ||

389 | error flags are assigned symbolic strings to indicate the nature of the error. Note that the | ||

390 | error flags are only approximate---they don't \emph{precisely} indicate the | ||

391 | nature of the error. However, combined with propagation mechanisms, | ||

392 | they are adequate to prevent the interpretation | ||

393 | of invalid data as valid data. Any result that is predicated on an invalid | ||

394 | result will itself be invalid. | ||

395 | |||

396 | The four possible error strings are enumerated below. If any Tcl long integer | ||

397 | function creates an erroneous result, the result will be assigned one of these | ||

398 | four symbolic error strings rather than a string of digits. | ||

399 | |||

400 | \begin{itemize} | ||

401 | \item \index{GMP\_INTS\_EF\_INTOVF\_POS@\texttt{GMP\_INTS\_EF\_INTOVF\_POS}} | ||

402 | \texttt{GMP\_INTS\_EF\_INTOVF\_POS}---the result is too positive (i.e. too | ||

403 | large in a positive direction). This error flag is also produced | ||

404 | by an attempted division by zero, regardless of the sign of the | ||

405 | dividend. | ||

406 | \item \index{GMP\_INTS\_EF\_INTOVF\_NEG@\texttt{GMP\_INTS\_EF\_INTOVF\_NEG}} | ||

407 | \texttt{GMP\_INTS\_EF\_INTOVF\_NEG}---the result is too negative (i.e. too | ||

408 | large in a negative direction). | ||

409 | \item \index{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS@\texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS}} | ||

410 | \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS}---the result has been ``tainted'' | ||

411 | by combination with an integer which has the | ||

412 | \texttt{GMP\_INTS\_EF\_INTOVF\_POS} flag set. | ||

413 | \item \index{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG@\texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG}} | ||

414 | \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG}---the result has been | ||

415 | ``tainted'' by combination with an integer which has the | ||

416 | \texttt{GMP\_INTS\_EF\_INTOVF\_NEG} flag set. | ||

417 | \end{itemize} | ||

418 | |||

419 | Note that the functions which operate on arbitrary length integers will | ||

420 | never produce an exception or a fatal error. Instead, they will mark | ||

421 | results as NAN, and these NAN results will propagate. | ||

422 | This mechanism provides for graceful failures, and also allows complex | ||

423 | calculations to be performed without the necessity of checking for | ||

424 | errors after every calculation step. | ||

425 | |||

426 | Note also that each of the separate arbitrary-length integer extensions described | ||

427 | in this section are a ``sub-extension'' to the \texttt{arbint} extension. It | ||

428 | should also be noted | ||

429 | that many of these extensions perform the same function as a DOS | ||

430 | utility with the same name (see Chapter \cdcmzeroxrefhyphen{}\ref{cdcm0}). | ||

431 | |||

432 | |||

433 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

434 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

435 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

436 | \subsection{The \texttt{arbint iseflag} Extension} | ||

437 | |||

438 | \index{arbint iseflag@\emph{arbint iseflag}} | ||

439 | \index{iseflag@\emph{iseflag}} | ||

440 | \begin{tclcommandname}{arbint iseflag}% | ||

441 | identifies a string as an arbitrary integer error flag (or not) and | ||

442 | returns an integer value categorizing the string. | ||

443 | \end{tclcommandname} | ||

444 | |||

445 | \begin{tclcommandsynopsis} | ||

446 | \tclcommandsynopsisline{arbint iseflag }{stringarg} | ||

447 | \end{tclcommandsynopsis} | ||

448 | |||

449 | \begin{tclcommanddescription} | ||

450 | This extension returns: | ||

451 | \begin{itemize} | ||

452 | \item ``0'' if the string argument supplied is not a recognized | ||

453 | error flag. | ||

454 | \item ``1'' if the string argument supplied is recognized as the\\ | ||

455 | \texttt{GMP\_INTS\_EF\_INTOVF\_POS} | ||

456 | error flag. | ||

457 | \item ``2'' if the string argument supplied is recognized as the\\ | ||

458 | \texttt{GMP\_INTS\_EF\_INTOVF\_NEG} | ||

459 | error flag. | ||

460 | \item ``3'' if the string argument supplied is recognized as the\\ | ||

461 | \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_POS} | ||

462 | error flag. | ||

463 | \item ``4'' if the string argument supplied is recognized as the\\ | ||

464 | \texttt{GMP\_INTS\_EF\_INTOVF\_TAINT\_NEG} | ||

465 | error flag. | ||

466 | \end{itemize} | ||

467 | |||

468 | This extension is most often used to classify the output of an | ||

469 | arbitrary-length integer operation. All valid integers will create | ||

470 | a value of zero if passed to this extension as an argument. | ||

471 | \end{tclcommanddescription} | ||

472 | |||

473 | \begin{tclcommandsampleinvocations} | ||

474 | \begin{scriptsize} | ||

475 | \begin{verbatim} | ||

476 | % arbint iseflag GMP_INTS_EF_INTOVF_NEG | ||

477 | 2 | ||

478 | % arbint iseflag 249,422 | ||

479 | 0 | ||

480 | \end{verbatim} | ||

481 | \end{scriptsize} | ||

482 | \end{tclcommandsampleinvocations} | ||

483 | |||

484 | \begin{tclcommandseealso} | ||

485 | See also Section \ref{cxtn0:sarb0:seab0}. | ||

486 | \end{tclcommandseealso} | ||

487 | |||

488 | |||

489 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

490 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

491 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

492 | \subsection{The \texttt{arbint commanate} Extension} | ||

493 | %Subsection Tag: COM0 | ||

494 | \label{cxtn0:sarb0:scom0} | ||

495 | |||

496 | \index{arbint commanate@\emph{arbint commanate}} | ||

497 | \index{commanate@\emph{commanate}} | ||

498 | \begin{tclcommandname}{arbint commanate}% | ||

499 | inserts comma characters (`,') into a string as necessary to | ||

500 | make it a properly formatted integer with commas. | ||

501 | \end{tclcommandname} | ||

502 | |||

503 | \begin{tclcommandsynopsis} | ||

504 | \tclcommandsynopsisline{arbint commanate}{sint} | ||

505 | \end{tclcommandsynopsis} | ||

506 | |||

507 | \begin{tclcommanddescription} | ||

508 | This extension adds commas to an integer to make it a properly | ||

509 | formatted integer with commas. This extension is normally used to | ||

510 | format a string for more ``human-friendly'' output. The input to this extension | ||

511 | must be either: | ||

512 | |||

513 | \begin{itemize} | ||

514 | \item A integer with no commas, as a string of digits (i.e. | ||

515 | scientific notation is not allowed). The only valid representation | ||

516 | for zero is ``0''. | ||

517 | \item An integer with all commas properly placed (i.e. it is | ||

518 | allowed to ``recommanate'' an integer that is already | ||

519 | ``commanated''). | ||

520 | \item One of the four symbolic NAN strings described in | ||

521 | Section \ref{cxtn0:sarb0:seab0}. (Such a string | ||

522 | will not be modified and will be returned unmodified from | ||

523 | this extension.) | ||

524 | \end{itemize} | ||

525 | |||

526 | Any string that cannot be parsed as described above will result in | ||

527 | an error. | ||

528 | \end{tclcommanddescription} | ||

529 | |||

530 | \begin{tclcommandsampleinvocations} | ||

531 | \begin{scriptsize} | ||

532 | \begin{verbatim} | ||

533 | % arbint intfac 129 | ||

534 | 4974504222477287440390234150412680963965661113713884314596886402265216893219635 | ||

535 | 5119328515747917449637889876686464600208839390308261862352651828829226610077151 | ||

536 | 044469167497022952331930501120000000000000000000000000000000 | ||

537 | % arbint commanate [arbint intfac 129] | ||

538 | 49,745,042,224,772,874,403,902,341,504,126,809,639,656,611,137,138,843,145,968, | ||

539 | 864,022,652,168,932,196,355,119,328,515,747,917,449,637,889,876,686,464,600,208 | ||

540 | ,839,390,308,261,862,352,651,828,829,226,610,077,151,044,469,167,497,022,952,33 | ||

541 | 1,930,501,120,000,000,000,000,000,000,000,000,000,000 | ||

542 | % arbint commanate GMP_INTS_EF_INTOVF_POS | ||

543 | GMP_INTS_EF_INTOVF_POS | ||

544 | \end{verbatim} | ||

545 | \end{scriptsize} | ||

546 | \end{tclcommandsampleinvocations} | ||

547 | |||

548 | |||

549 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

550 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

551 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

552 | \subsection{The \texttt{arbint decommanate} Extension} | ||

553 | %Subsection Tag: dco0 | ||

554 | \label{cxtn0:sarb0:sdco0} | ||

555 | |||

556 | \index{arbint decommanate@\emph{arbint decommanate}} | ||

557 | \index{decommanate@\emph{decommanate}} | ||

558 | \begin{tclcommandname}{arbint decommanate}% | ||

559 | removes comma characters (`,') from a properly | ||

560 | formatted integer. | ||

561 | \end{tclcommandname} | ||

562 | |||

563 | \begin{tclcommandsynopsis} | ||

564 | \tclcommandsynopsisline{arbint decommanate}{sint} | ||

565 | \end{tclcommandsynopsis} | ||

566 | |||

567 | \begin{tclcommanddescription} | ||

568 | This extension removes commas from a properly formatted integer. | ||

569 | The input to this extension | ||

570 | must be either: | ||

571 | |||

572 | \begin{itemize} | ||

573 | \item A integer with no commas, as a string of digits (i.e. | ||

574 | scientific notation is not allowed). The only valid representation | ||

575 | for zero is ``0''. (Note that it is allowed to ``decommanate'' | ||

576 | an integer that contains no commas.) | ||

577 | \item An integer with all commas properly placed. | ||

578 | \item One of the four symbolic NAN strings described in | ||

579 | Section \ref{cxtn0:sarb0:seab0}. (Such a string | ||

580 | will not be modified and will be returned unmodified from | ||

581 | this extension.) | ||

582 | \end{itemize} | ||

583 | |||

584 | Any string that cannot be parsed as described above will result in | ||

585 | an error. | ||

586 | \end{tclcommanddescription} | ||

587 | |||

588 | \begin{tclcommandsampleinvocations} | ||

589 | \begin{scriptsize} | ||

590 | \begin{verbatim} | ||

591 | % arbint intfac 129 | ||

592 | 4974504222477287440390234150412680963965661113713884314596886402265216893219635 | ||

593 | 5119328515747917449637889876686464600208839390308261862352651828829226610077151 | ||

594 | 044469167497022952331930501120000000000000000000000000000000 | ||

595 | % arbint commanate [arbint intfac 129] | ||

596 | 49,745,042,224,772,874,403,902,341,504,126,809,639,656,611,137,138,843,145,968, | ||

597 | 864,022,652,168,932,196,355,119,328,515,747,917,449,637,889,876,686,464,600,208 | ||

598 | ,839,390,308,261,862,352,651,828,829,226,610,077,151,044,469,167,497,022,952,33 | ||

599 | 1,930,501,120,000,000,000,000,000,000,000,000,000,000 | ||

600 | % set number [arbint commanate [arbint intfac 129]] | ||

601 | 49,745,042,224,772,874,403,902,341,504,126,809,639,656,611,137,138,843,145,968, | ||

602 | 864,022,652,168,932,196,355,119,328,515,747,917,449,637,889,876,686,464,600,208 | ||

603 | ,839,390,308,261,862,352,651,828,829,226,610,077,151,044,469,167,497,022,952,33 | ||

604 | 1,930,501,120,000,000,000,000,000,000,000,000,000,000 | ||

605 | % arbint decommanate $number | ||

606 | 4974504222477287440390234150412680963965661113713884314596886402265216893219635 | ||

607 | 5119328515747917449637889876686464600208839390308261862352651828829226610077151 | ||

608 | 044469167497022952331930501120000000000000000000000000000000 | ||

609 | % arbint decommanate GMP_INTS_EF_INTOVF_POS | ||

610 | GMP_INTS_EF_INTOVF_POS | ||

611 | \end{verbatim} | ||

612 | \end{scriptsize} | ||

613 | \end{tclcommandsampleinvocations} | ||

614 | |||

615 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

616 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

617 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

618 | \subsection{The \texttt{arbint intcmp} Extension} | ||

619 | %Subsection Tag: add0 | ||

620 | \label{cxtn0:sarb0:scmp0} | ||

621 | |||

622 | \index{arbint intcmp@\emph{arbint intcmp}} | ||

623 | \index{intcmp@\emph{intcmp}} | ||

624 | \begin{tclcommandname}{arbint intcmp}% | ||

625 | compares two arbitrary integers and returns a result indicating their relative | ||

626 | ordering. | ||

627 | \end{tclcommandname} | ||

628 | |||

629 | \begin{tclcommandsynopsis} | ||

630 | \tclcommandsynopsisline{arbint intcmp}{sint\_a sint\_b} | ||

631 | \end{tclcommandsynopsis} | ||

632 | |||

633 | \begin{tclcommanddescription} | ||

634 | This extension compares \emph{sint\_a} and \emph{sint\_b} and | ||

635 | returns $\{-1, 0, 1\}$ if | ||

636 | \emph{sint\_a} $\{ <, =, > \}$ \emph{sint\_b}. This extension | ||

637 | is used to compare arbitrarily large integers in Tcl scripts. | ||

638 | Because NAN tags (see Section \ref{cxtn0:sarb0:seab0}) | ||

639 | cannot be logically compared, | ||

640 | this extension will signal an error if either parameter is | ||

641 | a NAN tag. | ||

642 | \end{tclcommanddescription} | ||

643 | |||

644 | \begin{tclcommandsampleinvocations} | ||

645 | \begin{scriptsize} | ||

646 | \begin{verbatim} | ||

647 | % arbint intcmp -5 -3 | ||

648 | -1 | ||

649 | % arbint intcmp -5 -5 | ||

650 | 0 | ||

651 | % arbint intcmp 7 5 | ||

652 | 1 | ||

653 | \end{verbatim} | ||

654 | \end{scriptsize} | ||

655 | \end{tclcommandsampleinvocations} | ||

656 | |||

657 | \begin{tclcommandseealso} | ||

658 | See also the \emph{arbint rncmp} Tcl extension, | ||

659 | Section \ref{cxtn0:srne0:srcm0}, which performs a similar | ||

660 | function for arbitrary rational numbers. | ||

661 | \end{tclcommandseealso} | ||

662 | |||

663 | |||

664 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

665 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

666 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

667 | \subsection{The \texttt{arbint intadd} Extension} | ||

668 | %Subsection Tag: add0 | ||

669 | \label{cxtn0:sarb0:sadd0} | ||

670 | |||

671 | \index{arbint intadd@\emph{arbint intadd}} | ||

672 | \index{intadd@\emph{intadd}} | ||

673 | \begin{tclcommandname}{arbint intadd}% | ||

674 | calculates and returns as a string the sum of two integers. | ||

675 | \end{tclcommandname} | ||

676 | |||

677 | \begin{tclcommandsynopsis} | ||

678 | \tclcommandsynopsisline{arbint intadd}{sint sint} | ||

679 | \end{tclcommandsynopsis} | ||

680 | |||

681 | \begin{tclcommanddescription} | ||

682 | This extension returns the sum of two integer | ||

683 | arguments, or one of the NAN tags described in | ||

684 | Section \ref{cxtn0:sarb0:seab0} if an overflow occurs. | ||

685 | \end{tclcommanddescription} | ||

686 | |||

687 | \begin{tclcommandsampleinvocations} | ||

688 | \begin{scriptsize} | ||

689 | \begin{verbatim} | ||

690 | % arbint intadd 1e20 21643215482123164 | ||

691 | 100021643215482123164 | ||

692 | \end{verbatim} | ||

693 | \end{scriptsize} | ||

694 | \end{tclcommandsampleinvocations} | ||

695 | |||

696 | \begin{tclcommandseealso} | ||

697 | See also the \emph{intadd} DOS command-line utility, | ||

698 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sadd0}. | ||

699 | \end{tclcommandseealso} | ||

700 | |||

701 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

702 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

703 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

704 | \subsection{The \texttt{arbint intsub} Extension} | ||

705 | %Subsection Tag: mod0 | ||

706 | \label{cxtn0:sarb0:ssub0} | ||

707 | |||

708 | \index{arbint intsub@\emph{arbint intsub}} | ||

709 | \index{intsub@\emph{intsub}} | ||

710 | \begin{tclcommandname}{arbint intsub}% | ||

711 | calculates and returns as a string the difference of two integers. | ||

712 | \end{tclcommandname} | ||

713 | |||

714 | \begin{tclcommandsynopsis} | ||

715 | \tclcommandsynopsisline{arbint intsub}{sint sint} | ||

716 | \end{tclcommandsynopsis} | ||

717 | |||

718 | \begin{tclcommanddescription} | ||

719 | This extension returns the difference of two integer | ||

720 | arguments, or one of the NAN tags described in | ||

721 | Section \ref{cxtn0:sarb0:seab0} if an overflow occurs. | ||

722 | \end{tclcommanddescription} | ||

723 | |||

724 | \begin{tclcommandsampleinvocations} | ||

725 | \begin{scriptsize} | ||

726 | \begin{verbatim} | ||

727 | % arbint intsub 123846129436219 1e25 | ||

728 | -9999999999876153870563781 | ||

729 | \end{verbatim} | ||

730 | \end{scriptsize} | ||

731 | \end{tclcommandsampleinvocations} | ||

732 | |||

733 | \begin{tclcommandseealso} | ||

734 | See also the \emph{intsub} DOS command-line utility, | ||

735 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:ssub0}. | ||

736 | \end{tclcommandseealso} | ||

737 | |||

738 | |||

739 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

740 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

741 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

742 | \subsection{The \texttt{arbint intmul} Extension} | ||

743 | %Subsection Tag: mul0 | ||

744 | \label{cxtn0:sarb0:smul0} | ||

745 | |||

746 | \index{arbint intmul@\emph{arbint intmul}} | ||

747 | \index{intmul@\emph{intmul}} | ||

748 | \begin{tclcommandname}{arbint intmul}% | ||

749 | calculates and returns as a string the product of two integers. | ||

750 | \end{tclcommandname} | ||

751 | |||

752 | \begin{tclcommandsynopsis} | ||

753 | \tclcommandsynopsisline{arbint intmul}{sint sint} | ||

754 | \end{tclcommandsynopsis} | ||

755 | |||

756 | \begin{tclcommanddescription} | ||

757 | This extension returns the product of two integer arguments. | ||

758 | The result of this | ||

759 | extension will always be either a NAN tag | ||

760 | (see Section \ref{cxtn0:sarb0:seab0}) | ||

761 | or an integer. | ||

762 | \end{tclcommanddescription} | ||

763 | |||

764 | \begin{tclcommandsampleinvocations} | ||

765 | \begin{scriptsize} | ||

766 | \begin{verbatim} | ||

767 | % arbint intmul -329749813264962165493214963541976325 4.36463214521843123e38 | ||

768 | -143923663485602892702423181098245942606484617030062975000000000000000000000 | ||

769 | \end{verbatim} | ||

770 | \end{scriptsize} | ||

771 | \end{tclcommandsampleinvocations} | ||

772 | |||

773 | \begin{tclcommandseealso} | ||

774 | See also the \emph{intmul} DOS command-line utility, | ||

775 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:smul0}. | ||

776 | \end{tclcommandseealso} | ||

777 | |||

778 | |||

779 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

780 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

781 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

782 | \subsection{The \texttt{arbint intdiv} Extension} | ||

783 | %Subsection Tag: div0 | ||

784 | \label{cxtn0:sarb0:sdiv0} | ||

785 | |||

786 | \index{arbint intdiv@\emph{arbint intdiv}} | ||

787 | \index{intdiv@\emph{intdiv}} | ||

788 | \begin{tclcommandname}{arbint intdiv}% | ||

789 | calculates and returns as a string the quotient of two integers. | ||

790 | \end{tclcommandname} | ||

791 | |||

792 | \begin{tclcommandsynopsis} | ||

793 | \tclcommandsynopsisline{arbint intdiv}{sint\_dividend sint\_divisor} | ||

794 | \end{tclcommandsynopsis} | ||

795 | |||

796 | \begin{tclcommanddescription} | ||

797 | This extension returns the quotient of two integer arguments. | ||

798 | The first integer argument is interpreted to be the dividend, | ||

799 | and the second the divisor. The quotient is without remainder, | ||

800 | i.e. what is actually returned is | ||

801 | |||

802 | \begin{equation} | ||

803 | sgn(dividend \cdot divisor) | ||

804 | \left\lfloor{\frac{|dividend|}{|divisor|}}\right\rfloor , | ||

805 | \end{equation} | ||

806 | |||

807 | or one of the NAN tags described in | ||

808 | Section \ref{cxtn0:sarb0:seab0} | ||

809 | if division by zero is attempted. Note that division | ||

810 | by zero is not an error (as far as a Tcl script is concerned): | ||

811 | the only outcome is that the result will be assigned a symbolic | ||

812 | NAN tag rather than a string of digits representing an integer. | ||

813 | \end{tclcommanddescription} | ||

814 | |||

815 | \begin{tclcommandsampleinvocations} | ||

816 | \begin{scriptsize} | ||

817 | \begin{verbatim} | ||

818 | % arbint intdiv 2364832165653218648321543215848236458124 2854871354812543821 | ||

819 | 828349817467869034672 | ||

820 | % arbint intdiv 2364832165653218648321543215848236458124 0 | ||

821 | GMP_INTS_EF_INTOVF_POS | ||

822 | \end{verbatim} | ||

823 | \end{scriptsize} | ||

824 | \end{tclcommandsampleinvocations} | ||

825 | |||

826 | \begin{tclcommandseealso} | ||

827 | See also the \emph{intdiv} DOS command-line utility, | ||

828 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sdiv0}. | ||

829 | \end{tclcommandseealso} | ||

830 | |||

831 | |||

832 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

833 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

834 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

835 | \subsection{The \texttt{arbint intmod} Extension} | ||

836 | %Subsection Tag: mod0 | ||

837 | \label{cxtn0:sarb0:smod0} | ||

838 | |||

839 | \index{arbint intmod@\emph{arbint intmod}} | ||

840 | \index{intmod@\emph{intmod}} | ||

841 | \begin{tclcommandname}{arbint intmod}% | ||

842 | calculates and returns as a string the modulo of two integers. | ||

843 | \end{tclcommandname} | ||

844 | |||

845 | \begin{tclcommandsynopsis} | ||

846 | \tclcommandsynopsisline{arbint intmod}{sint\_dividend sint\_divisor} | ||

847 | \end{tclcommandsynopsis} | ||

848 | |||

849 | \begin{tclcommanddescription} | ||

850 | This extension returns the remainder resulting from the | ||

851 | division of two integer arguments. | ||

852 | The first integer argument is interpreted to be the dividend, | ||

853 | and the second the divisor. The sign of the remainder is always | ||

854 | chosen so that the following relationship holds: | ||

855 | |||

856 | \begin{equation} | ||

857 | dividend \; div \; divisor + \frac{dividend \; mod \; divisor}{divisor} | ||

858 | = \frac{dividend}{divisor}, | ||

859 | \end{equation} | ||

860 | |||

861 | where the \emph{div} operator is as explained in Section | ||

862 | \ref{cxtn0:sarb0:sdiv0} for the \emph{arbint intdiv} extension. | ||

863 | If division by zero is attempted, this extension | ||

864 | returns one of the NAN tags described in | ||

865 | Section \ref{cxtn0:sarb0:seab0}. Note that division | ||

866 | by zero is not an error (as far as a Tcl script is concerned): | ||

867 | the only outcome is that the result will be assigned a symbolic | ||

868 | NAN tag rather than a string of digits representing an integer. | ||

869 | \end{tclcommanddescription} | ||

870 | |||

871 | \begin{tclcommandsampleinvocations} | ||

872 | \begin{scriptsize} | ||

873 | \begin{verbatim} | ||

874 | % arbint intmod 264321654632432421 2175438321654 | ||

875 | 1547674828113 | ||

876 | % arbint intmod 264321654632432421 0 | ||

877 | GMP_INTS_EF_INTOVF_POS | ||

878 | \end{verbatim} | ||

879 | \end{scriptsize} | ||

880 | \end{tclcommandsampleinvocations} | ||

881 | |||

882 | \begin{tclcommandseealso} | ||

883 | See also the \emph{intmod} DOS command-line utility, | ||

884 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:smod0}. | ||

885 | \end{tclcommandseealso} | ||

886 | |||

887 | |||

888 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

889 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

890 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

891 | \subsection{The \texttt{arbint intexp} Extension} | ||

892 | %Subsection Tag: exp0 | ||

893 | \label{cxtn0:sarb0:sixp0} | ||

894 | |||

895 | \index{arbint intexp@\emph{arbint intexp}} | ||

896 | \index{intexp@\emph{intexp}} | ||

897 | \begin{tclcommandname}{arbint intexp}% | ||

898 | computes and returns as a string one integer | ||

899 | exponentiated to the power of another, | ||

900 | $base^{exponent}$. | ||

901 | |||

902 | \end{tclcommandname} | ||

903 | |||

904 | \begin{tclcommandsynopsis} | ||

905 | \tclcommandsynopsisline{arbint intexp}{sint\_base uint32\_exponent} | ||

906 | \end{tclcommandsynopsis} | ||

907 | |||

908 | \begin{tclcommanddescription} | ||

909 | This extension exponentiates an integer to a non-negative | ||

910 | power. For | ||

911 | simplicity and convenience, $0^0$ will return 1, although | ||

912 | this is inconsistent with the mathematical definition. | ||

913 | All other exponentiations are as expected. | ||

914 | |||

915 | The method used to exponentiate is simple squaring and multiplying | ||

916 | based on the bit pattern of the exponent, as discussed | ||

917 | in \cite{bibref:b:knuthclassic2ndedvol2}, pp. 461-462. | ||

918 | \end{tclcommanddescription} | ||

919 | |||

920 | \begin{tclcommandsampleinvocations} | ||

921 | \begin{scriptsize} | ||

922 | \begin{verbatim} | ||

923 | % arbint intexp 47 69 | ||

924 | 2370021018513446695324337468306899241173950476009917473665218657220346081293500 | ||

925 | 4143894985892600403244809901800125167 | ||

926 | % arbint intexp 1 0 | ||

927 | 1 | ||

928 | % arbint intexp 0 0 | ||

929 | 1 | ||

930 | % arbint intexp 0 1 | ||

931 | 0 | ||

932 | % arbint intexp 0 19237498 | ||

933 | 0 | ||

934 | % arbint intexp -47 69 | ||

935 | -237002101851344669532433746830689924117395047600991747366521865722034608129350 | ||

936 | 04143894985892600403244809901800125167 | ||

937 | % arbint intexp -47 -69 | ||

938 | arbint intexp: "-69" is not a recognized unsigned 32-bit integer. | ||

939 | % arbint intexp 193461926436214 99999999 | ||

940 | GMP_INTS_EF_INTOVF_TAINT_POS | ||

941 | \end{verbatim} | ||

942 | \end{scriptsize} | ||

943 | \end{tclcommandsampleinvocations} | ||

944 | |||

945 | \begin{tclcommandseealso} | ||

946 | See also the \emph{intexp} DOS command-line utility, | ||

947 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sixp0}. | ||

948 | \end{tclcommandseealso} | ||

949 | |||

950 | |||

951 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

952 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

953 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

954 | \subsection{The \texttt{arbint intfac} Extension} | ||

955 | %Subsection Tag: fac0 | ||

956 | \label{cxtn0:sarb0:sfac0} | ||

957 | |||

958 | \index{arbint intfac@\emph{arbint intfac}} | ||

959 | \index{intfac@\emph{intfac}} | ||

960 | \begin{tclcommandname}{arbint intfac}% | ||

961 | computes and returns as a string the factorial ($!$) of | ||

962 | the integer argument supplied. | ||

963 | \end{tclcommandname} | ||

964 | |||

965 | \begin{tclcommandsynopsis} | ||

966 | \tclcommandsynopsisline{arbint intfac}{uint32} | ||

967 | \end{tclcommandsynopsis} | ||

968 | |||

969 | \begin{tclcommanddescription} | ||

970 | This extension returns the factorial of an integer argument. | ||

971 | Any of the symbolic NAN strings described in | ||

972 | Section \ref{cxtn0:sarb0:seab0} will cause a return | ||

973 | value of an appropriate symbolic NAN string. | ||

974 | Strings that cannot be parsed as integers or | ||

975 | NAN strings, strings | ||

976 | that represent negative integers, and strings that represent | ||

977 | non-negative integers that will not fit in 32 bits will generate | ||

978 | an error. | ||

979 | |||

980 | As of this writing, 200! requires about 1 second to compute on a | ||

981 | 600MHz PC. Although this function will calculate factorials of any size | ||

982 | up to 100,000 digits, it is not recommended to use this function above | ||

983 | about 200! as the increase in computation time appears to be exponential | ||

984 | with respect to the argument. This may improve in the future as algorithmic | ||

985 | enhancements are made. | ||

986 | \end{tclcommanddescription} | ||

987 | |||

988 | \begin{tclcommandsampleinvocations} | ||

989 | \begin{scriptsize} | ||

990 | \begin{verbatim} | ||

991 | % arbint intfac 129 | ||

992 | 4974504222477287440390234150412680963965661113713884314596886402265216893219635 | ||

993 | 5119328515747917449637889876686464600208839390308261862352651828829226610077151 | ||

994 | 044469167497022952331930501120000000000000000000000000000000 | ||

995 | \end{verbatim} | ||

996 | \end{scriptsize} | ||

997 | \end{tclcommandsampleinvocations} | ||

998 | |||

999 | \begin{tclcommandseealso} | ||

1000 | See also the \emph{intfac} DOS command-line utility, | ||

1001 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sifc0}. | ||

1002 | \end{tclcommandseealso} | ||

1003 | |||

1004 | |||

1005 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1006 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1007 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1008 | \subsection{The \texttt{arbint intgcd} Extension} | ||

1009 | %Subsection Tag: gcd0 | ||

1010 | \label{cxtn0:sarb0:sgcd0} | ||

1011 | |||

1012 | \index{arbint intgcd@\emph{arbint intgcd}} | ||

1013 | \index{intgcd@\emph{intgcd}} | ||

1014 | \begin{tclcommandname}{arbint intgcd}% | ||

1015 | calculates and returns as a string the g.c.d. | ||

1016 | (greatest common divisor) of two integers. | ||

1017 | \end{tclcommandname} | ||

1018 | |||

1019 | \begin{tclcommandsynopsis} | ||

1020 | \tclcommandsynopsisline{arbint intgcd}{sint sint} | ||

1021 | \end{tclcommandsynopsis} | ||

1022 | |||

1023 | \begin{tclcommanddescription} | ||

1024 | This extension returns the g.c.d. of two integer arguments. | ||

1025 | If either argument is 0, the result will be 1. If either | ||

1026 | argument is negative, the absolute value of the argument | ||

1027 | will be used in its place. The result of this | ||

1028 | extension will always be either a NAN tag | ||

1029 | (see Section \ref{cxtn0:sarb0:seab0}) | ||

1030 | or an integer greater than or equal to 1. | ||

1031 | |||

1032 | The algorithm employed is the | ||

1033 | \emph{Modern Euclidian Algorithm} as | ||

1034 | described in \cite{bibref:b:knuthclassic2ndedvol2}, p. 337. | ||

1035 | Although faster algorithms for computer | ||

1036 | implementation do exist, this is the simplest | ||

1037 | and most direct algorithm. | ||

1038 | \end{tclcommanddescription} | ||

1039 | |||

1040 | \begin{tclcommandsampleinvocations} | ||

1041 | \begin{scriptsize} | ||

1042 | \begin{verbatim} | ||

1043 | % arbint intgcd 263130836933693530167218012160000000 503580 | ||

1044 | 4620 | ||

1045 | \end{verbatim} | ||

1046 | \end{scriptsize} | ||

1047 | \end{tclcommandsampleinvocations} | ||

1048 | |||

1049 | \begin{tclcommandseealso} | ||

1050 | See also the \emph{intgcd} DOS command-line utility, | ||

1051 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:sgcd0}. | ||

1052 | \end{tclcommandseealso} | ||

1053 | |||

1054 | |||

1055 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1056 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1057 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1058 | \subsection{The \texttt{arbint intlcm} Extension} | ||

1059 | %Subsection Tag: lcm0 | ||

1060 | \label{cxtn0:sarb0:slcm0} | ||

1061 | |||

1062 | \index{arbint intgcd@\emph{arbint intlcm}} | ||

1063 | \index{intlcm@\emph{intlcm}} | ||

1064 | \begin{tclcommandname}{arbint intlcm}% | ||

1065 | calculates and returns as a string the l.c.m. | ||

1066 | (least common multiple) of two integers. | ||

1067 | \end{tclcommandname} | ||

1068 | |||

1069 | \begin{tclcommandsynopsis} | ||

1070 | \tclcommandsynopsisline{arbint intlcm}{sint sint} | ||

1071 | \end{tclcommandsynopsis} | ||

1072 | |||

1073 | \begin{tclcommanddescription} | ||

1074 | This extension returns the l.c.m. of two integer arguments. | ||

1075 | If either argument is 0, the argument will be treated as if it | ||

1076 | were 1. If either | ||

1077 | argument is negative, the absolute value of the argument | ||

1078 | will be used in its place. The result of this | ||

1079 | extension will always be either a NAN tag | ||

1080 | (see Section \ref{cxtn0:sarb0:seab0}) | ||

1081 | or an integer greater than or equal to 1. | ||

1082 | |||

1083 | The algorithm employed is to calculate | ||

1084 | the g.c.d. of the arguments using the | ||

1085 | \emph{Modern Euclidian Algorithm} as | ||

1086 | described in \cite{bibref:b:knuthclassic2ndedvol2}, p. 337; | ||

1087 | then to divide the product of the arguments by their | ||

1088 | g.c.d., as implied by \cite{bibref:b:knuthclassic2ndedvol2}, | ||

1089 | p. 334, Equation 10. Both sides of this equation can be | ||

1090 | divided by $\gcd(u,v)$ to yield | ||

1091 | |||

1092 | \begin{equation} | ||

1093 | lcm(u,v) = \frac{uv}{\gcd(u,v)}, | ||

1094 | \end{equation} | ||

1095 | |||

1096 | and this is the relationship used to calculated the l.c.m. | ||

1097 | \end{tclcommanddescription} | ||

1098 | |||

1099 | \begin{tclcommandsampleinvocations} | ||

1100 | \begin{scriptsize} | ||

1101 | \begin{verbatim} | ||

1102 | % arbint intlcm 64 100 | ||

1103 | 1600 | ||

1104 | \end{verbatim} | ||

1105 | \end{scriptsize} | ||

1106 | \end{tclcommandsampleinvocations} | ||

1107 | |||

1108 | \begin{tclcommandseealso} | ||

1109 | See also the \emph{intlcm} DOS command-line utility, | ||

1110 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:sali0:slcm0}. | ||

1111 | \end{tclcommandseealso} | ||

1112 | |||

1113 | |||

1114 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1115 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1116 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1117 | \section{Rational Number Extensions} | ||

1118 | %Section Tag: RNE0 | ||

1119 | |||

1120 | This section describes extensions that implement | ||

1121 | rational number arithmetic. | ||

1122 | |||

1123 | In most cases, the rational number extensions described in | ||

1124 | this section are liberal in the representations of rational numbers | ||

1125 | they accept, but always produce results as integer components | ||

1126 | separated by the forward slash character. This means that the | ||

1127 | rational number extensions described in this section can exchange data | ||

1128 | freely---the output of any of the extensions is suitable as input | ||

1129 | for another extension. | ||

1130 | |||

1131 | |||

1132 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1133 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1134 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1135 | \subsection{The \texttt{arbint rnred} Extension} | ||

1136 | %Subsection Tag: RNR0 | ||

1137 | \label{cxtn0:srne0:srnr0} | ||

1138 | |||

1139 | \index{arbint rnred@\emph{arbint rnred}} | ||

1140 | \index{rnred@\emph{rnred}} | ||

1141 | \begin{tclcommandname}{arbint rnred}% | ||

1142 | reduces a rational number to lowest terms and normalizes it. | ||

1143 | \end{tclcommandname} | ||

1144 | |||

1145 | \begin{tclcommandsynopsis} | ||

1146 | \tclcommandsynopsisline{arbint rnred}{srn} | ||

1147 | \end{tclcommandsynopsis} | ||

1148 | |||

1149 | \begin{tclcommanddescription} | ||

1150 | The \emph{arbint rnred} extension reduces a rational number to its lowest terms | ||

1151 | and normalizes it. By \emph{reducing} a rational number and | ||

1152 | normalizing it, we mean the application of the following rules. | ||

1153 | |||

1154 | \begin{enumerate} | ||

1155 | \item Any number with a numerator of zero is given the | ||

1156 | representation 0/1, i.e. 0/1 is the canonical | ||

1157 | representation of zero. | ||

1158 | \item Any number with a denominator of zero is given | ||

1159 | the representation 1/0, i.e. 1/0 is the canonical | ||

1160 | representation of ``division by zero''. | ||

1161 | \item Rational numbers which are effectively positive | ||

1162 | are normalized to have a positve numerator and positive | ||

1163 | denominator. | ||

1164 | \item Rational numbers which are effectively negative are | ||

1165 | normalized to have a negative numerator and positive | ||

1166 | denominator. | ||

1167 | \item Any common factors are removed from the numerator and | ||

1168 | denominator, i.e. the numerator and denominator are | ||

1169 | made coprime. | ||

1170 | \end{enumerate} | ||

1171 | |||

1172 | Note that one behavior above may be unexpected---the | ||

1173 | \emph{arbint rnred} extension \emph{will} accept a rational number | ||

1174 | specified with a denominator of zero, and will normalize it to | ||

1175 | 1/0. | ||

1176 | \end{tclcommanddescription} | ||

1177 | |||

1178 | \begin{tclcommandsampleinvocations} | ||

1179 | \begin{scriptsize} | ||

1180 | \begin{verbatim} | ||

1181 | % arbint rnred 422.414 | ||

1182 | 211207/500 | ||

1183 | \end{verbatim} | ||

1184 | \end{scriptsize} | ||

1185 | \end{tclcommandsampleinvocations} | ||

1186 | |||

1187 | \begin{tclcommandseealso} | ||

1188 | See also the \emph{rnred} DOS command-line utility, | ||

1189 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srnr0}. | ||

1190 | \end{tclcommandseealso} | ||

1191 | |||

1192 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1193 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1194 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1195 | \subsection{The \texttt{arbint rnadd} Extension} | ||

1196 | %Subsection Tag: RAD0 | ||

1197 | \label{cxtn0:srne0:srad0} | ||

1198 | |||

1199 | \index{arbint rnadd@\emph{arbint rnadd}} | ||

1200 | \index{rnadd@\emph{rnadd}} | ||

1201 | \begin{tclcommandname}{arbint rnadd}% | ||

1202 | adds two rational numbers to produce a normalized rational result. | ||

1203 | \end{tclcommandname} | ||

1204 | |||

1205 | \begin{tclcommandsynopsis} | ||

1206 | \tclcommandsynopsisline{arbint rnadd}{srn srn} | ||

1207 | \end{tclcommandsynopsis} | ||

1208 | |||

1209 | \begin{tclcommanddescription} | ||

1210 | The \emph{arbint rnadd} extension adds two rational numbers to produce a | ||

1211 | normalized rational result. | ||

1212 | |||

1213 | If either of the two rational input arguments has a denominator of zero, | ||

1214 | the string ``NAN'' will be returned. | ||

1215 | \end{tclcommanddescription} | ||

1216 | |||

1217 | \begin{tclcommandsampleinvocations} | ||

1218 | \begin{scriptsize} | ||

1219 | \begin{verbatim} | ||

1220 | % arbint rnadd 3.1415 64/259 | ||

1221 | 1755297/518000 | ||

1222 | \end{verbatim} | ||

1223 | \end{scriptsize} | ||

1224 | \end{tclcommandsampleinvocations} | ||

1225 | |||

1226 | \begin{tclcommandseealso} | ||

1227 | See also the \emph{rnadd} DOS command-line utility, | ||

1228 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srna0}. | ||

1229 | \end{tclcommandseealso} | ||

1230 | |||

1231 | |||

1232 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1233 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1234 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1235 | \subsection{The \texttt{arbint rnsub} Extension} | ||

1236 | %Subsection Tag: RSB0 | ||

1237 | \label{cxtn0:srne0:srsb0} | ||

1238 | |||

1239 | \index{arbint rnsub@\emph{arbint rnsub}} | ||

1240 | \index{rnsub@\emph{rnsub}} | ||

1241 | \begin{tclcommandname}{arbint rnsub}% | ||

1242 | subtracts two rational numbers to produce a normalized rational result. | ||

1243 | \end{tclcommandname} | ||

1244 | |||

1245 | \begin{tclcommandsynopsis} | ||

1246 | \tclcommandsynopsisline{arbint rnsub}{srn\_arg1 srn\_arg2} | ||

1247 | \end{tclcommandsynopsis} | ||

1248 | |||

1249 | \begin{tclcommanddescription} | ||

1250 | The \emph{arbint rnsub} extension subtracts two rational numbers to produce a | ||

1251 | normalized rational result. The second argument is subtracted from the first, i.e. | ||

1252 | the result $arg_2 - arg_1$ is formed. | ||

1253 | |||

1254 | If either of the two rational input arguments has a denominator of zero, | ||

1255 | the string ``NAN'' will be returned. | ||

1256 | \end{tclcommanddescription} | ||

1257 | |||

1258 | \begin{tclcommandsampleinvocations} | ||

1259 | \begin{scriptsize} | ||

1260 | \begin{verbatim} | ||

1261 | % arbint rnsub 3.129 122/451 | ||

1262 | 1289179/451000 | ||

1263 | \end{verbatim} | ||

1264 | \end{scriptsize} | ||

1265 | \end{tclcommandsampleinvocations} | ||

1266 | |||

1267 | \begin{tclcommandseealso} | ||

1268 | See also the \emph{rnsub} DOS command-line utility, | ||

1269 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srsb0}. | ||

1270 | \end{tclcommandseealso} | ||

1271 | |||

1272 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1273 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1274 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1275 | \subsection{The \texttt{arbint rnmul} Extension} | ||

1276 | %Subsection Tag: RMU0 | ||

1277 | \label{cxtn0:srne0:srmu0} | ||

1278 | |||

1279 | \index{arbint rnmul@\emph{arbint rnmul}} | ||

1280 | \index{rnmul@\emph{rnmul}} | ||

1281 | \begin{tclcommandname}{arbint rnmul}% | ||

1282 | multiplies two rational numbers to produce a normalized rational result. | ||

1283 | \end{tclcommandname} | ||

1284 | |||

1285 | \begin{tclcommandsynopsis} | ||

1286 | \tclcommandsynopsisline{arbint rnmul}{srn srn} | ||

1287 | \end{tclcommandsynopsis} | ||

1288 | |||

1289 | \begin{tclcommanddescription} | ||

1290 | The \emph{arbint rnmul} extension multiplies two rational numbers to produce a | ||

1291 | normalized rational result. | ||

1292 | |||

1293 | If either of the two rational input arguments has a denominator of zero, | ||

1294 | the string ``NAN'' will be returned. | ||

1295 | \end{tclcommanddescription} | ||

1296 | |||

1297 | \begin{tclcommandsampleinvocations} | ||

1298 | \begin{scriptsize} | ||

1299 | \begin{verbatim} | ||

1300 | % arbint rnmul 3.14 32/491 | ||

1301 | 2512/12275 | ||

1302 | \end{verbatim} | ||

1303 | \end{scriptsize} | ||

1304 | \end{tclcommandsampleinvocations} | ||

1305 | |||

1306 | \begin{tclcommandseealso} | ||

1307 | See also the \emph{rnmul} DOS command-line utility, | ||

1308 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srmu0}. | ||

1309 | \end{tclcommandseealso} | ||

1310 | |||

1311 | |||

1312 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1313 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1314 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1315 | \subsection{The \texttt{arbint rndiv} Extension} | ||

1316 | %Subsection Tag: RDV0 | ||

1317 | \label{cxtn0:srne0:srdv0} | ||

1318 | |||

1319 | \index{arbint rndiv@\emph{arbint rndiv}} | ||

1320 | \index{rndiv@\emph{rndiv}} | ||

1321 | \begin{tclcommandname}{arbint rndiv}% | ||

1322 | divides two rational numbers to produce a normalized rational result. | ||

1323 | \end{tclcommandname} | ||

1324 | |||

1325 | \begin{tclcommandsynopsis} | ||

1326 | \tclcommandsynopsisline{arbint rndiv}{srn srn} | ||

1327 | \end{tclcommandsynopsis} | ||

1328 | |||

1329 | \begin{tclcommanddescription} | ||

1330 | The \emph{arbint rndiv} extension divides two rational numbers to produce a | ||

1331 | normalized rational result. | ||

1332 | |||

1333 | If either of the two rational input arguments has a denominator of zero, or | ||

1334 | if the divisor is zero, | ||

1335 | the string ``NAN'' will be returned. | ||

1336 | \end{tclcommanddescription} | ||

1337 | |||

1338 | \begin{tclcommandsampleinvocations} | ||

1339 | \begin{scriptsize} | ||

1340 | \begin{verbatim} | ||

1341 | % arbint rndiv 3.14 32/491 | ||

1342 | 77087/1600 | ||

1343 | \end{verbatim} | ||

1344 | \end{scriptsize} | ||

1345 | \end{tclcommandsampleinvocations} | ||

1346 | |||

1347 | \begin{tclcommandseealso} | ||

1348 | See also the \emph{rnmul} DOS command-line utility, | ||

1349 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:srnu0:srdv0}. | ||

1350 | \end{tclcommandseealso} | ||

1351 | |||

1352 | |||

1353 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1354 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1355 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1356 | \subsection{The \texttt{arbint rncmp} Extension} | ||

1357 | %Subsection Tag: RCM0 | ||

1358 | \label{cxtn0:srne0:srcm0} | ||

1359 | |||

1360 | \index{arbint rncmp@\emph{arbint rncmp}} | ||

1361 | \index{rncmp@\emph{rncmp}} | ||

1362 | \begin{tclcommandname}{arbint rncmp}% | ||

1363 | compares two rational numbers. | ||

1364 | \end{tclcommandname} | ||

1365 | |||

1366 | \begin{tclcommandsynopsis} | ||

1367 | \tclcommandsynopsisline{arbint rncmp}{srn\_arg1 srn\_arg2} | ||

1368 | \end{tclcommandsynopsis} | ||

1369 | |||

1370 | \begin{tclcommanddescription} | ||

1371 | The \emph{arbint rncmp} extension compares two rational numbers | ||

1372 | and returns $\{-1, 0, 1\}$ if $arg_1$ | ||

1373 | $\{<, =, >\}$ $arg_2$. | ||

1374 | |||

1375 | The rational numbers do not need to be reduced or normalized in any way. | ||

1376 | Any combination of signs on the numerators and denominators is permitted, | ||

1377 | and the numerators and denominators are not required to be coprime. | ||

1378 | |||

1379 | If for any reason the extension cannot compare the rational numbers, | ||

1380 | an error message will be returned and the extension will return | ||

1381 | \texttt{TCL\_ERROR}, which will normally cause a script to fail. | ||

1382 | The reason for the error return is that if the two rational number | ||

1383 | cannot be compared, in most cases it is logically impossible for a script to | ||

1384 | continue. | ||

1385 | \end{tclcommanddescription} | ||

1386 | |||

1387 | \begin{tclcommandsampleinvocations} | ||

1388 | \begin{scriptsize} | ||

1389 | \begin{verbatim} | ||

1390 | % arbint rncmp -4/-7 0.5 | ||

1391 | 1 | ||

1392 | \end{verbatim} | ||

1393 | \end{scriptsize} | ||

1394 | \end{tclcommandsampleinvocations} | ||

1395 | |||

1396 | |||

1397 | \begin{tclcommandseealso} | ||

1398 | See also the \emph{arbint intcmp} Tcl extension, | ||

1399 | Section \ref{cxtn0:sarb0:scmp0}, which performs a similar | ||

1400 | function for arbitrary integers. | ||

1401 | \end{tclcommandseealso} | ||

1402 | |||

1403 | |||

1404 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1405 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1406 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1407 | \section{Number Theory Extensions} | ||

1408 | %Section Tag: NTH0 | ||

1409 | \label{cxtn0:snth0} | ||

1410 | |||

1411 | This section describes extensions that are related to number theory. | ||

1412 | Extensions that deal with continued fractions are included in this | ||

1413 | category because of the relationship between continued fractions | ||

1414 | and number theory. Any extensions related to number theory that | ||

1415 | must process large integers are | ||

1416 | still a subextension of \texttt{arbint}.\footnote{This was done to | ||

1417 | avoid creating an excessive number of software modules and | ||

1418 | Tcl extensions.} | ||

1419 | |||

1420 | |||

1421 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1422 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1423 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1424 | \subsection{The \texttt{arbint cfratnum} Extension} | ||

1425 | %Subsection Tag: CFR0 | ||

1426 | \label{cxtn0:snth0:scfr0} | ||

1427 | |||

1428 | \index{arbint cfratnum@\emph{arbint cfratnum}} | ||

1429 | \index{cfratnum@\emph{cfratnum}} | ||

1430 | \begin{tclcommandname}{arbint cfratnum}% | ||

1431 | calculates the partial quotients and convergents of | ||

1432 | a non-negative rational number. | ||

1433 | \end{tclcommandname} | ||

1434 | |||

1435 | \begin{tclcommandsynopsis} | ||

1436 | \tclcommandsynopsisline{arbint cfratnum}{urn} | ||

1437 | \end{tclcommandsynopsis} | ||

1438 | |||

1439 | \begin{tclcommanddescription} | ||

1440 | This extension calculates the partial quotients and convergents of | ||

1441 | of a non-negative rational number. The results are | ||

1442 | returned as a string containing integers separated by spaces. | ||

1443 | The integers are arranged in consecutive triplets of the form | ||

1444 | ``$a_k \; p_k \; q_k$''. Such a string can be converted to a | ||

1445 | list and processed from a Tcl script. | ||

1446 | \end{tclcommanddescription} | ||

1447 | |||

1448 | \begin{tclcommandsampleinvocations} | ||

1449 | \begin{scriptsize} | ||

1450 | \begin{verbatim} | ||

1451 | % arbint cfratnum 3.14 | ||

1452 | 3 3 1 7 22 7 7 157 50 | ||

1453 | \end{verbatim} | ||

1454 | \end{scriptsize} | ||

1455 | |||

1456 | In the sample invocation above, note that $a_0 = 3$, | ||

1457 | $p_0 = 3$, $q_0 = 1$, $a_1 = 7$, $p_1 = 22$, $q_1 = 7$, | ||

1458 | $a_2 = 7$, $p_2 = 157$, and $q_2 = 50$. | ||

1459 | \end{tclcommandsampleinvocations} | ||

1460 | |||

1461 | \begin{tclcommandseealso} | ||

1462 | See also the \emph{cfratnum} DOS command-line utility, | ||

1463 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:snth0:scfr0}. | ||

1464 | \end{tclcommandseealso} | ||

1465 | |||

1466 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1467 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1468 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1469 | \subsection{The \texttt{arbint cfbrapab} Extension} | ||

1470 | %Subsection Tag: BRA0 | ||

1471 | \label{cxtn0:snth0:sbra0} | ||

1472 | |||

1473 | \index{arbint cfbrapab@\emph{arbint cfbrapab}} | ||

1474 | \index{cfbrapab@\emph{cfbrapab}} | ||

1475 | \begin{tclcommandname}{arbint cfbrapab}% | ||

1476 | finds best rational approximations to a supplied rational | ||

1477 | number in either the Farey series of order $k_{MAX}$ (denoted | ||

1478 | $F_{k_{MAX}}$), or in a rectangular region of the integer lattice | ||

1479 | bounded by $k \leq k_{MAX}$ and $h \leq h_{MAX}$ | ||

1480 | (denoted $F_{k_{MAX}, \overline{h_{MAX}}}$). | ||

1481 | \end{tclcommandname} | ||

1482 | |||

1483 | \begin{tclcommandsynopsis} | ||

1484 | \tclcommandsynopsisline{arbint cfbrapab}{srn uint\_kmax [options]} | ||

1485 | \tclcommandsynopsisline{arbint cfbrapab}{srn uint\_kmax uint\_hmax [options]} | ||

1486 | \end{tclcommandsynopsis} | ||

1487 | |||

1488 | \begin{tclcommanddescription} | ||

1489 | When used without options, this extension returns the closest rational | ||

1490 | number to the specified rational number in $F_{k_{MAX}}$ (if only $k_{MAX}$ is | ||

1491 | specified) or in $F_{k_{MAX}, \overline{h_{MAX}}}$ (if both | ||

1492 | $k_{MAX}$ and $h_{MAX}$ are specified). If the rational number specified | ||

1493 | is already in the series of interest, its reduced form is returned. | ||

1494 | If the rational number supplied is equidistant from the two closest | ||

1495 | formable rational numbers in the series of interest, the neighbor of smaller | ||

1496 | magnitude (absolute value) is returned. | ||

1497 | |||

1498 | When operating in $F_{k_{MAX}}$, there are no practical constraints | ||

1499 | on the size of rational numbers that this extension can approximate. | ||

1500 | However, when operating in $F_{k_{MAX}, \overline{h_{MAX}}}$, | ||

1501 | this extension will not accept rational numbers outside the | ||

1502 | interval $[-h_{MAX}, h_{MAX}]$ (note that $-h_{MAX}/1$ and | ||

1503 | $h_{MAX}/1$ are the smallest and largest numbers that can be formed | ||

1504 | when the numerator of the rational approximations is constrained). | ||

1505 | Any attempt to approximate a rational number outside $[-h_{MAX}, h_{MAX}]$ | ||

1506 | will result in a Tcl error, which will normally terminate a script. | ||

1507 | |||

1508 | The \texttt{-neversmaller} and \texttt{-neverlarger} | ||

1509 | options cause the extension to always choose the larger and | ||

1510 | smaller neighbors (rather than the closer neighbor), respectively. | ||

1511 | These options are useful when approximations are desired that | ||

1512 | do not underestimate or overestimate the function of interest for | ||

1513 | large values in the domain. These parameters do not affect | ||

1514 | the behavior if the rational number supplied is already in the | ||

1515 | series of interest---the reduced form of the specified number | ||

1516 | is returned in the case of equality. | ||

1517 | The \texttt{-neversmaller} and \texttt{-neverlarger} options | ||

1518 | must be used alone, with no other options. | ||

1519 | |||

1520 | The \texttt{-pred} and \texttt{-succ} options cause this extension | ||

1521 | to calculate either the predecessor or successor to the rational | ||

1522 | number specified in the series of interest. If the number specified | ||

1523 | is already in series of interest, its predecessor or successor | ||

1524 | is returned. | ||

1525 | If the number specified is not in the series of interest, | ||

1526 | the left or right neighbor is returned. If no predecessor, | ||

1527 | successor, or left or right neighbor exist, an error is generated. | ||

1528 | These options (\texttt{-pred} or \texttt{-succ}) | ||

1529 | must be used alone, with no other options. | ||

1530 | |||

1531 | The normal behavior of this extension is to return a single | ||

1532 | rational number, as described above. | ||

1533 | The \texttt{-n \emph{uint32\_count}} option will cause the extension | ||

1534 | to return \emph{count} rational numbers on each side of the | ||

1535 | rational number specified. If the rational number specified is already | ||

1536 | in the series of interest, it will be returned as well, normally\footnote{If | ||

1537 | the set of returned rational numbers is not clipped at $-h_{MAX}/1$ or | ||

1538 | $h_{MAX}/1$.} resulting | ||

1539 | in an odd number of rational numbers returned. If the rational number | ||

1540 | specified is not already in the series of interest, an even number of | ||

1541 | rational numbers will normally be returned. The rational | ||

1542 | numbers returned are prefixed with integer indices, which | ||

1543 | indicate their ordinal distance from the rational number to be approximated | ||

1544 | (see the invocation examples below). The index of 0 is reserved for | ||

1545 | the reduced form of the rational number specified, and and a rational number with | ||

1546 | this index will be in the output only if the rational number supplied was already | ||

1547 | in the series of interest. | ||

1548 | The rational numbers returned | ||

1549 | will be formatted as integer indices and slash-separated integers, separated | ||

1550 | by single spaces and arranged in ascending order.. | ||

1551 | If the number of rational numbers requested by this option exceeds | ||

1552 | the number available, the sequence will simply be truncated at | ||

1553 | $-h_{MAX}/1$ or $h_{MAX}/1$, as appropriate. Any request for more than | ||

1554 | 10,000 neighbors (on each side) will be clipped to 10,000. | ||

1555 | \end{tclcommanddescription} | ||

1556 | |||

1557 | \begin{tclcommandsampleinvocations} | ||

1558 | \begin{scriptsize} | ||

1559 | \begin{verbatim} | ||

1560 | % arbint cfbrapab 1.6093 255 | ||

1561 | 346/215 | ||

1562 | % arbint cfbrapab 1.6093 255 255 | ||

1563 | 243/151 | ||

1564 | % arbint cfbrapab 1.6093 255 255 -neversmaller | ||

1565 | 103/64 | ||

1566 | % arbint cfbrapab 1.6093 255 255 -neverlarger | ||

1567 | 243/151 | ||

1568 | % arbint cfbrapab 1.6093 255 255 -n 20 | ||

1569 | -20 143/89 -19 188/117 -18 233/145 -17 45/28 -16 217/135 -15 172/107 -14 127/79 | ||

1570 | -13 209/130 -12 82/51 -11 201/125 -10 119/74 -9 156/97 -8 193/120 -7 230/143 -6 | ||

1571 | 37/23 -5 251/156 -4 214/133 -3 177/110 -2 140/87 -1 243/151 1 103/64 2 169/105 | ||

1572 | 3 235/146 4 66/41 5 227/141 6 161/100 7 95/59 8 219/136 9 124/77 10 153/95 11 | ||

1573 | 182/113 12 211/131 13 240/149 14 29/18 15 253/157 16 224/139 17 195/121 18 | ||

1574 | 166/103 19 137/85 20 245/152 | ||

1575 | % arbint cfbrapab 1.6093 255 255 -succ | ||

1576 | 103/64 | ||

1577 | % arbint cfbrapab 1.6093 255 255 -pred | ||

1578 | 243/151 | ||

1579 | % arbint cfbrapab 2/3 255 255 -pred | ||

1580 | 169/254 | ||

1581 | \end{verbatim} | ||

1582 | \end{scriptsize} | ||

1583 | \end{tclcommandsampleinvocations} | ||

1584 | |||

1585 | \begin{tclcommandseealso} | ||

1586 | This extension uses the continued fraction | ||

1587 | algorithms presented in Chapter \ccfrzeroxrefhyphen{}\ref{ccfr0}. | ||

1588 | See also the \emph{cfratnum} DOS command-line utility, | ||

1589 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:snth0:sbra0}. | ||

1590 | \end{tclcommandseealso} | ||

1591 | |||

1592 | |||

1593 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1594 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1595 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1596 | \subsection{The \texttt{arbint const} Extension} | ||

1597 | %Subsection Tag: CEX0 | ||

1598 | \label{cxtn0:snth0:scex0} | ||

1599 | |||

1600 | \index{arbint const@\emph{arbint const}} | ||

1601 | \index{const (Tcl arbint sub-extension)@\emph{const} (Tcl \emph{arbint} sub-extension)} | ||

1602 | \begin{tclcommandname}{arbint const}% | ||

1603 | returns a string representing the value of important | ||

1604 | mathematical and conversion constants (such as the value | ||

1605 | of $\pi$ or $e$, or the conversion factor from miles to kilometers). | ||

1606 | \end{tclcommandname} | ||

1607 | |||

1608 | \begin{tclcommandsynopsis} | ||

1609 | \tclcommandsynopsisline{arbint const}{const\_tag} | ||

1610 | \tclcommandsynopsisline{arbint const}{const\_tag uint32\_ndigits} | ||

1611 | \end{tclcommandsynopsis} | ||

1612 | |||

1613 | \begin{tclcommanddescription} | ||

1614 | The \emph{const} subextension returns the value (as a string) of | ||

1615 | constants that may be useful in engineering work. Such constants | ||

1616 | may include mathematically significant numbers (such as | ||

1617 | \index{pi@$\pi$ (transcendental constant)}$\pi$ or | ||

1618 | \index{e@$e$ (transcendental constant)}$e$), or | ||

1619 | useful conversion factors (the conversion factor from | ||

1620 | miles to kilometers, for example). These string constants | ||

1621 | can be used in calculations involving rational numbers. | ||

1622 | |||

1623 | All constants are simply tabulated as character strings | ||

1624 | within the `C' source code. | ||

1625 | |||

1626 | Mathematically significant numbers (which, to the best | ||

1627 | of the author's knowledge are always irrational and | ||

1628 | usually transcendental, as mathematicians | ||

1629 | don't seem to have any lasting interest in specific integers | ||

1630 | or rational numbers) are available to about 1,000 significant digits, | ||

1631 | and have been obtained from various web pages. It is reasoned that | ||

1632 | 1,000 significant digits should be adequate for engineering applications. | ||

1633 | |||

1634 | Measurement unit conversion constants have typically been obtained from | ||

1635 | \emph{NIST Special Publication 811} \cite{bibref:b:nistsp811:1995ed}. | ||

1636 | These constants are always tabulated with their full precision, since | ||

1637 | no physical constant can be precise to more than several decimal places. | ||

1638 | |||

1639 | If the number of significant figures is not specified, | ||

1640 | each constant is returned as a string with a default number of | ||

1641 | decimal places (typically about 30). In most cases, the default | ||

1642 | number of decimal places provides more than enough precision for | ||

1643 | engineering work. However, an optional parameter allows more | ||

1644 | or fewer digits to be obtained, up to the maximum number tabulated internally | ||

1645 | in the software. The default number of decimal places is a compromise | ||

1646 | between calculation speed and accuracy. It is felt in most cases that | ||

1647 | the default number of decimal places provides excellent accuracy | ||

1648 | and good calculation speed. | ||

1649 | |||

1650 | Please e-mail the authors if you would like additional useful | ||

1651 | constants included. Because the list of tabulated constants | ||

1652 | may grow and shrink, it would not be a sound decision to document | ||

1653 | the constants which are included here. Instead, use | ||

1654 | \emph{arbint const} with an invalid tag, and the software itself | ||

1655 | will list all of the internally tabulated constants and their | ||

1656 | significance. | ||

1657 | \end{tclcommanddescription} | ||

1658 | |||

1659 | \begin{tclcommandsampleinvocations} | ||

1660 | Please note that the sample invocation below was created using | ||

1661 | v1.05 of the tool set. The list of constants may have grown | ||

1662 | since this example was created. Please poll the software directly | ||

1663 | by using \emph{arbint const} with an invalid tag to obtain the | ||

1664 | list of constants and their significance. | ||

1665 | \begin{scriptsize} | ||

1666 | \begin{verbatim} | ||

1667 | % arbint const xxx | ||

1668 | arbint const: "xxx" is not a recognized constant. | ||

1669 | Available constants are: | ||

1670 | e (1000 digits available) | ||

1671 | Historically significant transcendental constant. Digits obtained | ||

1672 | from http://fermi.udw.ac.za/physics/e.html on 08/17/01. | ||

1673 | g_si (6 digits available) | ||

1674 | Gravitational acceleration in SI units, meters per second**2. | ||

1675 | Obtained from NIST Special Publication 811 on 08/17/01. | ||

1676 | in2m (3 digits available) | ||

1677 | Multiplicative conversion factor from inches to meters. | ||

1678 | Obtained from NIST Special Publication 811 on 08/17/01. | ||

1679 | mi2km (7 digits available) | ||

1680 | Multiplicative conversion factor from miles to kilometers. | ||

1681 | Obtained from NIST Special Publication 811 on 08/17/01. | ||

1682 | pi (1201 digits available) | ||

1683 | Transcendental constant supplying ratio of a circle's circumference | ||

1684 | to its diameter. Digits obtained from http://www.joyofpi.com/ | ||

1685 | pi.htm on 08/17/01. | ||

1686 | sqrt5 (1040 digits available) | ||

1687 | The square root of 5. Digits obtained from | ||

1688 | http://home.earthlink.net/~maryski/sqrt51000000.txt on 08/17/01. | ||

1689 | % arbint const pi | ||

1690 | 3.14159265358979323846264338327 | ||

1691 | % arbint const pi 100 | ||

1692 | 3.141592653589793238462643383279502884197169399375105820974944592307816406286208998628034825342117067 | ||

1693 | % arbint const pi 10 | ||

1694 | 3.141592653 | ||

1695 | % arbint cfbrapab [arbint const pi 100] 65535 65535 | ||

1696 | 65298/20785 | ||

1697 | \end{verbatim} | ||

1698 | \end{scriptsize} | ||

1699 | \end{tclcommandsampleinvocations} | ||

1700 | |||

1701 | |||

1702 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1703 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1704 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1705 | \section{Miscellaneous Extensions} | ||

1706 | |||

1707 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1708 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1709 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1710 | \subsection{credits} | ||

1711 | |||

1712 | \index{credits@\emph{credits}} | ||

1713 | \begin{tclcommandname}{credits}% | ||

1714 | returns information about authorship of software components. | ||

1715 | \end{tclcommandname} | ||

1716 | |||

1717 | \begin{tclcommandsynopsis} | ||

1718 | \tclcommandsynopsisline{credits}{} | ||

1719 | \tclcommandsynopsisline{credits}{searchstring} | ||

1720 | \end{tclcommandsynopsis} | ||

1721 | |||

1722 | \begin{tclcommanddescription} | ||

1723 | The \emph{credits} command returns a list of contributors to the tools, | ||

1724 | their area(s) of contribution, and e-mail addresses. The volume of | ||

1725 | information returned can be reduced by using an optional \emph{searchstring}. | ||

1726 | |||

1727 | \tclcommanddescsynopsisline{credits}{} | ||

1728 | \begin{tclcommandinternaldescription} | ||

1729 | Returns the complete list of contributors to the tools and their area(s) of contribution. | ||

1730 | \end{tclcommandinternaldescription} | ||

1731 | |||

1732 | \tclcommanddescsynopsisline{credits}{searchstring} | ||

1733 | \begin{tclcommandinternaldescription} | ||

1734 | Returns all credit records containing \emph{searchstring}. | ||

1735 | Most commonly, this option is used to search for information about a specific | ||

1736 | command by using the command name as the \emph{searchstring}, or about a | ||

1737 | specific individual by using a component of the individual's name as the | ||

1738 | \emph{searchstring}. | ||

1739 | |||

1740 | \end{tclcommandinternaldescription} | ||

1741 | |||

1742 | \end{tclcommanddescription} | ||

1743 | |||

1744 | |||

1745 | |||

1746 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1747 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1748 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1749 | \noindent\begin{figure}[!b] | ||

1750 | \noindent\rule[-0.25in]{\textwidth}{1pt} | ||

1751 | \begin{tiny} | ||

1752 | \begin{verbatim} | ||

1753 | $RCSfile: c_xtn0.tex,v $ | ||

1754 | $Source: /home/dashley/cvsrep/e3ft_gpl01/e3ft_gpl01/dtaipubs/esrgubka/c_xtn0/c_xtn0.tex,v $ | ||

1755 | $Revision: 1.11 $ | ||

1756 | $Author: dtashley $ | ||

1757 | $Date: 2003/04/03 19:49:36 $ | ||

1758 | \end{verbatim} | ||

1759 | \end{tiny} | ||

1760 | \noindent\rule[0.25in]{\textwidth}{1pt} | ||

1761 | \end{figure} | ||

1762 | |||

1763 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1764 | % $Log: c_xtn0.tex,v $ | ||

1765 | % Revision 1.11 2003/04/03 19:49:36 dtashley | ||

1766 | % Global corrections to typeface of "gcd" made as per Jan-Hinnerk Reichert's | ||

1767 | % recommendation. | ||

1768 | % | ||

1769 | % Revision 1.10 2001/08/18 18:37:56 dtashley | ||

1770 | % Preparation for v1.05 release. | ||

1771 | % | ||

1772 | % Revision 1.9 2001/08/16 19:53:27 dtashley | ||

1773 | % Beginning to prepare for v1.05 release. | ||

1774 | % | ||

1775 | % Revision 1.8 2001/08/12 10:15:33 dtashley | ||

1776 | % Safety check-in. Substantial progress. | ||

1777 | % | ||

1778 | % Revision 1.7 2001/08/10 00:56:07 dtashley | ||

1779 | % Completion of basic rational number arithmetic utilities and extensions. | ||

1780 | % | ||

1781 | % Revision 1.6 2001/08/08 02:25:03 dtashley | ||

1782 | % Completion of RNRED utility and ARBINT RNRED Tcl extension. | ||

1783 | % | ||

1784 | % Revision 1.5 2001/08/07 10:46:44 dtashley | ||

1785 | % Completion of CFRATNUM Tcl extension and DOS command-line utility. | ||

1786 | % | ||

1787 | % Revision 1.4 2001/08/01 03:37:39 dtashley | ||

1788 | % Finished most primitive integer operations, both as Tcl extensions and | ||

1789 | % as DOS command-line utilities, such as addition, subtraction, | ||

1790 | % multiplication, division, and modulo. | ||

1791 | % | ||

1792 | % Revision 1.3 2001/07/30 02:54:17 dtashley | ||

1793 | % INTFAC extension and command-line utility finished. | ||

1794 | % | ||

1795 | % Revision 1.2 2001/07/01 20:50:58 dtashley | ||

1796 | % Move out of binary mode for use with CVS. | ||

1797 | % | ||

1798 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||

1799 | % $History: c_xtn0.tex $ | ||

1800 | % | ||

1801 | % ***************** Version 3 ***************** | ||

1802 | % User: Dashley1 Date: 2/10/01 Time: 2:03a | ||

1803 | % Updated in $/uC Software Multi-Volume Book (A)/Chapter, XTN0, IjuScripter-IjuConsole Tcl-Tk Extensions | ||

1804 | % Completion of Farey series chapter. | ||

1805 | % | ||

1806 | % ***************** Version 2 ***************** | ||

1807 | % User: Dashley1 Date: 1/01/01 Time: 8:13p | ||

1808 | % Updated in $/uC Software Multi-Volume Book (A)/Chapter, XTN0, IjuScripter-IjuConsole Tcl-Tk Extensions | ||

1809 | % Edits. | ||

1810 | % | ||

1811 | % ***************** Version 1 ***************** | ||

1812 | % User: Dashley1 Date: 12/31/00 Time: 9:34p | ||

1813 | % Created in $/uC Software Multi-Volume Book (A)/Chapter, XTN0, IjuScripter-IjuConsole Tcl-Tk Extensions | ||

1814 | % Initial check-in. | ||

1815 | % | ||

1816 | %End of file C_XTN0.TEX |

dashley@gmail.com | ViewVC Help |

Powered by ViewVC 1.1.25 |