Parent Directory | Revision Log

Revision **278** -
(**show annotations**)
(**download**)
(**as text**)

*Wed Aug 14 23:10:36 2019 UTC*
(5 years ago)
by *dashley*

File MIME type: application/x-tex

File size: 70523 byte(s)

File MIME type: application/x-tex

File size: 70523 byte(s)

Change keyword substitution (migration from cvs to svn).

1 | %$Header$ |

2 | |

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

4 | |

5 | \label{cxtn0} |

6 | |

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

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

9 | {Unknown} |

10 | |

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

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

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

14 | \section{Introduction} |

15 | %Section Tag: INT0 |

16 | \label{cxtn0:sint0} |

17 | |

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

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

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

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

22 | a Tcl script. |

23 | |

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

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

26 | |

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

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

29 | utilities (described in Chapter |

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

31 | redundancy of documentation, the parameter formats described |

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

33 | Tcl extensions |

34 | and the DOS command-line utilities. |

35 | |

36 | |

37 | |

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

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

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

41 | \section{Version Control Extensions} |

42 | |

43 | |

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

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

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

47 | \subsection{vcinfo} |

48 | |

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

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

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

52 | IjuScripter or IjuConsole. |

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

54 | running under. |

55 | \end{tclcommandname} |

56 | |

57 | \begin{tclcommandsynopsis} |

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

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

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

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

62 | \end{tclcommandsynopsis} |

63 | |

64 | \begin{tclcommanddescription} |

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

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

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

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

69 | This command can be used to |

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

71 | components. |

72 | |

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

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

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

76 | |

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

78 | \begin{tclcommandinternaldescription} |

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

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

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

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

83 | but adds no new functionality. |

84 | |

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

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

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

88 | no new functionality. |

89 | \end{tclcommandinternaldescription} |

90 | |

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

92 | \begin{tclcommandinternaldescription} |

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

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

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

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

97 | \end{tclcommandinternaldescription} |

98 | |

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

100 | \begin{tclcommandinternaldescription} |

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

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

103 | rather than the CRC of the file. |

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

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

106 | This form is |

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

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

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

110 | \end{tclcommandinternaldescription} |

111 | |

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

113 | \begin{tclcommandinternaldescription} |

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

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

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

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

118 | is supplied. |

119 | \end{tclcommandinternaldescription} |

120 | |

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

122 | \begin{tclcommandinternaldescription} |

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

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

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

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

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

128 | This form is |

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

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

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

132 | \end{tclcommandinternaldescription} |

133 | |

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

135 | \begin{tclcommandinternaldescription} |

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

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

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

139 | \end{tclcommandinternaldescription} |

140 | |

141 | \end{tclcommanddescription} |

142 | |

143 | |

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

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

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

147 | \section{File Transformation Extensions} |

148 | |

149 | |

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

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

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

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

154 | %Section Tag: CRC0 |

155 | |

156 | |

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

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

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

160 | \subsection{crc32} |

161 | %Subsection Tag: CRC0 |

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

163 | |

164 | |

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

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

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

168 | digital signatures of files or data. |

169 | \end{tclcommandname} |

170 | |

171 | \begin{tclcommandsynopsis} |

172 | \tclcommandsynopsisline{crc32}{filename} |

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

174 | |

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

176 | |

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

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

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

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

181 | \end{tclcommandsynopsis} |

182 | |

183 | \begin{tclcommanddescription} |

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

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

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

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

188 | that two files are almost certainly identical. |

189 | |

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

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

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

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

194 | aesthetics. It is guaranteed that: |

195 | |

196 | \begin{itemize} |

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

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

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

200 | \item The hexadecimal representation |

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

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

203 | \end{itemize} |

204 | |

205 | \tclcommanddescsynopsisline{crc32}{filename} |

206 | \begin{tclcommandinternaldescription} |

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

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

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

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

211 | \end{tclcommandinternaldescription} |

212 | |

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

214 | \begin{tclcommandinternaldescription} |

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

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

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

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

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

220 | \end{tclcommandinternaldescription} |

221 | |

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

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

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

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

226 | \begin{tclcommandinternaldescription} |

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

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

229 | state vector of the CRC calculation algorithm. |

230 | |

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

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

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

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

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

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

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

238 | |

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

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

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

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

243 | |

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

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

246 | \end{tclcommandinternaldescription} |

247 | \end{tclcommanddescription} |

248 | |

249 | \begin{tclcommandusagenotes} |

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

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

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

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

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

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

256 | larger chunks will give better performance. |

257 | |

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

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

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

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

262 | \end{tclcommandusagenotes} |

263 | |

264 | \begin{tclcommandacknowledgements} |

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

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

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

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

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

270 | and free of charge. |

271 | \end{tclcommandacknowledgements} |

272 | |

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

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

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

276 | \section{Random Number Generation Extensions} |

277 | |

278 | |

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

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

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

282 | \subsection{rngPwrResRndA} |

283 | |

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

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

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

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

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

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

290 | \end{tclcommandname} |

291 | |

292 | \begin{tclcommandsynopsis} |

293 | \tclcommandsynopsisline{rngPwrResRndA}{} |

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

295 | \end{tclcommandsynopsis} |

296 | |

297 | \begin{tclcommanddescription} |

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

299 | using the [power residue] recursive formula |

300 | |

301 | \begin{equation} |

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

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

304 | \end{equation} |

305 | |

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

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

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

309 | |

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

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

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

313 | |

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

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

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

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

318 | It is not possible to set the internal |

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

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

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

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

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

324 | script. |

325 | |

326 | |

327 | \tclcommanddescsynopsisline{rngPwrResRndA}{} |

328 | \begin{tclcommandinternaldescription} |

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

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

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

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

333 | \end{tclcommandinternaldescription} |

334 | |

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

336 | \begin{tclcommandinternaldescription} |

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

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

339 | \end{tclcommandinternaldescription} |

340 | |

341 | \end{tclcommanddescription} |

342 | |

343 | |

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

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

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

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

348 | %Section Tag: SARB0 |

349 | \label{cxtn0:sarb0} |

350 | |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

365 | data size limit is approached. |

366 | |

367 | |

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

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

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

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

372 | %Subsection Tag: EAB0 |

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

374 | |

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

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

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

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

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

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

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

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

383 | the first two flags listed below). |

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

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

