Mercurial > hg > xemacs-beta

comparison man/lispref/numbers.texi @ 5739:a2912073be85

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Support bignums with MPIR. Add documentation on the bignum, ratio, and bigfloat implementations. See xemacs-patches message with ID <CAHCOHQkytZao7Uk9ggeo1HKKJtN1bqO054X2mPsGYyQFjbHrZA@mail.gmail.com> and following messages.
author Jerry James <james@xemacs.org>
date Wed, 19 Jun 2013 09:30:30 -0600
parents 378a34562cbe
children 9fae6227ede5
comparison
equal deleted inserted replaced
5738:f6af091ac654 5739:a2912073be85
318 libraries if they are available on your platform. ``Arbitrary'' 318 libraries if they are available on your platform. ``Arbitrary''
319 precision means precisely what it says. Your ability to work with large 319 precision means precisely what it says. Your ability to work with large
320 numbers is limited only by the amount of virtual memory (and time) you 320 numbers is limited only by the amount of virtual memory (and time) you
321 can throw at them. 321 can throw at them.
322 322
323 As of 09 April 2004, support for the GNU Multiple Precision 323 XEmacs supports the GNU Multiple Precision arithmetic library (GMP),
324 arithmetic library (GMP) is nearly complete, and support for the BSD 324 the Multiple Precision Integers and Rationals library (MPIR), and the
325 Multiple Precision arithmetic library (MP) is being debugged. To enable 325 BSD Multiple Precision arithmetic library (MP). To enable bignum
326 bignum support using GMP (respectively MP), invoke configure with your 326 support using GMP, MPIR, or MP, invoke configure with your usual options
327 usual options, and add @samp{--use-number-lib=gmp} (respectively 327 and add @samp{--use-number-lib=gmp}, @samp{--use-number-lib=mpir}, or
328 @samp{--use-number-lib=mp}). The default is to disable bignum support, 328 @samp{--use-number-lib=mp}, respectively. The default is to disable
329 but if you are using a script to automate the build process, it may be 329 bignum support, but if you are using a script to automate the build
330 convenient to explicitly disable support by @emph{appending} 330 process, it may be convenient to explicitly disable support by
331 @samp{--use-number-lib=no} to your invocation of configure. GMP has an 331 @emph{appending} @samp{--use-number-lib=no} to your invocation of
332 MP compatibility mode, but it is not recommended, as there remain poorly 332 configure. GMP has an MP compatibility mode, but it is not recommended,
333 understood bugs (even more so than for other vendors' versions of MP). 333 as there remain poorly understood bugs (even more so than for other
334 334 vendors' versions of MP).
335 With GMP, exact arithmetic with integers and ratios of arbitrary 335
336 precision and approximate (``floating point'') arithmetic of arbitrary 336 With GMP and MPIR, exact arithmetic with integers and ratios of
337 precision are implemented efficiently in the library. (Note that 337 arbitrary precision and approximate (``floating point'') arithmetic of
338 numerical implementations are quite delicate and sensitive to 338 arbitrary precision are implemented efficiently in the library. (Note
339 that numerical implementations are quite delicate and sensitive to
339 optimization. If the library was poorly optimized for your hardware, as 340 optimization. If the library was poorly optimized for your hardware, as
340 is often the case with Linux distributions for 80x86, you may achieve 341 is often the case with Linux distributions for 80x86, you may achieve
341 gains of @emph{several orders of magnitude} by rebuilding the MP 342 gains of @emph{several orders of magnitude} by rebuilding the MP
342 library. See @uref{http://www.swox.com/gmp/gmp-speed.html}.) The MP 343 library. See @uref{http://gmplib.org/gmpbench.html}.) The MP
343 implementation provides arbitrary precision integers. Ratios and arbitrary 344 implementation provides arbitrary precision integers. Ratios and
344 precision floats are not available with MP. 345 arbitrary precision floats are not available with MP.
345 346
346 If your code needs to run correctly whether or not the feature is 347 If your code needs to run correctly whether or not the feature is
347 provided, you may test for the features @code{bignum}, @code{ratio}, and 348 provided, you may test for the features @code{bignum}, @code{ratio}, and
348 @code{bigfloat}. 349 @code{bigfloat}.
349 350
361 Since floating point arithmetic is inherently imprecise, numbers are 362 Since floating point arithmetic is inherently imprecise, numbers are
362 implicitly coerced to bigfloats only if other operands in the expression 363 implicitly coerced to bigfloats only if other operands in the expression
363 are bigfloat, and bigfloats are only coerced to other numerical types by 364 are bigfloat, and bigfloats are only coerced to other numerical types by
364 explicit calls to the function @code{coerce}. 365 explicit calls to the function @code{coerce}.
365 366
366 Bignum support is incomplete. If you would like to help with bignum
367 support, especially on BSD MP, please subscribe to the
368 @uref{http://www.xemacs.org/Lists/#xemacs-beta, XEmacs Beta mailing
369 list}, and book up on @file{number-gmp.h} and @file{number-mp.h}. Jerry
370 has promised to write internals documentation eventually, but if your
371 skills run more to analysis and documentation than to writing new code,
372 feel free to fill in the gap!
373
374 @menu 367 @menu
375 * Bignum Basics:: Representation and range of integers. 368 * Bignum Basics:: Representation and range of integers.
376 * Ratio Basics:: Representation and range of rational numbers. 369 * Ratio Basics:: Representation and range of rational numbers.
377 * Bigfloat Basics:: Representation and range of floating point. 370 * Bigfloat Basics:: Representation and range of floating point.
378 * Canonicalization and Contagion:: Automatic coercion to other types. 371 * Canonicalization and Contagion:: Automatic coercion to other types.
383 @node Bignum Basics 376 @node Bignum Basics
384 @subsection Bignum Basics 377 @subsection Bignum Basics
385 378
386 In most cases, bignum support should be transparent to users and Lisp 379 In most cases, bignum support should be transparent to users and Lisp
387 programmers. A bignum-enabled XEmacs will automatically convert from 380 programmers. A bignum-enabled XEmacs will automatically convert from
388 fixnums to bignums and back in pure integer arithmetic, and for GNU MP, 381 fixnums to bignums and back in pure integer arithmetic, and for GMP and
389 from floats to bigfloats. (Bigfloats must be explicitly coerced to 382 MPIR, from floats to bigfloats. (Bigfloats must be explicitly coerced
390 other types, even if they are exactly representable by less precise 383 to other types, even if they are exactly representable by less precise
391 types.) The Lisp reader and printer have been enhanced to handle 384 types.) The Lisp reader and printer have been enhanced to handle
392 bignums, as have the mathematical functions. Rationals (fixnums, 385 bignums, as have the mathematical functions. Rationals (fixnums,
393 bignums, and ratios) are printed using the @samp{%d}, @samp{%o}, 386 bignums, and ratios) are printed using the @samp{%d}, @samp{%o},
394 @samp{%x}, and @samp{%u} format conversions. 387 @samp{%x}, and @samp{%u} format conversions.
395 388
396 389
397 @node Ratio Basics 390 @node Ratio Basics
398 @subsection Ratio Basics 391 @subsection Ratio Basics
399 392
400 Ratios, when available have the read syntax and print representation 393 Ratios, when available, have the read syntax and print representation
401 @samp{3/5}. Like other rationals (fixnums and bignums), they are 394 @samp{3/5}. Like other rationals (fixnums and bignums), they are
402 printed using the @samp{%d}, @samp{%o}, @samp{%x}, and @samp{%u} format 395 printed using the @samp{%d}, @samp{%o}, @samp{%x}, and @samp{%u} format
403 conversions. 396 conversions.
404 397
405 398
411 404
412 It is possible to make bigfloat the default floating point format by 405 It is possible to make bigfloat the default floating point format by
413 setting @code{default-float-precision} to a non-zero value. Precision 406 setting @code{default-float-precision} to a non-zero value. Precision
414 is given in bits, with a maximum precision of 407 is given in bits, with a maximum precision of
415 @code{bigfloat-maximum-precision}. 408 @code{bigfloat-maximum-precision}.
416 @c #### is this true? 409
417 Bigfloats are created automatically when a number with yes 410 @example
418 411 (let* ((float1 (string-to-number "9999999999999999.99999999999999999999"))
419 412 (default-float-precision 256)
413 (float2 (string-to-number "9999999999999999.99999999999999999999")))
414 (+ (if (bigfloatp float1) 1 0)
415 (if (bigfloatp float2) 2 0)))
416 @result{} 2
417 @end example
418
419 @example
420 (let* ((float1 (float 999999999999999999999999999999999999999999999999999999))
421 (default-float-precision 256)
422 (float2 (float 999999999999999999999999999999999999999999999999999999)))
423 (princ float1)
424 (terpri)
425 (princ float2)
426 (terpri))
427 @result{} 9.999999999999999e+53
428 9.99999999999999999999999999999999999999999999999999999E53
429 t
430 @end example
431
432 Explicit type coercion is also available, although then the precision of
433 the bigfloat is no greater than the source type.
434
435 @example
436 (coerce 999999999999999 'bigfloat)
437 @result{} 9.99999999999999E14
438 @end example
420 439
421 @node Canonicalization and Contagion 440 @node Canonicalization and Contagion
422 @subsection Canonicalization and Contagion 441 @subsection Canonicalization and Contagion
423 442
424 @dfn{Canonicalization} is a rule intended to enhance the time and space 443 @dfn{Canonicalization} is a rule intended to enhance the time and space