386 | |

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

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

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

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

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

392 | they are adequate to prevent the interpretation |

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

394 | result will itself be invalid. |

395 | |

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

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

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

399 | |

400 | \begin{itemize} |

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

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

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

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

405 | dividend. |

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

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

408 | large in a negative direction). |

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

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

411 | by combination with an integer which has the |

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

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

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

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

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

417 | \end{itemize} |

418 | |

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

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

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

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

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

424 | errors after every calculation step. |

425 | |

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

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

428 | should also be noted |

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

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

431 | |

432 | |

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

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

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

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

437 | |

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

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

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

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

442 | returns an integer value categorizing the string. |

443 | \end{tclcommandname} |

444 | |

445 | \begin{tclcommandsynopsis} |

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

447 | \end{tclcommandsynopsis} |

448 | |

449 | \begin{tclcommanddescription} |

450 | This extension returns: |

451 | \begin{itemize} |

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

453 | error flag. |

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

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

456 | error flag. |

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

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

459 | error flag. |

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

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

462 | error flag. |

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

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

465 | error flag. |

466 | \end{itemize} |

467 | |

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

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

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

471 | \end{tclcommanddescription} |

472 | |

473 | \begin{tclcommandsampleinvocations} |

474 | \begin{scriptsize} |

475 | \begin{verbatim} |

476 | % arbint iseflag GMP_INTS_EF_INTOVF_NEG |

477 | 2 |

478 | % arbint iseflag 249,422 |

479 | 0 |

480 | \end{verbatim} |

481 | \end{scriptsize} |

482 | \end{tclcommandsampleinvocations} |

483 | |

484 | \begin{tclcommandseealso} |

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

486 | \end{tclcommandseealso} |

487 | |

488 | |

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

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

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

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

493 | %Subsection Tag: COM0 |

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

495 | |

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

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

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

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

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

501 | \end{tclcommandname} |

502 | |

503 | \begin{tclcommandsynopsis} |

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

505 | \end{tclcommandsynopsis} |

506 | |

507 | \begin{tclcommanddescription} |

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

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

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

511 | must be either: |

512 | |

513 | \begin{itemize} |

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

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

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

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

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

519 | ``commanated''). |

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

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

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

523 | this extension.) |

524 | \end{itemize} |

525 | |

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

527 | an error. |

528 | \end{tclcommanddescription} |

529 | |

530 | \begin{tclcommandsampleinvocations} |

531 | \begin{scriptsize} |

532 | \begin{verbatim} |

533 | % arbint intfac 129 |

534 | 4974504222477287440390234150412680963965661113713884314596886402265216893219635 |

535 | 5119328515747917449637889876686464600208839390308261862352651828829226610077151 |

536 | 044469167497022952331930501120000000000000000000000000000000 |

537 | % arbint commanate [arbint intfac 129] |

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

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

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

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

542 | % arbint commanate GMP_INTS_EF_INTOVF_POS |

543 | GMP_INTS_EF_INTOVF_POS |

544 | \end{verbatim} |

545 | \end{scriptsize} |

546 | \end{tclcommandsampleinvocations} |

547 | |

548 | |

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

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

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

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

553 | %Subsection Tag: dco0 |

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

555 | |

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

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

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

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

560 | formatted integer. |

561 | \end{tclcommandname} |

562 | |

563 | \begin{tclcommandsynopsis} |

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

565 | \end{tclcommandsynopsis} |

566 | |

567 | \begin{tclcommanddescription} |

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

569 | The input to this extension |

570 | must be either: |

571 | |

572 | \begin{itemize} |

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

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

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

576 | an integer that contains no commas.) |

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

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

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

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

581 | this extension.) |

582 | \end{itemize} |

583 | |

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

585 | an error. |

586 | \end{tclcommanddescription} |

587 | |

588 | \begin{tclcommandsampleinvocations} |

589 | \begin{scriptsize} |

590 | \begin{verbatim} |

591 | % arbint intfac 129 |

592 | 4974504222477287440390234150412680963965661113713884314596886402265216893219635 |

593 | 5119328515747917449637889876686464600208839390308261862352651828829226610077151 |

594 | 044469167497022952331930501120000000000000000000000000000000 |

595 | % arbint commanate [arbint intfac 129] |

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

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

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

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

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

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

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

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

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

605 | % arbint decommanate $number |

606 | 4974504222477287440390234150412680963965661113713884314596886402265216893219635 |

607 | 5119328515747917449637889876686464600208839390308261862352651828829226610077151 |

608 | 044469167497022952331930501120000000000000000000000000000000 |

609 | % arbint decommanate GMP_INTS_EF_INTOVF_POS |

610 | GMP_INTS_EF_INTOVF_POS |

611 | \end{verbatim} |

612 | \end{scriptsize} |

613 | \end{tclcommandsampleinvocations} |

614 | |

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

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

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

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

619 | %Subsection Tag: add0 |

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

621 | |

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

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

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

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

626 | ordering. |

627 | \end{tclcommandname} |

628 | |

629 | \begin{tclcommandsynopsis} |

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

631 | \end{tclcommandsynopsis} |

632 | |

633 | \begin{tclcommanddescription} |

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

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

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

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

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

639 | cannot be logically compared, |

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

641 | a NAN tag. |

642 | \end{tclcommanddescription} |

643 | |

644 | \begin{tclcommandsampleinvocations} |

645 | \begin{scriptsize} |

646 | \begin{verbatim} |

647 | % arbint intcmp -5 -3 |

648 | -1 |

649 | % arbint intcmp -5 -5 |

650 | 0 |

651 | % arbint intcmp 7 5 |

652 | 1 |

653 | \end{verbatim} |

654 | \end{scriptsize} |

655 | \end{tclcommandsampleinvocations} |

656 | |

657 | \begin{tclcommandseealso} |

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

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

660 | function for arbitrary rational numbers. |

661 | \end{tclcommandseealso} |

662 | |

663 | |

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

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

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

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

668 | %Subsection Tag: add0 |

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

670 | |

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

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

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

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

675 | \end{tclcommandname} |

676 | |

677 | \begin{tclcommandsynopsis} |

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

679 | \end{tclcommandsynopsis} |

680 | |

681 | \begin{tclcommanddescription} |

682 | This extension returns the sum of two integer |

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

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

685 | \end{tclcommanddescription} |

686 | |

687 | \begin{tclcommandsampleinvocations} |

688 | \begin{scriptsize} |

689 | \begin{verbatim} |

690 | % arbint intadd 1e20 21643215482123164 |

691 | 100021643215482123164 |

692 | \end{verbatim} |

693 | \end{scriptsize} |

694 | \end{tclcommandsampleinvocations} |

695 | |

696 | \begin{tclcommandseealso} |

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

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

699 | \end{tclcommandseealso} |

700 | |

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

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

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

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

705 | %Subsection Tag: mod0 |

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

707 | |

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

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

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

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

712 | \end{tclcommandname} |

713 | |

714 | \begin{tclcommandsynopsis} |

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

716 | \end{tclcommandsynopsis} |

717 | |

718 | \begin{tclcommanddescription} |

719 | This extension returns the difference of two integer |

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

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

722 | \end{tclcommanddescription} |

723 | |

724 | \begin{tclcommandsampleinvocations} |

725 | \begin{scriptsize} |

726 | \begin{verbatim} |

727 | % arbint intsub 123846129436219 1e25 |

728 | -9999999999876153870563781 |

729 | \end{verbatim} |

730 | \end{scriptsize} |

731 | \end{tclcommandsampleinvocations} |

732 | |

733 | \begin{tclcommandseealso} |

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

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

736 | \end{tclcommandseealso} |

737 | |

738 | |

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

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

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

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

743 | %Subsection Tag: mul0 |

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

745 | |

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

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

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

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

750 | \end{tclcommandname} |

751 | |

752 | \begin{tclcommandsynopsis} |

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

754 | \end{tclcommandsynopsis} |

755 | |

756 | \begin{tclcommanddescription} |

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

758 | The result of this |

759 | extension will always be either a NAN tag |

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

761 | or an integer. |

762 | \end{tclcommanddescription} |

763 | |

764 | \begin{tclcommandsampleinvocations} |

765 | \begin{scriptsize} |

766 | \begin{verbatim} |

767 | % arbint intmul -329749813264962165493214963541976325 4.36463214521843123e38 |

768 | -143923663485602892702423181098245942606484617030062975000000000000000000000 |

769 | \end{verbatim} |

770 | \end{scriptsize} |

771 | \end{tclcommandsampleinvocations} |

772 | |

773 | \begin{tclcommandseealso} |

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

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

776 | \end{tclcommandseealso} |

777 | |

778 | |

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

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

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

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

783 | %Subsection Tag: div0 |

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

785 | |

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

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

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

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

790 | \end{tclcommandname} |

791 | |

792 | \begin{tclcommandsynopsis} |

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

794 | \end{tclcommandsynopsis} |

795 | |

796 | \begin{tclcommanddescription} |

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

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

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

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

801 | |

802 | \begin{equation} |

803 | sgn(dividend \cdot divisor) |

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

805 | \end{equation} |

806 | |

807 | or one of the NAN tags described in |

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

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

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

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

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

813 | \end{tclcommanddescription} |

814 | |

815 | \begin{tclcommandsampleinvocations} |

816 | \begin{scriptsize} |

817 | \begin{verbatim} |

818 | % arbint intdiv 2364832165653218648321543215848236458124 2854871354812543821 |

819 | 828349817467869034672 |

820 | % arbint intdiv 2364832165653218648321543215848236458124 0 |

821 | GMP_INTS_EF_INTOVF_POS |

822 | \end{verbatim} |

823 | \end{scriptsize} |

824 | \end{tclcommandsampleinvocations} |

825 | |

826 | \begin{tclcommandseealso} |

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

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

829 | \end{tclcommandseealso} |

830 | |

831 | |

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

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

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

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

836 | %Subsection Tag: mod0 |

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

838 | |

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

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

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

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

843 | \end{tclcommandname} |

844 | |

845 | \begin{tclcommandsynopsis} |

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

847 | \end{tclcommandsynopsis} |

848 | |

849 | \begin{tclcommanddescription} |

850 | This extension returns the remainder resulting from the |

851 | division of two integer arguments. |

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

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

854 | chosen so that the following relationship holds: |

855 | |

856 | \begin{equation} |

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

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

859 | \end{equation} |

860 | |

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

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

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

864 | returns one of the NAN tags described in |

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

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

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

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

869 | \end{tclcommanddescription} |

870 | |

871 | \begin{tclcommandsampleinvocations} |

872 | \begin{scriptsize} |

873 | \begin{verbatim} |

874 | % arbint intmod 264321654632432421 2175438321654 |

875 | 1547674828113 |

876 | % arbint intmod 264321654632432421 0 |

877 | GMP_INTS_EF_INTOVF_POS |

878 | \end{verbatim} |

879 | \end{scriptsize} |

880 | \end{tclcommandsampleinvocations} |

881 | |

882 | \begin{tclcommandseealso} |

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

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

885 | \end{tclcommandseealso} |

886 | |

887 | |

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

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

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

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

892 | %Subsection Tag: exp0 |

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

894 | |

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

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

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

898 | computes and returns as a string one integer |

899 | exponentiated to the power of another, |

900 | $base^{exponent}$. |

901 | |

902 | \end{tclcommandname} |

903 | |

904 | \begin{tclcommandsynopsis} |

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

906 | \end{tclcommandsynopsis} |

907 | |

908 | \begin{tclcommanddescription} |

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

910 | power. For |

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

912 | this is inconsistent with the mathematical definition. |

913 | All other exponentiations are as expected. |

914 | |

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

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

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

918 | \end{tclcommanddescription} |

919 | |

920 | \begin{tclcommandsampleinvocations} |

921 | \begin{scriptsize} |

922 | \begin{verbatim} |

923 | % arbint intexp 47 69 |

924 | 2370021018513446695324337468306899241173950476009917473665218657220346081293500 |

925 | 4143894985892600403244809901800125167 |

926 | % arbint intexp 1 0 |

927 | 1 |

928 | % arbint intexp 0 0 |

929 | 1 |

930 | % arbint intexp 0 1 |

931 | 0 |

932 | % arbint intexp 0 19237498 |

933 | 0 |

934 | % arbint intexp -47 69 |

935 | -237002101851344669532433746830689924117395047600991747366521865722034608129350 |

936 | 04143894985892600403244809901800125167 |

937 | % arbint intexp -47 -69 |

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

939 | % arbint intexp 193461926436214 99999999 |

940 | GMP_INTS_EF_INTOVF_TAINT_POS |

941 | \end{verbatim} |

942 | \end{scriptsize} |

943 | \end{tclcommandsampleinvocations} |

944 | |

945 | \begin{tclcommandseealso} |

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

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

948 | \end{tclcommandseealso} |

949 | |

950 | |

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

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

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

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

955 | %Subsection Tag: fac0 |

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

957 | |

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

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

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

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

962 | the integer argument supplied. |

963 | \end{tclcommandname} |

964 | |

965 | \begin{tclcommandsynopsis} |

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

967 | \end{tclcommandsynopsis} |

968 | |

969 | \begin{tclcommanddescription} |

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

971 | Any of the symbolic NAN strings described in |

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

973 | value of an appropriate symbolic NAN string. |

974 | Strings that cannot be parsed as integers or |

975 | NAN strings, strings |

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

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

978 | an error. |

979 | |

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

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

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

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

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

985 | enhancements are made. |

986 | \end{tclcommanddescription} |

987 | |

988 | \begin{tclcommandsampleinvocations} |

989 | \begin{scriptsize} |

990 | \begin{verbatim} |

991 | % arbint intfac 129 |

992 | 4974504222477287440390234150412680963965661113713884314596886402265216893219635 |

993 | 5119328515747917449637889876686464600208839390308261862352651828829226610077151 |

994 | 044469167497022952331930501120000000000000000000000000000000 |

995 | \end{verbatim} |

996 | \end{scriptsize} |

997 | \end{tclcommandsampleinvocations} |

998 | |

999 | \begin{tclcommandseealso} |

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

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

1002 | \end{tclcommandseealso} |

1003 | |

1004 | |

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

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

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

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

1009 | %Subsection Tag: gcd0 |

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

1011 | |

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

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

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

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

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

1017 | \end{tclcommandname} |

1018 | |

1019 | \begin{tclcommandsynopsis} |

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

1021 | \end{tclcommandsynopsis} |

1022 | |

1023 | \begin{tclcommanddescription} |

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

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

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

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

1028 | extension will always be either a NAN tag |

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

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

1031 | |

1032 | The algorithm employed is the |

1033 | \emph{Modern Euclidian Algorithm} as |

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

1035 | Although faster algorithms for computer |

1036 | implementation do exist, this is the simplest |

1037 | and most direct algorithm. |

1038 | \end{tclcommanddescription} |

1039 | |

1040 | \begin{tclcommandsampleinvocations} |

1041 | \begin{scriptsize} |

1042 | \begin{verbatim} |

1043 | % arbint intgcd 263130836933693530167218012160000000 503580 |

1044 | 4620 |

1045 | \end{verbatim} |

1046 | \end{scriptsize} |

1047 | \end{tclcommandsampleinvocations} |

1048 | |

1049 | \begin{tclcommandseealso} |

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

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

1052 | \end{tclcommandseealso} |

1053 | |

1054 | |

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

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

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

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

1059 | %Subsection Tag: lcm0 |

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

1061 | |

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

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

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

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

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

1067 | \end{tclcommandname} |

1068 | |

1069 | \begin{tclcommandsynopsis} |

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

1071 | \end{tclcommandsynopsis} |

1072 | |

1073 | \begin{tclcommanddescription} |

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

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

1076 | were 1. If either |

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

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

1079 | extension will always be either a NAN tag |

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

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

1082 | |

1083 | The algorithm employed is to calculate |

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

1085 | \emph{Modern Euclidian Algorithm} as |

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

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

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

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

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

1091 | |

1092 | \begin{equation} |

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

1094 | \end{equation} |

1095 | |

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

1097 | \end{tclcommanddescription} |

1098 | |

1099 | \begin{tclcommandsampleinvocations} |

1100 | \begin{scriptsize} |

1101 | \begin{verbatim} |

1102 | % arbint intlcm 64 100 |

1103 | 1600 |

1104 | \end{verbatim} |

1105 | \end{scriptsize} |

1106 | \end{tclcommandsampleinvocations} |

1107 | |

1108 | \begin{tclcommandseealso} |

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

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

1111 | \end{tclcommandseealso} |

1112 | |

1113 | |

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

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

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

1117 | \section{Rational Number Extensions} |

1118 | %Section Tag: RNE0 |

1119 | |

1120 | This section describes extensions that implement |

1121 | rational number arithmetic. |

1122 | |

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

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

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

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

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

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

1129 | for another extension. |

1130 | |

1131 | |

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

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

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

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

1136 | %Subsection Tag: RNR0 |

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

1138 | |

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

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

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

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

1143 | \end{tclcommandname} |

1144 | |

1145 | \begin{tclcommandsynopsis} |

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

1147 | \end{tclcommandsynopsis} |

1148 | |

1149 | \begin{tclcommanddescription} |

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

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

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

1153 | |

1154 | \begin{enumerate} |

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

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

1157 | representation of zero. |

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

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

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

1161 | \item Rational numbers which are effectively positive |

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

1163 | denominator. |

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

1165 | normalized to have a negative numerator and positive |

1166 | denominator. |

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

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

1169 | made coprime. |

1170 | \end{enumerate} |

1171 | |

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

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

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

1175 | 1/0. |

1176 | \end{tclcommanddescription} |

1177 | |

1178 | \begin{tclcommandsampleinvocations} |

1179 | \begin{scriptsize} |

1180 | \begin{verbatim} |

1181 | % arbint rnred 422.414 |

1182 | 211207/500 |

1183 | \end{verbatim} |

1184 | \end{scriptsize} |

1185 | \end{tclcommandsampleinvocations} |

1186 | |

1187 | \begin{tclcommandseealso} |

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

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

1190 | \end{tclcommandseealso} |

1191 | |

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

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

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

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

1196 | %Subsection Tag: RAD0 |

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

1198 | |

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

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

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

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

1203 | \end{tclcommandname} |

1204 | |

1205 | \begin{tclcommandsynopsis} |

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

1207 | \end{tclcommandsynopsis} |

1208 | |

1209 | \begin{tclcommanddescription} |

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

1211 | normalized rational result. |

1212 | |

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

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

1215 | \end{tclcommanddescription} |

1216 | |

1217 | \begin{tclcommandsampleinvocations} |

1218 | \begin{scriptsize} |

1219 | \begin{verbatim} |

1220 | % arbint rnadd 3.1415 64/259 |

1221 | 1755297/518000 |

1222 | \end{verbatim} |

1223 | \end{scriptsize} |

1224 | \end{tclcommandsampleinvocations} |

1225 | |

1226 | \begin{tclcommandseealso} |

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

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

1229 | \end{tclcommandseealso} |

1230 | |

1231 | |

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

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

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

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

1236 | %Subsection Tag: RSB0 |

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

1238 | |

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

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

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

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

1243 | \end{tclcommandname} |

1244 | |

1245 | \begin{tclcommandsynopsis} |

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

1247 | \end{tclcommandsynopsis} |

1248 | |

1249 | \begin{tclcommanddescription} |

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

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

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

1253 | |

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

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

1256 | \end{tclcommanddescription} |

1257 | |

1258 | \begin{tclcommandsampleinvocations} |

1259 | \begin{scriptsize} |

1260 | \begin{verbatim} |

1261 | % arbint rnsub 3.129 122/451 |

1262 | 1289179/451000 |

1263 | \end{verbatim} |

1264 | \end{scriptsize} |

1265 | \end{tclcommandsampleinvocations} |

1266 | |

1267 | \begin{tclcommandseealso} |

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

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

1270 | \end{tclcommandseealso} |

1271 | |

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

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

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

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

1276 | %Subsection Tag: RMU0 |

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

1278 | |

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

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

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

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

1283 | \end{tclcommandname} |

1284 | |

1285 | \begin{tclcommandsynopsis} |

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

1287 | \end{tclcommandsynopsis} |

1288 | |

1289 | \begin{tclcommanddescription} |

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

1291 | normalized rational result. |

1292 | |

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

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

1295 | \end{tclcommanddescription} |

1296 | |

1297 | \begin{tclcommandsampleinvocations} |

1298 | \begin{scriptsize} |

1299 | \begin{verbatim} |

1300 | % arbint rnmul 3.14 32/491 |

1301 | 2512/12275 |

1302 | \end{verbatim} |

1303 | \end{scriptsize} |

1304 | \end{tclcommandsampleinvocations} |

1305 | |

1306 | \begin{tclcommandseealso} |

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

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

1309 | \end{tclcommandseealso} |

1310 | |

1311 | |

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

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

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

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

1316 | %Subsection Tag: RDV0 |

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

1318 | |

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

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

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

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

1323 | \end{tclcommandname} |

1324 | |

1325 | \begin{tclcommandsynopsis} |

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

1327 | \end{tclcommandsynopsis} |

1328 | |

1329 | \begin{tclcommanddescription} |

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

1331 | normalized rational result. |

1332 | |

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

1334 | if the divisor is zero, |

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

1336 | \end{tclcommanddescription} |

1337 | |

1338 | \begin{tclcommandsampleinvocations} |

1339 | \begin{scriptsize} |

1340 | \begin{verbatim} |

1341 | % arbint rndiv 3.14 32/491 |

1342 | 77087/1600 |

1343 | \end{verbatim} |

1344 | \end{scriptsize} |

1345 | \end{tclcommandsampleinvocations} |

1346 | |

1347 | \begin{tclcommandseealso} |

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

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

1350 | \end{tclcommandseealso} |

1351 | |

1352 | |

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

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

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

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

1357 | %Subsection Tag: RCM0 |

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

1359 | |

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

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

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

1363 | compares two rational numbers. |

1364 | \end{tclcommandname} |

1365 | |

1366 | \begin{tclcommandsynopsis} |

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

1368 | \end{tclcommandsynopsis} |

1369 | |

1370 | \begin{tclcommanddescription} |

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

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

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

1374 | |

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

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

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

1378 | |

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

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

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

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

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

1384 | continue. |

1385 | \end{tclcommanddescription} |

1386 | |

1387 | \begin{tclcommandsampleinvocations} |

1388 | \begin{scriptsize} |

1389 | \begin{verbatim} |

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

1391 | 1 |

1392 | \end{verbatim} |

1393 | \end{scriptsize} |

1394 | \end{tclcommandsampleinvocations} |

1395 | |

1396 | |

1397 | \begin{tclcommandseealso} |

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

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

1400 | function for arbitrary integers. |

1401 | \end{tclcommandseealso} |

1402 | |

1403 | |

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

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

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

1407 | \section{Number Theory Extensions} |

1408 | %Section Tag: NTH0 |

1409 | \label{cxtn0:snth0} |

1410 | |

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

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

1413 | category because of the relationship between continued fractions |

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

1415 | must process large integers are |

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

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

1418 | Tcl extensions.} |

1419 | |

1420 | |

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

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

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

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

1425 | %Subsection Tag: CFR0 |

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

1427 | |

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

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

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

1431 | calculates the partial quotients and convergents of |

1432 | a non-negative rational number. |

1433 | \end{tclcommandname} |

1434 | |

1435 | \begin{tclcommandsynopsis} |

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

1437 | \end{tclcommandsynopsis} |

1438 | |

1439 | \begin{tclcommanddescription} |

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

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

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

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

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

1445 | list and processed from a Tcl script. |

1446 | \end{tclcommanddescription} |

1447 | |

1448 | \begin{tclcommandsampleinvocations} |

1449 | \begin{scriptsize} |

1450 | \begin{verbatim} |

1451 | % arbint cfratnum 3.14 |

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

1453 | \end{verbatim} |

1454 | \end{scriptsize} |

1455 | |

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

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

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

1459 | \end{tclcommandsampleinvocations} |

1460 | |

1461 | \begin{tclcommandseealso} |

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

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

1464 | \end{tclcommandseealso} |

1465 | |

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

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

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

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

1470 | %Subsection Tag: BRA0 |

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

1472 | |

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

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

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

1476 | finds best rational approximations to a supplied rational |

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

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

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

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

1481 | \end{tclcommandname} |

1482 | |

1483 | \begin{tclcommandsynopsis} |

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

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

1486 | \end{tclcommandsynopsis} |

1487 | |

1488 | \begin{tclcommanddescription} |

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

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

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

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

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

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

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

1496 | magnitude (absolute value) is returned. |

1497 | |

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

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

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

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

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

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

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

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

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

1507 | |

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

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

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

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

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

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

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

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

1516 | is returned in the case of equality. |

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

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

1519 | |

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

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

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

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

1524 | is returned. |

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

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

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

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

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

1530 | |

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

1532 | rational number, as described above. |

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

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

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

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

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

1538 | $h_{MAX}/1$.} resulting |

1539 | in an odd number of rational numbers returned. If the rational number |

1540 | specified is not already in the series of interest, an even number of |

1541 | rational numbers will normally be returned. The rational |

1542 | numbers returned are prefixed with integer indices, which |

1543 | indicate their ordinal distance from the rational number to be approximated |

1544 | (see the invocation examples below). The index of 0 is reserved for |

1545 | the reduced form of the rational number specified, and and a rational number with |

1546 | this index will be in the output only if the rational number supplied was already |

1547 | in the series of interest. |

1548 | The rational numbers returned |

1549 | will be formatted as integer indices and slash-separated integers, separated |

1550 | by single spaces and arranged in ascending order.. |

1551 | If the number of rational numbers requested by this option exceeds |

1552 | the number available, the sequence will simply be truncated at |

1553 | $-h_{MAX}/1$ or $h_{MAX}/1$, as appropriate. Any request for more than |

1554 | 10,000 neighbors (on each side) will be clipped to 10,000. |

1555 | \end{tclcommanddescription} |

1556 | |

1557 | \begin{tclcommandsampleinvocations} |

1558 | \begin{scriptsize} |

1559 | \begin{verbatim} |

1560 | % arbint cfbrapab 1.6093 255 |

1561 | 346/215 |

1562 | % arbint cfbrapab 1.6093 255 255 |

1563 | 243/151 |

1564 | % arbint cfbrapab 1.6093 255 255 -neversmaller |

1565 | 103/64 |

1566 | % arbint cfbrapab 1.6093 255 255 -neverlarger |

1567 | 243/151 |

1568 | % arbint cfbrapab 1.6093 255 255 -n 20 |

1569 | -20 143/89 -19 188/117 -18 233/145 -17 45/28 -16 217/135 -15 172/107 -14 127/79 |

1570 | -13 209/130 -12 82/51 -11 201/125 -10 119/74 -9 156/97 -8 193/120 -7 230/143 -6 |

1571 | 37/23 -5 251/156 -4 214/133 -3 177/110 -2 140/87 -1 243/151 1 103/64 2 169/105 |

1572 | 3 235/146 4 66/41 5 227/141 6 161/100 7 95/59 8 219/136 9 124/77 10 153/95 11 |

1573 | 182/113 12 211/131 13 240/149 14 29/18 15 253/157 16 224/139 17 195/121 18 |

1574 | 166/103 19 137/85 20 245/152 |

1575 | % arbint cfbrapab 1.6093 255 255 -succ |

1576 | 103/64 |

1577 | % arbint cfbrapab 1.6093 255 255 -pred |

1578 | 243/151 |

1579 | % arbint cfbrapab 2/3 255 255 -pred |

1580 | 169/254 |

1581 | \end{verbatim} |

1582 | \end{scriptsize} |

1583 | \end{tclcommandsampleinvocations} |

1584 | |

1585 | \begin{tclcommandseealso} |

1586 | This extension uses the continued fraction |

1587 | algorithms presented in Chapter \ccfrzeroxrefhyphen{}\ref{ccfr0}. |

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

1589 | Section \cdcmzeroxrefhyphen{}\ref{cdcm0:snth0:sbra0}. |

1590 | \end{tclcommandseealso} |

1591 | |

1592 | |

1593 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1594 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1595 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1596 | \subsection{The \texttt{arbint const} Extension} |

1597 | %Subsection Tag: CEX0 |

1598 | \label{cxtn0:snth0:scex0} |

1599 | |

1600 | \index{arbint const@\emph{arbint const}} |

1601 | \index{const (Tcl arbint sub-extension)@\emph{const} (Tcl \emph{arbint} sub-extension)} |

1602 | \begin{tclcommandname}{arbint const}% |

1603 | returns a string representing the value of important |

1604 | mathematical and conversion constants (such as the value |

1605 | of $\pi$ or $e$, or the conversion factor from miles to kilometers). |

1606 | \end{tclcommandname} |

1607 | |

1608 | \begin{tclcommandsynopsis} |

1609 | \tclcommandsynopsisline{arbint const}{const\_tag} |

1610 | \tclcommandsynopsisline{arbint const}{const\_tag uint32\_ndigits} |

1611 | \end{tclcommandsynopsis} |

1612 | |

1613 | \begin{tclcommanddescription} |

1614 | The \emph{const} subextension returns the value (as a string) of |

1615 | constants that may be useful in engineering work. Such constants |

1616 | may include mathematically significant numbers (such as |

1617 | \index{pi@$\pi$ (transcendental constant)}$\pi$ or |

1618 | \index{e@$e$ (transcendental constant)}$e$), or |

1619 | useful conversion factors (the conversion factor from |

1620 | miles to kilometers, for example). These string constants |

1621 | can be used in calculations involving rational numbers. |

1622 | |

1623 | All constants are simply tabulated as character strings |

1624 | within the `C' source code. |

1625 | |

1626 | Mathematically significant numbers (which, to the best |

1627 | of the author's knowledge are always irrational and |

1628 | usually transcendental, as mathematicians |

1629 | don't seem to have any lasting interest in specific integers |

1630 | or rational numbers) are available to about 1,000 significant digits, |

1631 | and have been obtained from various web pages. It is reasoned that |

1632 | 1,000 significant digits should be adequate for engineering applications. |

1633 | |

1634 | Measurement unit conversion constants have typically been obtained from |

1635 | \emph{NIST Special Publication 811} \cite{bibref:b:nistsp811:1995ed}. |

1636 | These constants are always tabulated with their full precision, since |

1637 | no physical constant can be precise to more than several decimal places. |

1638 | |

1639 | If the number of significant figures is not specified, |

1640 | each constant is returned as a string with a default number of |

1641 | decimal places (typically about 30). In most cases, the default |

1642 | number of decimal places provides more than enough precision for |

1643 | engineering work. However, an optional parameter allows more |

1644 | or fewer digits to be obtained, up to the maximum number tabulated internally |

1645 | in the software. The default number of decimal places is a compromise |

1646 | between calculation speed and accuracy. It is felt in most cases that |

1647 | the default number of decimal places provides excellent accuracy |

1648 | and good calculation speed. |

1649 | |

1650 | Please e-mail the authors if you would like additional useful |

1651 | constants included. Because the list of tabulated constants |

1652 | may grow and shrink, it would not be a sound decision to document |

1653 | the constants which are included here. Instead, use |

1654 | \emph{arbint const} with an invalid tag, and the software itself |

1655 | will list all of the internally tabulated constants and their |

1656 | significance. |

1657 | \end{tclcommanddescription} |

1658 | |

1659 | \begin{tclcommandsampleinvocations} |

1660 | Please note that the sample invocation below was created using |

1661 | v1.05 of the tool set. The list of constants may have grown |

1662 | since this example was created. Please poll the software directly |

1663 | by using \emph{arbint const} with an invalid tag to obtain the |

1664 | list of constants and their significance. |

1665 | \begin{scriptsize} |

1666 | \begin{verbatim} |

1667 | % arbint const xxx |

1668 | arbint const: "xxx" is not a recognized constant. |

1669 | Available constants are: |

1670 | e (1000 digits available) |

1671 | Historically significant transcendental constant. Digits obtained |

1672 | from http://fermi.udw.ac.za/physics/e.html on 08/17/01. |

1673 | g_si (6 digits available) |

1674 | Gravitational acceleration in SI units, meters per second**2. |

1675 | Obtained from NIST Special Publication 811 on 08/17/01. |

1676 | in2m (3 digits available) |

1677 | Multiplicative conversion factor from inches to meters. |

1678 | Obtained from NIST Special Publication 811 on 08/17/01. |

1679 | mi2km (7 digits available) |

1680 | Multiplicative conversion factor from miles to kilometers. |

1681 | Obtained from NIST Special Publication 811 on 08/17/01. |

1682 | pi (1201 digits available) |

1683 | Transcendental constant supplying ratio of a circle's circumference |

1684 | to its diameter. Digits obtained from http://www.joyofpi.com/ |

1685 | pi.htm on 08/17/01. |

1686 | sqrt5 (1040 digits available) |

1687 | The square root of 5. Digits obtained from |

1688 | http://home.earthlink.net/~maryski/sqrt51000000.txt on 08/17/01. |

1689 | % arbint const pi |

1690 | 3.14159265358979323846264338327 |

1691 | % arbint const pi 100 |

1692 | 3.141592653589793238462643383279502884197169399375105820974944592307816406286208998628034825342117067 |

1693 | % arbint const pi 10 |

1694 | 3.141592653 |

1695 | % arbint cfbrapab [arbint const pi 100] 65535 65535 |

1696 | 65298/20785 |

1697 | \end{verbatim} |

1698 | \end{scriptsize} |

1699 | \end{tclcommandsampleinvocations} |

1700 | |

1701 | |

1702 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1703 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1704 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1705 | \section{Miscellaneous Extensions} |

1706 | |

1707 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1708 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1709 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1710 | \subsection{credits} |

1711 | |

1712 | \index{credits@\emph{credits}} |

1713 | \begin{tclcommandname}{credits}% |

1714 | returns information about authorship of software components. |

1715 | \end{tclcommandname} |

1716 | |

1717 | \begin{tclcommandsynopsis} |

1718 | \tclcommandsynopsisline{credits}{} |

1719 | \tclcommandsynopsisline{credits}{searchstring} |

1720 | \end{tclcommandsynopsis} |

1721 | |

1722 | \begin{tclcommanddescription} |

1723 | The \emph{credits} command returns a list of contributors to the tools, |

1724 | their area(s) of contribution, and e-mail addresses. The volume of |

1725 | information returned can be reduced by using an optional \emph{searchstring}. |

1726 | |

1727 | \tclcommanddescsynopsisline{credits}{} |

1728 | \begin{tclcommandinternaldescription} |

1729 | Returns the complete list of contributors to the tools and their area(s) of contribution. |

1730 | \end{tclcommandinternaldescription} |

1731 | |

1732 | \tclcommanddescsynopsisline{credits}{searchstring} |

1733 | \begin{tclcommandinternaldescription} |

1734 | Returns all credit records containing \emph{searchstring}. |

1735 | Most commonly, this option is used to search for information about a specific |

1736 | command by using the command name as the \emph{searchstring}, or about a |

1737 | specific individual by using a component of the individual's name as the |

1738 | \emph{searchstring}. |

1739 | |

1740 | \end{tclcommandinternaldescription} |

1741 | |

1742 | \end{tclcommanddescription} |

1743 | |

1744 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1745 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1746 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1747 | \noindent\begin{figure}[!b] |

1748 | \noindent\rule[-0.25in]{\textwidth}{1pt} |

1749 | \begin{tiny} |

1750 | \begin{verbatim} |

1751 | $HeadURL$ |

1752 | $Revision$ |

1753 | $Date$ |

1754 | $Author$ |

1755 | \end{verbatim} |

1756 | \end{tiny} |

1757 | \noindent\rule[0.25in]{\textwidth}{1pt} |

1758 | \end{figure} |

1759 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |

1760 | % |

1761 | %End of file C_XTN0.TEX |

Name | Value |
---|---|

svn:eol-style |
native |

svn:keywords |
Author Date Id Revision URL Header |

dashley@gmail.com | ViewVC Help |

Powered by ViewVC 1.1.25 |