2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/ent.info
8 @node Enhanced Number Types, Internationalization, OpenSSL Support, Top
9 @chapter Enhanced Number Types (ENT)
12 @cindex enhanced number types
13 @cindex multi-precision numbers
14 @cindex BSD-MP numbers
17 @cindex MPC complex numbers
18 @cindex complex numbers
19 @cindex Gaussian numbers
20 @cindex Residue Class Rings
21 @cindex Residue Classes
30 Compiling SXEmacs with enhanced number type support not only brings
31 a full heap of new number types, but also provides a more convenient
32 concept of numbers at all. This concept is mostly driven by
33 mathematical issues. Nonetheless we attempt to provide as much
34 backward compatibility as possible.
36 The purpose of enhanced number types is to propagate both a
37 convenient set of additional functionality which is (hopefully) widely
38 used in the future, and a consistent concept for dealing with
39 numeric computations from within emacs lisp.
41 The feature itself must be considered experimental, though. Howbeit
42 programmers can benefit from extremely increased performance, even
43 with the current implementation.
46 * ENT Basics:: Introduction to enhanced numbers.
47 * Types of Numbers:: How do C types reflect in elisp.
48 * Unions of Number Types:: Categories of numbers.
49 * Coercion:: Converting from on number type to
51 * Revised Arithmetics:: How ENT modifies arithmetics.
52 * Revised Formatting:: New output formatting features.
53 * Number Theoretic Functions:: Functions provided by ENT concerning
55 * Auxiliary Functions:: Functions that make use of ENT.
62 SXEmacs supports several of the available arithmetical and
63 mathematical libraries. Wherever possible, it is attempted to
64 introduce a transparency layer, such that one library can be exchanged
65 by another when both provide equal or similar functionality. This
66 layering allow emacs lisp and C programmers to minimise their efforts
67 by using a standardised interface.
69 On the other hand, it is attempted to additionally bring all
70 library-specific features into the emacs lisp environment. That way
71 emacs lisp (and also C) programmers can easily use certain functions
72 which are contained in only one specific library.
74 Some of the functionality provided by libraries is even
75 re-implemented in C in order to allow emacs lisp programmers to use
76 such functions even if the external library is not available. This
77 may sound a little obscure, but it is important to establish a
78 consistent and convenient concept of number types in the emacs lisp
79 environment once the enhanced number type support is enabled.
81 We start this section with a quick overview of what is available out
82 there, and what is additionally available due to re-implementation.
85 * GNU-MP:: The GNU multi-precision arithmetic
87 * BSD-MP:: The BSD multi-precision library.
88 * MPFR:: Multi-precision floats with correct.
89 rounding (based on GMP).
90 * MPC:: Multi-precision complex numbers with
91 correct rounding (based on MPFR).
92 * Pseudocomplex Numbers:: A native SXEmacs implementation of
93 complex numbers (based on MPF/MPFR).
94 * Pseudogaussian Numbers:: A native SXEmacs implementation of
95 Gaussian numbers (based on MPZ).
96 * Residue Class Rings:: A native SXEmacs implementation of
97 residue class rings (based on MPZ)
98 * Quaternions:: A native SXEmacs implementation of
99 the quaternionic division algebra.
100 * Octonions:: A native SXEmacs implementation of
101 the octonions division algebra.
102 * Algebraic Numbers:: A native SXEmacs implementation of
103 algebraic numbers (based on GMP).
104 * Modules/Lattices:: A native SXEmacs implementation of
105 lattices (Z-modules).
111 @subsection The GNU multi-precision arithmetic library (GMP)
113 The GMP library is the most widely used library of its kind, and
114 probably the most versatile and powerful library for high precision
115 arithmetic. Hence SXEmacs will extensively support this library in
116 its ENT system. Also, many other libraries and pseudo-implementations
117 are based on GMP. That is why it is probably worth fetching and
120 @cindex multi-precision arithmetic
121 @cindex arbitrary-precision arithmetic
122 The term @dfn{multi-precision arithmetic}, also called
123 @dfn{arbitrary-precision arithmetic}, is used to mean that the number
124 of digits of handled numbers is not limited in any way. Practically
125 of course it is limited by the amount of virtual memory and, more
126 often these days, by time.
128 GMP is distributed under the GNU LGPL and the library is available
129 at @url{http://swox.com/gmp}. Please refer also to their
130 documentation, and especially their instructions on how to install it.
132 The GMP library consists of roughly 4 parts, MPN, MPZ, MPQ, and
133 MPF. Only the latter three are intended for consumption.
136 MPN is sort of the spine of GMP and provides the actual
137 implementation of the multi-precision arithmetic. It is not further
138 interesting for SXEmacs since MPN functions are never accessed
142 MPZ is a higher level interface to arbitrary precision integer
143 arithmetic. The name is derived from the mathematical symbol for
144 integral numbers Z. We will also use the term @dfn{rational integers}
145 to refer to the mathematical concept of Z. In turn, historically Z is
146 derived from the German word ``Zahlen'' which stands for ``numbers''.
147 @cindex rational integers
150 MPQ is the interface to @dfn{rational numbers}. The name is derived
151 from the mathematical symbol for the rational field Q. Rational
152 numbers, also referred to as @dfn{fractions of integers} or
153 @dfn{quotients of integers}, or (if the meaning is clear) simply
154 @dfn{fractions} and @dfn{quotients} respectively. This nomenclature
155 already suggests how rationals can be represented, namely by two MPZ
156 integers written in the form @samp{a/b}. In such a representation we
157 call @samp{a} the @dfn{numerator} and @samp{b} the @dfn{denominator}
158 of @samp{a/b}. Internally, a fraction is always stored in its
159 canonical form, that is the @dfn{fraction is cancelled} as far as
160 possible, such that @samp{a} and @samp{b} are coprime. For reasons of
161 compatibility to XEmacs 21.5, we will also refer to fractions as
168 @cindex canonical form
169 @cindex cancelled fraction
172 MPF is an interface to multi-precision floats. They are implemented
173 like ordinary floats but are not limited to fixed number of mantissa
174 and exponent bits. These numbers may vary instead and is called the
175 @dfn{precision} of such a number. The precision in turn does not need
176 to be a multiple of 4 or 8 or something similar and is measured in
177 bits. In this sense, MPF numbers may be regarded as an approximation
178 for @dfn{real numbers}, see @ref{Unions of Number Types}.
182 @subsection The BSD multi-precision library
184 The BSD-MP library comes natively (as the name maybe suggests) with
185 BSD distributions. It is also widely, though mostly stealthily,
186 spread in form of the crypto library @file{libcrypto.so} of OpenSSL.
188 BSD-MP, like GMP, provides a form of arbitrary-precision rational
189 integers, called MINT. Both MPZ and MINT integers are transparently
190 unified within SXEmacs, which is why you can use only one
191 implementation at a time.
195 @subsection The MPFR library
197 MPFR is a portable library for arbitrary precision arithmetic on
198 floating-point numbers, based on the GMP library. It works similar to
199 the MPF module of GMP, however the main differences with MPF are:
203 the mpfr code is portable, i.e. the result of any operation does not
204 depend on the machine word size mp_bits_per_limb (32 or 64 on most
207 the precision in bits can be set exactly to any valid value for each
210 MPFR provides the four rounding modes from the IEEE 754-1985
214 In particular, with a precision of 53 bits, mpfr should be able to
215 exactly reproduce all computations with double-precision machine
216 floating-point numbers (double type in C). Furthermore, MPFR comes
217 with a heap of useful functions over the reals, like logarithms,
218 trigonometrical functions and so forth.
220 The MPFR library is released under the GNU LGPL and can be obtained
221 from @url{http://www.mpfr.org}. Please refer also to their
222 documentation, and especially their instructions on how to install it.
224 Especially note that we currently do @emph{only support the
225 standalone version of MPFR}, and not the one distributed with GMP.
229 @subsection The MPC library
231 MPC is a portable library written by Andreas Enge for
232 arbitrary-precision arithmetic on complex numbers. It is based on the
233 GMP and MPFR libraries.
235 The MPC library is released under the GNU LGPL and is available at
236 @url{http://www.lix.polytechnique.fr/Labo/Andreas.Enge/mpc/mpc.html}.
238 Unfortunately, as of November 2005, the build system of MPC is
239 extremely poor, hence we describe shortly how to install it. After
240 untarring the archive invoke @samp{make}. This will produce a
241 @file{libmpc.a}. Copy this file to your favourite @file{lib/}
242 directory, for example @file{/path/to/gmp/prefix/lib/} and make that
243 path known to SXEmacs via the @samp{--with-site-prefixes} switch when
244 configuring. Secondly, copy the file @file{mpc.h} to your favourite
245 @file{include/} directory, for example to
246 @file{/path/to/gmp/prefix/include/}. That's it!
248 @cindex complex numbers
249 The name MPC is probably derived from the mathematical symbol C for
250 the complex number field. Without further explanations, the
251 @dfn{complex numbers} are an algebraic extension of the real numbers,
252 indeed it is the only sensible extension. It turns out, that efforts
253 to find an algebraic closure of any number field end up in the complex
256 @cindex complex number
257 @cindex imaginary unit
259 @cindex imaginary part
260 Complex numbers have different representations, but one of the most
261 known is the representation as a tuple of reals (more formally as
262 vector space over R). The notation of a @dfn{complex number} for this
263 representation is @samp{(a,b)} or @samp{a+bi}, where @samp{a} and
264 @samp{b} are real numbers. The symbol @samp{i} denotes the
265 @dfn{imaginary unit}. In this representation, we refer to @samp{a} as
266 the @dfn{real part} and to @samp{b} as the @dfn{imaginary part} of
269 There are other representations of complex numbers which are not
270 implemented yet and hence will not be explained at this place.
273 @node Pseudocomplex Numbers
274 @subsection Pseudocomplex Numbers
276 Pseudocomplex numbers are the poor man's version of MPC. Its
277 implementation is based on MPFR which must be available therefore.
278 The representation of complex numbers follows the one used in MPC,
279 namely in the form @samp{a+bi}. Complex numbers are internally stored
280 by two independent MPFR floats.
282 Pseudocomplex numbers are gratis whenever MPFR is provided on a
283 system. They are contained and maintained within the SXEmacs source
284 distribution and hence inherit the licence of SXEmacs.
287 @node Pseudogaussian Numbers
288 @subsection Pseudogaussian Numbers
290 Pseudogaussian numbers are implemented like pseudocomplex numbers.
291 They are based on GMP-MPZ which must be available therefore.
293 Like pseudocomplex numbers, pseudogaussians are gratis whenever
294 GMP-MPZ is provided on a system. They are contained and maintained
295 within the SXEmacs source distribution and hence inherit the licence
298 The representation of Gaussian numbers within SXEmacs follows the
299 one usually used in algebra, namely as the ring of integers of Q+Qi.
300 Gaussian numbers may thusly be written like complex ones, @samp{a+bi},
301 where @samp{a} and @samp{b} are both rational integers.
304 @node Residue Class Rings
305 @subsection Residue Class Rings
307 Residue classes are a special form of partitioning the class of
308 rational integers into finitely many classes of congruent elements.
309 They are based on GMP-MPZ which must be available therefore.
311 Like pseudocomplex or pseudogaussian numbers residue class rings are
312 gratis whenever GMP-MPZ is provided on a system. The classes
313 themselves are represented additively and canonicalised, that is
314 @samp{c+mZ}, where @samp{c} and @samp{m} are both rational integers,
315 and canonically @samp{c} is in [0..m).
319 @subsection Quaternions
321 Quaternions are a special form of hypercomplex numbers. Currently,
322 we support the integer ring of the usual quaternion definition. That
323 way, quaternions form a special Z-module. They are based, however, on
324 the GMP-MPZ which must be available therefore.
326 Quaternions are represented additively by a set of basis vectors,
327 called 1, i, j, and k. These suffice the fundamental equation:
330 $i^2 = j^2 = k^2 = ijk = -1$
334 i^2 = j^2 = k^2 = ijk = -1
339 @subsection Octonions
341 Neither documented nor implemented yet.
344 @node Algebraic Numbers
345 @subsection Algebraic Numbers
347 Neither documented nor implemented yet.
350 @node Modules/Lattices
351 @subsection Modules and Lattices
353 Neither documented nor implemented yet.
357 @node Types of Numbers
358 @section Types of Numbers
360 For proper understanding, we are using the terms type and
361 category in the next sections. These terms are used (quite inclusive)
362 in the meaning of type and category theory in some sense. A
363 @dfn{category} is a class of elements related to each other by
364 fulfilling a common predicate. Then on the other hand the @dfn{type}
365 of an object is something like the strongest category an object may
368 The main difference between both terms is that in C an object must
369 have exactly one type, whereas it still can belong to other
370 categories. For example, having the integer @code{0} and the fraction
371 @code{0/1}, then both of these belong to the category @samp{zero}, but
372 it is quite obvious that nobody would expect them to be of type
376 * Type bigz:: The type @samp{bigz} (@samp{bignum}).
377 * Type bigq:: The type @samp{bigq} (@samp{ratio}).
378 * Type bigf:: The type @samp{bigf} (@samp{bigfloat}).
379 * Type bigfr:: The type @samp{bigfr}.
380 * Type bigc:: The type @samp{bigc}.
381 * Type bigg:: The type @samp{bigg}.
382 * Type indefinite:: The type @samp{indefinite}.
383 * Type residue-class-ring:: The Type @samp{residue-class-ring}.
384 * Type residue-class:: The Type @samp{residue-class}.
385 * Type quatern:: The Type @samp{quatern}.
390 @subsection The Type @samp{bigz}
392 The type @samp{bigz} is an abstract C type for arbitrary-precision
393 rational integers. Its actual library-specific implementation is
394 chosen at configure time, and can be either GMP-MPZ or BSD-MP. In the
395 former case the actual C type would be @samp{mpz_t}, in the latter
396 case it is @samp{MINT}.
398 Any other library which implements something similar to MPZ, should
399 be accessed via the abstract type @samp{bigz}, too.
401 Lisp objects can be tested for the type @samp{bigz} by the following
405 This predicate tests whether its argument is a big integer (as
406 provided by GMP-MPZ or BSD-MP), and returns @code{t} if so, @code{nil}
410 @defun bignump object
411 This is roughly the same as @code{bigzp} and is provided for
412 compatibility to XEmacs.
415 The read syntax (and print syntax) of rational integers is the same
416 as for ordinary emacs integers. If the mantissa is not sufficient to
417 regard an integer as fixnum, that integer is automatically treated as
418 @samp{bigz} integer and created as such.
420 There are no other forms of creation, especially there are no
421 constructors for @samp{bigz} objects.
423 Although named `arbitrary'-precision integers there is no way to
424 take influence on the precision or internal representation of
425 @samp{bigz}s (unlike the float types). The number of limbs used, read
426 the precision, is administered solely by the underlying library
431 @subsection The Type @samp{bigq}
433 The type @samp{bigq} is an abstract C type for arbitrary-precision
434 rational numbers (fractions). The actual C type provided by the
435 GMP-MPQ library is @samp{mpq_t}.
437 Any other library which implements something similar to MPQ, should
438 be accessed via the abstract type @samp{bigq}, too.
440 Lisp objects can be tested for the type @samp{bigq} by the following
444 This predicate tests whether its argument is a fraction of integers
445 (as provided by GMP-MPQ), and returns @code{t} if so, @code{nil}
450 This is roughly the same as @code{bigqp} and is provided for
451 compatibility to XEmacs.
454 Furthermore, for @samp{bigq} objects exist two accessor functions,
455 namely @code{numerator} and @code{denominator} to access the
456 respective parts of a fraction.
458 @defun numerator rational
459 Return the numerator of the canonical form of @var{rational}.
460 If @var{rational} is an integer, @var{rational} is returned.
463 @defun denominator rational
464 Return the denominator of the canonical form of @var{rational}.
465 If @var{rational} is an integer, 1 is returned.
468 The read syntax of rational quotients is the intuitive one, and
469 identical to their output syntax if the quotients are not integral
470 (i.e. have denominator 1). The lisp reader interprets
471 @samp{@var{a}/@var{b}} with @var{a} a rational integer and @var{b} a
472 positive integer as the quotient @samp{a/b}.
474 Within the lisp reader quotients are automatically cancelled and
475 stored in their canonical form (@var{a} coprime to @var{b}), consider
476 the following examples:
487 Please note that the result in the latter example is @emph{not} of
488 type @samp{bigq} because auto-coercion is in effect (see the notes in
489 @ref{Category integer}) which canonicalises rational fractions with
490 denominator 1 to rational integers.
492 Also note that the read syntax for quotients steals a whole class of
493 possible symbol identifiers. In a non-ENT-SXEmacs @var{1/3} is a
494 valid name for a variable.
496 Beside the creation of rational quotients, the arithmetic operation
497 @code{//} can also be used to construct quotients. This function is
498 not exclusively a @samp{bigq}-constructor, but passing two integral
499 arguments (interpretable as numerator and denominator) will yield a
507 Again, in spite of their name arbitrary-precision quotients do not
508 offer a way to take influence on the precision or internal
509 representation of @samp{bigq}s (unlike the float types). The number
510 of limbs used, read the precision, is administered solely by the
511 underlying library implementation.
515 @subsection The Type @samp{bigf}
517 The type @samp{bigf} is an abstract C type for arbitrary-precision
518 real number approximations (so called floats). The actual C type
519 provided by the GMP-MPF library is @samp{mpf_t}.
521 Any other library which implements something similar to MPF, should
522 be accessed via the abstract type @samp{bigf}, too.
524 Lisp objects can be tested for the type @samp{bigq} by the following
528 This predicate tests whether its argument is a MP-float (as provided
529 by GMP-MPF), and returns @code{t} if so, @code{nil} otherwise.
532 @defun bigfloatp object
533 This is roughly the same as @code{bigfp} and is provided for
534 compatibility to XEmacs.
537 The read syntax (and print syntax) of @samp{bigf}s is the same as
538 for emacs floats. The interpretation in the lisp reader depends on
539 the variable @var{read-real-as} (see @ref{Category real}).
541 There are no other forms of creation, especially there are no
542 constructors for @samp{bigf} objects.
544 As the name arbitrary-precision suggested, numbers of type
545 @samp{bigf} can be assigned a precision. This precision can be
546 queried and even may be changed at any time.
548 @defun bigf-get-precision number
549 Return the precision of @var{number} as an integer.
552 @defun bigf-set-precision number precision
553 Set the precision of @var{number} to @var{precision}, a nonnegative
555 The new precision of @var{number} is returned.
557 Note that the return value may differ from @var{precision} if the
558 underlying library is unable to support exactly @var{precision} bits
560 Note also, that setting the precision is @emph{lossy}, that means
561 @var{number} after setting the precision is not necessarily the same
562 as the original @var{number}.
567 @subsection The Type @samp{bigfr}
569 The type @samp{bigfr} is an abstract C type for arbitrary-precision
570 real number approximations with correct rounding facilities (so called
571 floats). The actual C type is provided by the MPFR library and is
572 called @samp{mpfr_t}.
574 Any other library which implements something similar to MPFR, should
575 be accessed via the abstract type @samp{bigfr}, too.
577 We have chosen to not regard MPFR and GMP-MPF as equivalent. MPFR
578 provides a lot more behind the scenes.
580 Lisp objects can be tested for the type @samp{bigfr} by the
584 This predicate tests whether its argument is a MP-float (as provided
585 by MPFR), and returns @code{t} if so, @code{nil} otherwise.
588 The read syntax (and print syntax) of @samp{bigfr}s is the same as
589 for emacs floats. The interpretation in the lisp reader depends on
590 the variable @var{read-real-as} (see @ref{Category real}).
592 There are no other forms of creation, especially there are no
593 constructors for @samp{bigfr} objects.
595 As required by MPFR, SXEmacs supports indefinite number values which
596 can occur as return values of some MPFR functions. Such number
597 objects, however, are @emph{not} of type @samp{bigfr} anymore. We
598 provide a more general handling for these, see @ref{Type indefinite}
599 for more information.
601 Again, numbers of type @samp{bigfr} can be assigned a precision.
602 This precision can be queried and even may be changed at any time.
604 @defun bigfr-get-precision number
605 Return the precision of @var{number} as an integer.
608 @defun bigfr-set-precision number precision
609 Set the precision of @var{number} to @var{precision}, a nonnegative
611 The new precision of @var{number} is returned.
613 Note that the return value may differ from @var{precision} if the
614 underlying library is unable to support exactly @var{precision} bits
616 Note also, that setting the precision is @emph{lossy}, that means
617 @var{number} after setting the precision is not necessarily the same
618 as the original @var{number}.
623 @subsection The Type @samp{bigc}
625 The type @samp{bigc} is an abstract C type for arbitrary-precision
626 complex number approximations with correct rounding facilities. The
627 actual C type is provided either by the MPC library (@samp{mpc_t}) or
628 by the SXEmacs pseudo imlementation based on MPFR.
630 Any other library which implements something similar to MPC, should
631 be accessed via the abstract type @samp{bigc}, too.
633 Lisp objects can be tested for the type @samp{bigc} by the following
637 This predicate tests whether its argument is a complex number (as
638 provided by MPC or the SXEmacs pseudo-implementation), and returns
639 @code{t} if so, @code{nil} otherwise.
642 For @samp{bigc} objects exist two accessor functions, namely
643 @code{real-part} and @code{imaginary-part} to access the respective
644 parts of a complex number.
646 @defun real-part number
647 Return the real part of @var{number}.
650 @defun imaginary-part number
651 Return the imaginary part of @var{number}.
652 If @var{number} is a comparable, 0 is returned.
655 The read syntax of @samp{bigc}s is inspired by the notation of
656 elements of algebraic adjunctions. In these terms the lisp reader
657 interprets @var{a}+@var{b}i as @samp{bigc} whenever both @var{a} and
658 @var{b} are written in float syntax, alternatively it is allowed to
659 capitalise the imaginary symbol. If the imaginary part of a
660 @samp{bigc} is one, it is additionally allowed to omit @var{b}.
661 Consider the examples:
665 @result{} 2.000000+3.000000i
667 @result{} 2.000000+3.000000i
669 @result{} 3.000000+1.000000i
672 Note that the read syntax for complex numbers steals a whole class
673 of possible symbol identifiers. In a non-ENT-SXEmacs @var{2.0+3.0i}
674 is a valid name for a variable.
676 There is also the possibility to create @samp{bigc} objects with a
677 constructor, passing a real and an imaginary part to it. Both real
678 and imaginary part may be of any comparable number type, in this
679 case. In a certain sense, this is the inverse function of the
680 selector functions above.
682 @defun make-bigc real-part imaginary-part
683 Return the bigc number whose real component is @var{real-part} and
684 whose imaginary component is @var{imaginary-part}.
689 @result{} 1.000000+2.000000i
691 @result{} 0.500000+1.500000i
694 Again, numbers of type @samp{bigc} can be assigned a precision.
695 This precision can be queried and changed at any time.
697 @defun bigc-get-precision number
698 Return the precision of @var{number} as an integer.
701 @defun bigc-set-precision number precision
702 Set the precision of @var{number} to @var{precision}, a nonnegative
704 The new precision of @var{number} is returned.
706 Note that the return value may differ from @var{precision} if the
707 underlying library is unable to support exactly @var{precision} bits
709 Note also, that setting the precision is @emph{lossy}, that means
710 @var{number} after setting the precision is not necessarily the same
711 as the original @var{number}.
714 The precision always affects both, the real and the imaginary part.
715 Although supported by the underlying library, SXEmacs will not handle
716 selective precision assignment.
720 @subsection The Type @samp{bigg}
722 As of November 2005, there is no library dedicated to Gaussian
723 numbers available. Thusly, the abstract C type @samp{bigg} is
724 implemented only via the SXEmacs pseudo implementation based on
725 GMP-MPZ. Gaussian numbers are represented by two MPZ objects.
727 Nonetheless, any library which implements Gaussian numbers should be
728 accessed via the abstract type @samp{bigg} in the future.
730 Lisp objects can be tested for the type @samp{bigg} by the following
734 This predicate tests whether its argument is a Gaussian number (as
735 provided by the SXEmacs pseudo-implementation), and returns @code{t}
736 if so, @code{nil} otherwise.
739 For @samp{bigg} objects exist the same accessor functions as for
740 @samp{bigc} objects, @code{real-part} and @code{imaginary-part} to
741 access the respective parts of a Gaussian number. Hereby,
742 @code{real-part} returns the integral rational part.
744 The read syntax of @samp{bigg}s is inspired by the traditional
745 notation of the elements of a Gaussian lattice. In these terms the
746 lisp reader interprets @var{a}+@var{b}i as @samp{bigg} whenever both
747 @var{a} and @var{b} are written in integer syntax, alternatively it is
748 allowed to capitalise the imaginary symbol. If the imaginary part of
749 a @samp{bigg} is one, it is additionally allowed to omit @var{b}.
750 Consider the examples:
761 And similar to @samp{bigc} complex numbers, there is a constructor
762 which composes a Gaussian number from a given integral rational and
763 a given imaginary component.
765 @defun make-bigg real-part imaginary-part
766 Return the bigg number whose rational component is @var{real-part} and
767 whose imaginary component is @var{imaginary-part}.
771 @node Type indefinite
772 @subsection The Type @samp{indefinite}
774 In order to handle indefinite number values, SXEmacs provides an
775 abstract type to gather these and sophisticated means to handle them.
776 Indefinites are treated like ordinary numbers. They take part in
777 arithmetic and can be used for many mathematical functions.
779 Howbeit, indefinites cannot be explicitly generated because there
780 merely finitely many. Hence there are variables which refer to the
781 indefinites, their print syntax is identical to their symbol name.
785 A symbol representing positive infinity.
790 A symbol representing negative infinity.
793 @vindex complex-infinity
794 @defvar complex-infinity
795 A symbol representing the infinitely distant point in the complex
801 A symbol representing a not-a-number (NaN) value.
804 The big difference to other number objects is that indefinites may
805 shadow another other number types. This makes them more a category
806 than actually a number type of its own. Due to efficiency reasons and
807 cleaner coding we have chosen to assign them their own type and
808 allowed them to behave as another number type. That is SXEmacs does
809 not distinguish between the positively infinite point of the rational
810 integers and the positively infinite point of the reals.
812 On the other hand (and as typically seen in mathematics), the
813 infinities are not part of the class of numbers of a certain type,
814 therefore the type predicates of other number types will always yield
815 @code{nil}. That means the programmer must track the history of
816 computations to find out which element or term spawned the occurrence
817 of indefinites (if that information is valuable of course).
820 As usual for number types indefinites have their own predicate
822 @defun indefinitep object
823 Return @code{t} if @var{object} is an indefinite symbol, @code{nil}
827 Infinities, a subset of the indefinites, can be type-checked
830 @defun infinityp object
831 Return @code{t} if @var{object} is a form of infinity, @code{nil}
835 Note also, the indefinite @code{not-a-number} is indeed not a
836 number, thence the category predicate @code{numberp} will return
837 @code{nil} for @code{not-a-number} (see @ref{Category number}).
840 @node Type residue-class-ring
841 @subsection The Type @samp{residue-class-ring}
843 The type @samp{residue-class-ring} is a super-type for all possible
844 residue class rings, which in turn are the worlds (actually the types)
845 of residue classes. To progressively meet the actual need for
846 infinitely many types, we instead gather them into this super-type.
847 The underlying C-type is @samp{resc_rng}.
849 Lisp objects can be tested for the type @samp{residue-class-ring} by
850 the following predicate.
852 @defun residue-class-ring-p object
853 Return @code{t} if @var{object} is a residue class ring, @code{nil}
857 The read syntax of @samp{residue-class-ring}s is inspired by the
858 traditional algebra, hence the lisp reader interprets
859 @code{Z/@var{m}Z} as @samp{residue-class-ring} whenever @var{m} is a
860 rational integer. We call @var{m} the modulus of the residue class
863 Of course, there exists a constructor to derive a residue class ring
864 from a given modulus:
866 @defun make-residue-class-ring modulus
867 Return a residue class ring of size @var{modulus} (>= 2).
873 (make-residue-class-ring 24)
878 The converse is possible via the accessor function
879 @code{residue-class-modulus}, too. See next section for a detailed
883 @node Type residue-class
884 @subsection The Type @samp{residue-class-ring}
886 The type @samp{residue-class} is actually a world of worlds where
887 residue class ring elements may live. Their actual ``type'' is the
888 residue class ring where the element is contained. Therefore
889 (higher-ary) operations over residue classes @emph{must} always
890 perform two type checks, firstly whether an object lives in the world
891 of worlds of residue classes, and secondly whether all of the residue
892 classes are contained in the same ring.
893 The underlying C-type is @samp{resc_elm}.
895 Lisp objects can be tested for the type @samp{residue-class} by the
898 @defun residue-class-p object
899 Return @code{t} if @var{object} is a residue class, @code{nil}
903 For @samp{residue-class} objects exists an accessor function to
904 obtain the ring in which a certain residue class is contained.
906 @defun residue-class-ring resclass
907 Return the parental residue class ring (the world) of @var{resclass}.
910 The read syntax of @samp{residue-class}es is inspired by the
911 traditional algebra, hence the lisp reader interprets
912 @code{@var{c}+@var{m}Z} as @samp{residue-class} whenever both @var{c}
913 and @var{m} are rational integers, and @var{m} is positive. We
914 call @var{c} a representant of the residue class.
916 Of course, there exists a constructor to derive a residue class
917 from a given representant:
919 @defun make-residue-class element ring
920 Return the residue class of @var{element} in @var{ring}.
922 This is a lift of the integer @var{element} into one of the classes of
927 Note that arbitrary class members of a residue class are mapped to one
928 canonical representant.
934 (make-residue-class 2 Z/9Z)
939 ;; a canonicalisation
945 To regain the representant's integer value there is an accessor
946 function @code{residue-class-representant}:
948 @defun residue-class-representant element
949 Return the representant of the residue class @var{element} lifted to
950 the ring of rational integers.
954 Similarly there is an accessor for the modulus:
956 @defun residue-class-modulus ring-or-element
957 Return the modulus of the residue class ring @var{ring-or-element},
958 or the modulus of a residue class, respectively.
963 (residue-class-representant 3+4Z)
965 (residue-class-representant 6+4Z)
970 (residue-class-modulus 3+4Z)
972 (residue-class-modulus Z/7Z)
979 @subsection The Type @samp{quatern}
981 The type @samp{quatern} is an abstract C type for integral elements
982 of the quaternion division algebra. The actual C type
983 (@samp{quatern}) is pseudo-implemented as a struct of 4 MP-integers,
984 which are based on either GMP-MPZ or BSD-MP.
986 Lisp objects can be tested for the type @samp{quatern} by the
989 @defun quaternp object
990 Return @code{t} if @var{object} is a quaternion, @code{nil}
994 The read syntax of @samp{quatern}s is similar to the read syntax for
995 complex numbers. The lisp reader interprets
996 @code{@var{a}+@var{b}i+@var{c}j+@var{d}k} as @samp{quatern} whenever
997 @var{a}, @var{b}, @var{c} and @var{d} are all rational integers. We
998 call @var{a} the z-part, @var{b} the i-part, @var{c} the j-part
999 and @var{d} the k-part of the quaternion.
1001 As for complex or gaussian numbers, there exists a constructor
1002 @code{make-quatern} which may be used to compose a quaternion by its
1005 @defun make-quatern z i j k
1006 Return the Quaternion whose z-component is @var{z},
1007 whose i-, j-, and k-components are @var{i}, @var{j} and @var{k},
1013 @result{} 2+4i+3j+1k
1015 @result{} 0-1i-1j-1k
1016 (make-quatern 2 1 2 0)
1017 @result{} 2+1i+2j+0k
1020 And again, the single linear factors of a quaternion are regainable
1021 by the accessor functions @code{quatern-z}, @code{quatern-i},
1022 @code{quatern-j} and @code{quatern-k}.
1024 @defun quatern-z quatern
1025 Return @var{quatern}'s z-component.
1028 @defun quatern-i quatern
1029 Return @var{quatern}'s i-component.
1032 @defun quatern-j quatern
1033 Return @var{quatern}'s j-component.
1036 @defun quatern-k quatern
1037 Return @var{quatern}'s k-component.
1041 (quatern-z 1+2i-3j-k)
1043 (quatern-i 1+2i-3j-k)
1045 (quatern-j 1+2i-3j-k)
1047 (quatern-k 1+2i-3j-k)
1053 @node Unions of Number Types
1054 @section Unions of Number Types
1055 @cindex unions of number types
1056 @cindex number categories
1057 @cindex categories of numbers
1059 Formally, we refer to numbers (and anything number-related) in the
1060 SXEmacs lisp environment by a category called @samp{number}. The
1061 category @samp{number} (deductively) consists of all SXEmacs lisp
1062 objects which can be used in the arithmetical functions @code{+} and
1063 @code{*}, and which possess a @dfn{canonical norm}, i.e. for which the
1064 function @code{canonical-norm} returns a value.
1066 Of course, in our deductive approach, we wish to fragment the
1067 category @samp{number} seamlessly into several subcategories. You can
1068 take for granted that this is possible. To not scare you completely
1069 off, we look at an inductive approach instead.
1071 The inductive approach attempts to start at something like the atoms
1072 of the enhanced number facilities, namely the C types. As discussed
1073 in the previous section, C types themselves are gathered and unified
1074 into an abstract C type, which is library independent. Now we try
1075 further unifications to get something like @emph{the} super-type,
1076 which we call a category, since its objects do not physically carry
1080 * Category integer:: Unifications of rational integers.
1081 * Category rational:: Unifications of rationals.
1083 * Category comparable::
1084 * Category nonnegative::
1085 * Category complex::
1086 * Category archimedean::
1087 * Category nonarchimedean::
1088 * Category algebraic::
1089 * Category transcendent::
1096 @node Category integer
1097 @subsection The category @samp{integer}
1099 The category of integers is probably the most transparent one. This
1100 is of course due to the fact, that SXEmacs did provide integers
1101 before. Now it would be unregrettably stupid, if we invented another
1102 read-syntax for the additional integers. Hence big integers are
1103 unified transparently with ordinary 28-bit integers. The subcategory
1104 of ordinary emacs integers is called @dfn{int} or @dfn{fixnum}.
1106 Nevertheless, we provide functions to distinguish them, and to
1107 coerce from the one type to the other.
1110 This predicate tests whether its argument is an ordinary emacs
1111 integer, and return @code{t} if so, @code{nil} otherwise.
1114 @defun fixnump object
1115 This is roughly the same as @code{intp} and is provided for
1116 compatibility to XEmacs.
1120 This predicate tests whether its argument is a big integer (as
1121 provided by GMP-MPZ or BSD-MP), and returns @code{t} if so, @code{nil}
1125 @defun bignump object
1126 This is roughly the same as @code{bigzp} and is provided for
1127 compatibility to XEmacs.
1130 Unfortunately, ordinary emacs integers show some behaviour which in
1131 the new category of integers is not bearable anymore. This may lead
1132 to confusion in simpler cases, if not even to wrong code.
1134 The following example shows the most significant change:
1137 In an old fixnum-only SXEmacs:
1139 @result{} -134217728
1142 The same in a SXEmacs with ENT:
1148 Now the resulting integer is of bigz type.
1150 (bigzp (+ 1 134217727))
1155 Now, in general we can state, that whenever space is too tight for
1156 an integer to fit into the built-in integer type, this integer is
1157 coerced to the type @samp{bigz}.
1159 The reverse is not necessarily true. But there is an auto-coercion,
1160 known as canonicalisation, to bang big integers to ints, when they are
1161 small enough and to bang fractions which cancel to denominator 1 to
1162 integers, but some functions acquiesce their output as is.
1163 See the following examples:
1169 (bigzp (/ (2^ 42) (2^ 30)))
1175 (bigzp (factorial 4))
1180 We say, that @code{/} canonicalises its results, whereas
1181 @code{factorial} does not. Canonicalisation usually depends on the
1182 size of output compared to average input values. This is much too
1185 However, in order to be absolutely sure about the world where
1186 resulting integers (even fractions which cancel to integers) live,
1187 there is a canonicalisation function.
1189 @defun canonicalize-number number
1190 Return the canonical form of @var{number}.
1193 This function determines the smallest category a number can live in,
1194 and coerces to there. Hereby smallest category means the category
1195 with the least cardinality.
1198 (bigzp (factorial 4))
1200 (bigzp (canonicalize-number (factorial 4)))
1204 Canonicalisation actually begins in the expression reader already,
1205 consider the quotient @samp{4/2}, which cancels to @samp{2}.
1215 @node Category rational
1216 @subsection The category @samp{rational}
1218 The category of rationals gathers everything that is rational.
1219 Practically, it is the union of the integers with the @samp{bigq}s.
1222 The category's predicate is @code{rationalp}.
1224 @defun rationalp object
1225 Return @code{t} if @var{object} is a rational (i.e. a rational integer
1226 or a rational quotient), @code{nil} otherwise.
1232 (rationalp (factorial 100))
1240 @subsection The category @samp{real}
1242 The category of reals consists of the emacs floats and all
1243 arbitrary real-approximations (@samp{bigf}, @samp{bigfr} if provided).
1244 Possibly, if provided, it contains the symbolic ``number'' objects for
1245 positive and negative infinity, as well as @var{not-a-number}.
1247 Important note: As stated in the definition above, rationals are
1248 @emph{not} in the category of reals. This might seem contradictory,
1249 because (especially in school mathematics or calculus classes) reals
1250 are sometimes defined as the union of rationals and irrationals. From
1251 the algebraic view, this is approach is inconsistent. Please see
1252 @ref{Category comparable}. On the other hand, the non-ENT equivalent
1253 of real would be float, and in terms of non-ENT emacsen, fixnums are
1257 The category's predicate is @code{realp}.
1260 Return @code{t} if @var{object} is real (i.e. a float or one of the
1261 arbitrary-precision floats), @code{nil} otherwise.
1270 (realp (coerce 1 'bigf))
1274 (realp not-a-number)
1286 Additionally, the category real has some variables to control which
1287 float implementation is used. This is necessary as there is no
1288 information about loss of precision, and there is no function to
1289 measure if a float number would fit in one type or the other.
1291 @defvar read-real-as
1292 Indicate how real numbers should be read.
1293 If set to `nil' or 'float, reals are always converted to floats.
1294 If set to 'bigf or 'bigfr, reals are read as MPF floats or MPFR
1295 floats respectively.
1298 @defvar default-real-precision
1299 The default floating-point precision for newly created
1300 floating point values.
1301 This should be an unsigned integer no greater than
1302 @var{max-real-precision} to create external floats with the
1303 indicated precision.
1305 This variable is effective only when @var{read-real-as} is set to a
1306 float type which supports setting a precision.
1309 @defvar max-real-precision
1310 The maximum number of bits of precision a @samp{bigf} or @samp{bigfr}
1311 can have. This is determined by the underlying library used to
1312 implement arbitrary-precision floats.
1316 @node Category comparable
1317 @subsection The category @samp{comparable}
1319 Deductively, the category of comparables are all numbers which
1320 possess a total (archimedean) order. Inductively, this category is
1321 the union of reals and rationals. Comparables, as the names suggests,
1322 can be directly compared with ordering relations, such as @code{<} or
1326 The category's predicate is @code{comparablep}.
1328 @defun comparablep object
1329 Return @code{t} if @var{object} is comparable (i.e. a real or a
1330 rational), @code{nil} otherwise.
1332 We call a number comparable if there exists a total (archimedean)
1333 order on the underlying structure.
1346 @node Category nonnegative
1347 @subsection The category @samp{nonnegative}
1349 The category of nonnegatives are those comparables which are not
1350 less than zero. This explicitly implies, that 0 is nonnegative. The
1351 restriction to comparables is necessary, since the membership is
1352 indeed tested as in the definition.
1355 The category's predicate is @code{nonnegativep}.
1357 @defun nonnegativep object
1358 Return @code{t} if @var{object} is a nonnegative number, @code{nil}
1361 We call a number object non-negative iff it is comparable
1362 and its value is not less than 0.
1389 @node Category complex
1390 @subsection The category @samp{complex}
1392 The category of complices is the union of @samp{bigc}s and
1393 @samp{bigg}s. Explicitly, neither reals nor rationals are in the
1394 category of complex numbers, in contrast to some analytical
1395 definitions. See @ref{Category archimedean} for that.
1398 The category's predicate is @code{complexp}.
1400 @defun complexp object
1401 Return @code{t} if @var{object} is a complex number (i.e. either a
1402 @samp{bigc} or a @samp{bigg}), @code{nil} otherwise.
1411 (complexp (sqrt -2))
1426 @node Category archimedean
1427 @subsection The category @samp{archimedean}
1429 Deductively, the category of archimedeans contains all numbers which
1430 do have an archimedean valuation. Inductively, the category of
1431 archimedeans is the union of reals, rationals, complices and
1435 The category's predicate is @code{archimedeanp}.
1437 @defun archimedeanp object
1438 Return @code{t} if @var{object} is a number with an archimedean
1439 valuation, @code{nil} otherwise.
1451 (archimedeanp (sqrt -2))
1456 @node Category nonarchimedean
1457 @subsection The category @samp{nonarchimedean}
1460 Deductively, the category of non-archimedeans contains all numbers
1461 which do not have an archimedean valuation -- hence this category also
1462 holds numbers with trivial valuation.
1464 Currently, only residue classes are non-archimedeans for their only
1465 possible valuation is the trival one (which is not archimedean).
1468 The category's predicate is @code{nonarchimedeanp}.
1470 @defun nonarchimedeanp object
1471 Return @code{t} if @var{object} is a number with an non-archimedean
1472 valuation, @code{nil} otherwise.
1478 (nonarchimedeanp 1/2)
1480 (nonarchimedeanp 1.2)
1482 (nonarchimedeanp 12+121Z)
1487 @node Category algebraic
1488 @subsection The category @samp{algebraic}
1490 Not yet implemented.
1493 @node Category transcendent
1494 @subsection The category @samp{transcendent}
1496 Not yet implemented.
1500 @subsection The category @samp{zero}
1502 The category of zeroes are all numbers which represent a zero, that
1503 is an additive neutral element. In that sense, the following is
1507 (equal @var{num} (+ 0 @var{num}))
1511 The category's predicate is @code{zerop}.
1514 Return @code{t} if @var{object} is a zero, @code{nil} otherwise.
1518 Let us look at a variety of examples.
1539 There is a constructor for zeroes which accepts an arbitrary number
1540 and uses that to determine the world, read type, the number lives in.
1541 Afterwards it creates and returns the zero of that number type.
1544 Return the zero of the world @var{number} lives in.
1557 @result{} 0.000000+0.000000i
1565 @subsection The category @samp{one}
1567 The category of ones are all numbers which represent a one, that
1568 is a multiplicative neutral element. In that sense, the following is
1572 (equal @var{num} (* 1 @var{num}))
1576 The category's predicate is @code{onep}.
1579 Return @code{t} if @var{object} is a one, @code{nil} otherwise.
1582 As for zeroes, there is a constructor for ones, too, which similarly
1583 accepts an arbitrary number and uses that to determine the world of
1584 the number. Afterwards it creates and returns the one of that number
1588 Return the one of the world @var{number} lives in.
1601 @result{} 1.000000+0.000000i
1609 @node Category number
1610 @subsection The category @samp{number}
1612 Inductively, the union of all categories discussed above is the
1613 category @samp{number}. The category's predicate is @code{numberp}.
1615 @defun numberp object
1616 Return @code{t} if @var{object} is a number, @code{nil} otherwise.
1623 Like for non-ENT-SXEmacsen, various coercions (conversions) can be
1624 done. Hereby, on coercion numbers may lose some of their
1625 information. Possibly this loss of information totally destroys the
1626 numeric value of a number, and thusly makes coercion uninvertable in
1629 @defun coerce-number number type &optional precision
1630 Convert NUMBER to the indicated type, possibly losing information.
1633 TYPE is one of the symbols:
1634 - @var{fixnum} or @var{int} to convert to built-in integers
1635 - @var{bigz} or @var{bignum} to convert to bigz integers
1636 - @var{integer} to convert to the most suitable type out
1637 of @var{bigz} or @var{int}
1639 - @var{bigq} or @var{ratio} to convert to bigq fractions
1640 - @var{rational} to convert to the most suitable type out
1641 of @var{bigq}, @var{bigz} or @var{int}
1643 - @var{float} to convert to built-in floats
1644 - @var{bigf} or @var{bigfloat} to convert to bigf floats
1645 - @var{bigfr} to convert to bigfr floats
1646 - @var{real} to convert to the type indicated by
1647 @var{read-real-as} with a fallback to
1650 - @var{bigg} to convert to a Gaussian
1651 - @var{bigc} to convert to a bigc complex number
1653 @emph{Note:} Not all of these types may be supported.
1655 The optional argument @var{precision} is the number of bits of
1656 precision to use when converting to reals; it is ignored otherwise.
1657 If @code{nil}, the default precision is used.
1659 Note that some conversions lose information. No error is signaled in
1660 such cases; the information is silently lost.
1665 (coerce-number 1 'bigz)
1667 (bigzp (coerce-number 1 'bigz))
1672 (coerce-number 1 'integer)
1674 (coerce-number (exp 40) 'integer)
1675 @result{} 235385266837019985
1676 (bigzp (coerce-number 1 'integer))
1678 (bigzp (coerce-number (exp 40) 'integer))
1683 (coerce-number 8/2 'bigq)
1685 (coerce-number 8/2 'rational)
1687 (bigqp (coerce-number 8/2 'bigq))
1689 (bigqp (coerce-number 8/2 'rational))
1695 Now an example for how to effectively lose information and hence make
1696 coercion uninvertable.
1699 (coerce-number 4/3 'bigfr)
1700 @result{} 1.333333333333333333333333333333333333335
1701 (coerce-number (coerce-number 4/3 'bigfr) 'bigq)
1702 @result{} 105637550019019116791391933781/79228162514264337593543950336
1705 Besides, the types @samp{bigf}, @samp{bigfr} and @samp{bigc} allow
1706 you to pass a precision to @code{coerce-number} and some mathematical
1707 functions. In order to get a notion of varying precisions, we will
1708 first present some examples:
1711 (coerce-number 49000 'bigfr 16)
1713 (coerce-number 49000 'bigfr 13)
1715 (coerce-number 49000 'bigfr 12)
1717 (coerce-number 49000 'bigfr 10)
1719 (coerce-number 49000 'bigfr 9)
1721 (coerce-number 49000 'bigfr 8)
1723 (coerce-number 49000 'bigfr 7)
1725 (coerce-number 49000 'bigfr 4)
1729 Here you can see precisely how rounding affects the actual value of
1730 a number. Also note, with precision 9 or lower the number is not
1731 actually a float anymore, because the radix would require more digits
1732 in order to be set. Whenever something like this occurs, we fill the
1733 output with trailing zeroes instead of using the scientific
1734 exponential notation. That means, we write @samp{48900} instead of
1738 Even more complicated is the situation with one-way coercions.
1739 Numbers of the category @samp{complex} cannot be coerced to numbers of
1740 the category @samp{comparable}. This is because there exist a dozen
1741 methods to do that, and it is not clear which one to use.
1744 (coerce-number 1 'bigg)
1746 (coerce-number (coerce-number 1 'bigg))
1747 @result{} Wrong type argument: comparablep, 1+0i
1750 To ease that pain a little you can explicitly use your favourite
1751 embedding into comparables. For example:
1754 (defun my-coerce-from-bigg (num)
1755 (if (zerop (imaginary-part num))
1757 (canonical-norm num)))
1758 @result{} my-coerce-from-bigg
1760 (let ((num (coerce-number 3 'bigg)))
1761 (my-coerce-from-bigg num))
1765 (my-coerce-from-bigg num))
1771 There are some abbreviated forms for number coercion.
1773 @defun int number &optional precision
1774 Return the ordinary integer numerically equal to @var{number}.
1775 The optional argument @var{precision} is unused.
1777 This is equivalent to
1778 @code{(coerce-number @var{number} 'int precision)}
1781 @defun bigz (number &optional precision)
1782 Return the MPZ number numerically equal to @var{number}.
1783 The optional argument @var{precision} is unused.
1785 This is equivalent to
1786 @code{(coerce-number @var{number} 'bigz precision)}
1789 @defun bigq (number &optional precision)
1790 Return the MPQ number numerically equal to @var{number}.
1791 The optional argument @var{precision} is unused.
1793 This is equivalent to
1794 @code{(coerce-number @var{number} 'bigq precision)}
1797 @defun rational (number &optional precision)
1798 Return a rational most suitable to represent @var{number}.
1799 The optional argument @var{precision} is unused.
1801 This is equivalent to
1802 @code{(coerce-number @var{number} 'rational precision)}
1806 Return the floating point number numerically equal to @var{number}.
1809 @defun bigf (number &optional precision)
1810 Return the MPF number numerically equal to @var{number}.
1811 If optional argument @var{precision} is non-@code{nil}, its value
1812 (an integer) is used as precision.
1814 This is equivalent to
1815 @code{(coerce-number @var{number} 'bigf precision)}
1818 @defun bigfr (number &optional precision)
1819 Return the MPFR number numerically equal to @var{number}.
1820 If optional argument @var{precision} is non-@code{nil}, its value
1821 (an integer) is used as precision.
1823 This is equivalent to
1824 @code{(coerce-number @var{number} 'bigfr precision)}
1827 @defun real (number &optional precision)
1828 Return a real with respect to @var{read-real-as} numerically
1829 equal to @var{number}.
1830 If optional argument @var{precision} is non-@code{nil}, its value
1831 (an integer) is used as precision.
1833 This is equivalent to
1834 @code{(coerce-number @var{number} 'real precision)}
1838 @defun bigg (number &optional precision)
1839 Return the Gaussian number numerically equal to @var{number}.
1840 The optional argument @var{precision} is unused.
1842 This is equivalent to
1843 @code{(coerce-number @var{number} 'bigg precision)}
1846 @defun bigc (number &optional precision)
1847 Return the MPC number numerically equal to @var{number}.
1848 If optional argument @var{precision} is non-@code{nil}, its value
1849 (an integer) is used as precision.
1851 This is equivalent to
1852 @code{(coerce-number @var{number} 'bigc precision)}
1858 @node Revised Arithmetics
1859 @section Revised Arithmetics
1861 Of course, arithmetical functions like @code{+}, @code{*} and so
1862 forth, have been reused for enhanced number types. These are
1863 transparently overlaid. This concept allows to use the same emacs
1864 lisp code for both non-ENT and ENT-SXEmacsen.
1866 However, some of the arithmetical changes are not intuitive, so we
1867 discuss them here. Please always refer to @ref{Numbers} for
1868 function and variable equivalents in a non-ENT-SXEmacs.
1871 * Basic Arithmetics and ENT:: How does ENT work with basic
1872 arithmetic operations.
1873 * New Arithmetics:: New arithmetical functions.
1877 @node Basic Arithmetics and ENT
1878 @subsection Basic Arithmetics and ENT
1880 Of course, all of the provided new number types work when used with
1881 the basic arithmetic operations, @code{+}, @code{-}, @code{*},
1882 @code{/}, @code{%}, @code{1+}, and @code{1-}. At first glance, there
1883 are no severe differences to non-ENT-SXEmacs. However, there is a
1884 traditional rule, whenever one argument in a basic arithmetic
1885 operation is a float, the result is a float. This is an auto-coercion
1886 behaviour, which is heavily generalised in an ENT-SXEmacs.
1888 First, a remark on the alternatives. The most obvious alternative
1889 would have been to @emph{disallow} algebraic operations on arguments
1890 of different types, or (to be more fair) to disallow certain category
1891 mixtures in the arguments. But since SXEmacs is not a strict maths
1892 professor, we will allow most combinations of argument types.
1894 Indeed there are a few cases of binary operations where coercion
1895 would be so confusing that SXEmacs rather answers with an error
1896 instead of trying the insane.
1898 For a better understanding of the behaviour of auto-coercion,
1899 imagine that the expression @code{(+ @var{a} @var{b})} does something
1903 (let ((super-category (find-least-common-category a b)))
1904 (+ (coerce a super-category) (coerce 'b super-category)))
1908 analogously for more than two arguments.
1910 Now we just have to look at what this
1911 @code{find-least-common-category} actually does. For some types it is
1912 obvious, an @samp{int} and a @samp{bigz} share the super-category
1913 @samp{integer}, a @samp{float} and a @samp{bigfr} belong to
1914 @samp{real}. In that way, we can define the following chains:
1917 int < bigz < bigq < float < bigf < bigfr < bigc
1918 int < bigz < bigg < bigc
1922 which verbosely means, if argument one is of type @samp{int} and
1923 argument two of type @samp{bigz}, then their super-category is
1924 @samp{bigz}; if argument one is of type @samp{bigz} and argument two
1925 of type @samp{bigq} their super-category is @samp{bigq}, and so on.
1927 The general rule is to look for the first argument's type in one of
1928 the chains, then if the second is in the same chain, use the type
1929 which is more to the right. If the arguments' types lie in different
1930 chains, go rightwards to the leftmost type which is in both chains and
1944 @result{} 2.066666664+2.800000000i
1948 To be honest, this is chain technique is just a hint for users or
1949 programmers. The awful truth is that for every binary operation and
1950 every two types there has to be a function which returns the
1953 Given that we currently support 12 different number types and 16
1954 elementary binary operations and relations, there is a total of 2304
1955 combinations -- which is too much to list here. The above chain
1956 technique is a good approximation of the actual behaviour for all of
1957 the elementary binary operations and relations.
1959 A variety of exceptions results from operations on residue classes
1960 and quaternions at the moment, which is due to the imposed
1961 mathematical background. Rather we discuss the resulting errors, all
1962 being sub-errors of the @samp{arith-error} class:
1964 @defvr Error operation-error
1965 Error signalled when an operation is undefined over the worlds of the
1969 @defvr Error relation-error
1970 Error signalled when a relation is undefined over the worlds of the
1974 @defvr Error valuation-error
1975 Error signalled when a valuation is undecidable or unknown over the
1976 world of an argument.
1979 @defvr Error domain-error
1980 Error signalled when the world of an argument cannot be coerced or
1981 lifted onto or into another world.
1985 We close this discussion with a small list of examples:
1990 Operation undefined over domain
1992 Operation undefined over domain
1997 Relation undefined over domain
1998 (= 2.0+1.0i 2.0+1.0i)
1999 Relation undefined over domain
2004 In order to retain compatibility to existing lisp code, there are a
2005 number of issues dealing with division. We have to distinguish
2006 between historical lisp-behaviour and mathematically correct
2007 behaviour. The historic behaviour of @code{/} is to act as what is
2008 known as @code{div}.
2019 However, in order to construct quotients of integers, in terms of
2020 creating a @samp{bigq}, there is the function @code{//}. This
2021 quotient function behaves just like @code{/} with the mentioned
2022 exception of returning always a fraction when all arguments are in the
2023 category of rationals.
2025 @defun // &rest numbers
2026 Return first argument divided by all the remaining arguments.
2027 If a rest occurred, the category is enlarged, such that
2028 the division can be performed without leaving a rest.
2030 The arguments must be numbers, characters or markers.
2031 With one argument, reciprocates the argument.
2035 The above examples using @code{//} then yield:
2046 The mathematical division (division with remainder) is provided by
2047 the function @code{div}, the corresponding remainder function is
2050 @defun div &rest numbers
2051 Return first argument divided by all the remaining
2052 arguments, possibly leaving a rest.
2054 The arguments must be numbers, characters or markers.
2055 With one argument, reciprocates the argument.
2057 The division of @var{a} and @var{b} is defined as the
2058 largest number @var{c} such that (* @var{b} @var{c}) is
2059 less or equal @var{a}.
2060 Hereby, @var{c} lies in the larger category of @var{a}
2063 The rest can be queried by `mod'.
2068 Return @var{x} modulo @var{y}.
2069 The result falls between zero (inclusive) and @var{y} (exclusive).
2070 Both @var{x} and @var{y} must be numbers, characters or markers.
2072 The result value lies in the larger category of @var{x} and @var{y}.
2077 @node New Arithmetics
2078 @subsection New Arithmetical Functions
2080 Completing basic arithmetics, ENT provides functions for
2081 exponentiation. In general, it is highly advised to prefer the
2082 dedicated power function over successive multiplication. We give a
2083 timing example below.
2085 @defun ^ number1 number2
2086 Return the power @var{number1} to the @var{number2}.
2093 @result{} 78551672112789411833022577315290546060373041
2096 Note that exponentiation is @emph{not} associative. That is why
2097 @code{^} merely takes two arguments at a time. Check the order of
2098 computation carefully. The following example demonstrates the
2099 generated error in case of wrong association.
2103 @result{} 2417851639229258349412352
2108 In order to get a notion of the time differences,
2111 (let ((start (current-btime))
2112 (dummy (^ 2 (^ 3 4)))
2113 (stop (current-btime)))
2119 Now we perform the same with sequential multiplication:
2122 (let* ((start (current-btime))
2125 (2^3^4 (dotimes (i 3^4 result)
2126 (setq result (* 2 result))))
2127 (stop (current-btime)))
2133 To see the superiority, we modify the actual problem.
2137 (let ((start (current-btime))
2138 (dummy (^ 5 (^ 5 5)))
2139 (stop (current-btime)))
2145 (let* ((start (current-btime))
2148 (5^5^5 (dotimes (i 5^5 result)
2149 (setq result (* 5 result))))
2150 (stop (current-btime)))
2157 Whenever computing two-powers or ten-powers, there are dedicated
2158 functions which make use of special algorithms.
2160 @defun 2^ number &optional precision
2161 Return the exponential of @var{number} to 2 power.
2162 If optional argument @var{precision} is non-@code{nil}, its value
2163 (an integer) is used as precision in float computations.
2166 @defun 10^ number &optional precision
2167 Return the exponential of @var{number} to 10 power.
2168 If optional argument @var{precision} is non-@code{nil}, its value
2169 (an integer) is used as precision in float computations.
2173 There is another arithmetic function working on the
2174 @dfn{prime decomposition} of integer numbers. This is roughly
2175 equivalent to repeatedly check if a number is congruent modulo a
2176 factor and if so a division by that factor.
2178 @defun remove-factor factor number
2179 Remove all occurences of @var{factor} in @var{number} and
2180 return a cons cell with @var{number} divided by a maximal
2181 power of @var{factor} in the car and the exponent in the cdr.
2185 (remove-factor 5 25)
2187 (remove-factor 7 25)
2189 (remove-factor 11 2198765678901)
2190 @result{} (18171617181 . 2)
2196 @node Revised Formatting
2197 @section New Output Formatting Features
2200 ENT provides a number of new format specifiers:
2204 @samp{%Z} means print as big integer (convert to bigz)
2206 @samp{%Q} means print as fraction (convert to bigq)
2208 @samp{%F} means print as bigfr or bigf float (convert to in that order)
2209 this specifier always converts the argument, regardless the
2210 value of `read-real-as'
2212 @samp{%R} means print as real number (convert to bigfr, bigf or float)
2213 this specifier respects the value of `read-real-as'
2215 @samp{%B} means print as Gaussian number (convert to bigg)
2217 @samp{%C} means print as complex number (convert to bigc)
2220 Both @samp{%B} and @samp{%C} are actually rewrites to @samp{%Z%+Z} and
2221 @samp{%F%+F} respectively with the argument @var{arg} rewritten to
2222 @code{(real-part @var{arg})} @code{(imaginary-part @var{arg})}.
2223 Flags are passed on to at least the real part specifier.
2226 On the other hand, we have tried to seamlessly integrate the new
2227 specifiers along with the ordinary ones. Any number object is
2228 coerced to the integers if @samp{%d} or @samp{%Z} is used, if that is
2229 possible (see @ref{Coercion}). Besides, the base converters work on
2230 any number in two steps, too: firstly, coerce to the integers,
2231 secondly convert to another base.
2234 Time for examples. Here we demonstrate the equivalence of @samp{%d}
2235 and @samp{%Z} if used with big integers as arguments.
2239 (format "%d" (factorial 20))
2240 @result{} "2432902008176640000"
2241 (format "%30d" (factorial 20))
2242 @result{} " 2432902008176640000""
2243 (format "%.30d" (factorial 20))
2244 @result{} "000000000002432902008176640000"
2248 (format "%Z" (factorial 20))
2249 @result{} "2432902008176640000"
2250 (format "%30Z" (factorial 20))
2251 @result{} " 2432902008176640000""
2252 (format "%.30Z" (factorial 20))
2253 @result{} "000000000002432902008176640000"
2258 Now we look at the coercion facilities:
2261 (format "%d" (exp 1))
2268 @result{} Wrong type argument: comparablep, 4+3i
2272 Let us have a quick glance at the specifiers @samp{%f}, @samp{%F}
2273 and @samp{%R}. The most obvious difference is their way to format
2274 precision flags, especially how they do precision rounding.
2276 The specifier @samp{%f} performs a mathematically correct rounding,
2277 whereas @samp{%F} cuts the precision, that is it truncates the result
2282 (format "%f" (exp 1))
2283 @result{} "2.718282"
2284 (format "%.2f" (exp 1))
2286 (format "%+.2f" (exp 1))
2291 (format "%F" (exp 1))
2292 @result{} "2.718281828459045235360287471352662497759"
2293 (format "%.2F" (exp 1))
2295 (format "%+.2f" (exp 1))
2300 Indeed, @samp{%R} is rewritten to either @samp{%f} or @samp{%F},
2301 depending on whether @var{read-real-as} is set to @code{'float} or
2302 @code{'bigf} or @code{'bigfr}, thusly precision rounding is performed
2303 the way of the rewritten specifier.
2309 (format "%R" (exp 1))
2310 @result{} "2.718282"
2311 (format "%.2R" (exp 1))
2316 (let ((read-real-as 'bigfr))
2317 (format "%R" (exp 1)))
2318 @result{} "2.718281828459045235360287471352662497759"
2319 (let ((read-real-as 'bigfr))
2320 (format "%.2R" (exp 1)))
2325 A special exception of the float formatting rule are indefinite
2326 numbers (we like it to call them indefinite symbols since they are not
2327 numbers). These are @code{+infinite}, @code{-infinite} and
2328 @code{not-a-number}. Except the total width flag all of the special
2329 flags are ignored in their format specification.
2333 (format "%F" +infinity)
2334 @result{} "+infinity"
2335 (format "%F" -infinity)
2336 @result{} "-infinity"
2337 (format "%F" not-a-number)
2338 @result{} "not-a-number"
2342 (format "%+F" +infinity)
2343 @result{} "+infinity"
2344 (format "% F" -infinity)
2345 @result{} "-infinity"
2346 (format "%.10F" not-a-number)
2347 @result{} "not-a-number"
2355 (format "%12F" +infinity)
2356 @result{} " +infinity"
2357 (format "%-12F" -infinity)
2358 @result{} "-infinity "
2359 (format "%20F" not-a-number)
2360 @result{} " not-a-number"
2364 The coercion to rational quotients (and their output formatting) is
2365 straightforward. It suffers from the impossibility to sanely coerce
2366 from floating point numbers, see @ref{Coercion}.
2368 The precision flag, in contrast, has no effect on rational
2369 quotients. It is generally deprecated to prepend leading zeroes to
2370 the numerator of a fraction.
2372 If the quotient can be cancelled it is done so, and the formatted
2373 output uses this cancelled fraction. If the quotient cancels to a
2374 rational integer, i.e. if the denominator is 1, the formatted output
2375 shows the integer equivalent of the fraction. Note that even in that
2376 situation the precision flag has no effect.
2395 (format "%5.5Q" 2/3)
2406 (format "%Q" 0.66666)
2407 @result{} "3002369727582815/4503599627370496"
2412 Finally we have a detailed look at the rewriting technique of
2413 complex and Gaussian numbers.
2419 (format "%Z%+Zi" (real-part 2+i) (imaginary-part 2+i))
2424 @result{} "1.00000000000000+1.00000000000000i"
2425 (format "%F%+Fi" (real-part 1+i) (imaginary-part 1+i))
2426 @result{} "1.00000000000000+1.00000000000000i"
2430 Flag characters as well as padding and precision flags are passed to
2431 the rewritten specifiers with the following exception, the space and
2432 unary plus flags are @emph{not} passed to the second rewritten
2433 specifier, instead the second rewritten specifier is always flagged
2434 with the unary plus.
2439 @result{} "1.0000+1.0000i"
2442 (format "%+.2C" 2+3i)
2443 @result{} "+2.00+3.00i"
2447 (format "%10.4C" 1+i)
2448 @result{} " 1.0000 +1.0000i"
2449 (format "%+10.4B" 1+i)
2450 @result{} " +0001 +0001i"
2451 (format "%-10.2C" 0+0i)
2452 @result{} "0.00 +0.00 i"
2458 @node Number Theoretic Functions
2459 @section Number Theoretic Functions
2461 If GMP is available, some number theoretic functions are in effect.
2462 Most of which accept, unlike in number theory, all kinds of numbers.
2463 In that case coercion to the target range (mostly integer) takes
2466 @defun primep number &optional certainty-threshold
2467 Return @code{nil} if @var{number} is known to be composite,
2468 return @code{t} if @var{number} is definitely prime and
2469 return @code{'probably-prime} if @var{number} seems to be
2470 prime but it is not certain.
2472 If optional argument @var{certainty-threshold} is non-@code{nil},
2473 it should be a natural number to indicate how many probabilistic
2474 primality tests must be passed in order to have certainty about the
2475 primality of @var{number}.
2479 @defun next-prime number
2480 Return the next prime number greater than @var{number}.
2483 @defun gcd &rest numbers
2484 Return the greatest common divisor of the arguments.
2487 @defun xgcd &rest numbers
2489 Return the extended gcd of the arguments.
2490 The result is a list of integers, where the car is the actual gcd
2491 and the cdr consists of coefficients, @var{s1}, @dots{}, @var{sn},
2492 such that @var{s1}*@var{arg1} + @dots{} + @var{sn}*@var{argn} = gcd.
2495 Return the extended gcd of the arguments.
2496 The result is a list of integers, where the car is the actual gcd
2497 and the cdr consists of coefficients,
2499 $s_1, @dots{}, s_n$,
2503 $\sum_{i=1}^n s_i arg_i = gcd$.
2508 @defun lcm &rest numbers
2509 Return the least common multiple of the arguments.
2512 @defun factorial number
2513 Return the factorial of @var{number}.
2516 @defun binomial-coefficient n k
2517 Return the binomial coefficient, @var{n} over @var{k}.
2521 @defun fibonacci number
2522 Return the @var{number}th Fibonacci number.
2523 To compute both, the @var{number}th and (@var{number}-1)th
2524 Fibonacci number use @code{fibonacci2} instead.
2527 @defun fibonacci2 number
2528 Return a cons with the @var{number}th and (@var{number}-1)th
2530 To compute a series of Fibonacci numbers starting at index
2531 @var{number}, use this function and recursively compute the rest.
2535 Return the @var{number}th Lucas number.
2536 To compute both, the @var{number}th and (@var{number}-1)th
2537 Lucas number use @code{lucas2} instead.
2540 @defun lucas2 number
2541 Return a cons with the @var{number}th and (@var{number}-1)th
2543 To compute a series of Lucas numbers starting at index
2544 @var{number}, use this function and recursively compute the rest.
2548 @defun divisiblep number d
2549 Return @code{t} if @var{number} is divisible by @var{d},
2550 @code{nil} otherwise.
2553 @defun congruentp number c m
2554 Return @code{t} if @var{number} is congruent to @var{c}
2555 modulo @var{m}, @code{nil} otherwise.
2559 @defun perfect-power-p number
2560 Return @code{t} if @var{number} is a perfect power, @code{nil} otherwise.
2561 An integer @var{number} is said to be a perfect power if there
2562 exist integers, @var{a} and @var{b}, such that
2563 @samp{@var{a}^@var{b} = @var{number}}.
2566 @defun perfect-square-p number
2567 Return @code{t} if @var{number} is a perfect square, @code{nil} otherwise.
2568 An integer @var{number} is said to be a perfect square if there
2569 exists an integer @var{b} such that
2570 @samp{@var{b}^2 = @var{number}}.
2574 @defun integral-sqrt number
2575 Return a cons with the integral square root of @var{number}
2576 in the car and the remainder in the cdr.
2577 An integral square root is a number @var{b} and a remainder @var{c}
2578 such that @samp{@var{b}*@var{b} + @var{c} = @var{number}}.
2583 @defun canonical-norm number
2584 Return the canonical norm of @var{number}.
2587 @defun conjugate number
2588 Return the (canonical) conjugate of @var{number}.
2589 If @var{number} is a comparable, just return @var{number}.
2593 @defun zero-divisor-p number
2594 Return @code{t} if @var{number} is a zero-divisor, @code{nil} otherwise.
2595 @var{number} is said to be a zero-divisor, if there exists another
2596 non-zero number @var{b}, such that
2597 @samp{@var{number} * @var{b} = 0}
2601 Return @code{t} if @var{number} is a unit, @code{nil} otherwise.
2602 @var{number} is said to be a unit, if there exists another number
2603 @var{b} (the inverse of @var{number}), such that
2604 @samp{@var{number} * @var{b} = 1}
2610 @node Auxiliary Functions
2611 @section Auxiliary Functions using ENT
2613 This section is an unstructured assortment of new functions or
2614 functions which change their behaviour in an ENT-build.
2616 @subsection Time functions
2618 @defun current-btime
2619 Return the current time, as the number of microseconds since
2620 1970-01-01 00:00:00.
2621 The time is returned as a big integer.
2626 @result{} 1131714421468312
2628 @result{} 1131714424362856
2631 With @code{current-btime} some of the functions of the
2632 @samp{time-date} library can be quickly rewritten.
2638 (/ (current-btime) (bigfr 86400000000))
2639 @result{} 13098.5557760026967592
2646 (time-to-number-of-days (current-time))
2647 @result{} 13098.55588377945
2651 Also, conversions from ordinary time conses to big time integers and
2652 vice versa are supported.
2654 @defun time-to-btime specified-time
2655 Return a big integer from @var{specified-time} with the
2656 number of microseconds since the Epoch.
2659 @defun btime-to-time specified-time
2660 Return a time specified as (high low usec) as obtainable
2661 from @code{current-time} from @var{specified-time}.
2666 (time-to-btime (current-time))
2667 @result{} 1131959836543525
2669 (btime-to-time 1131959836543525)
2670 @result{} (17272 22044 543525)
2675 Of course, existing time functions are changed when SXEmacs is
2676 compiled with ENT enabled, such that they take both, time cons cells
2677 and big integer time values. We do not list the respective functions
2680 @defun encode-btime &rest arguments
2681 Like `encode-time' but return a big integer time instead.
2685 @subsection Random numbers
2687 Having ENT enabled the @code{random} function may return
2688 pseudo-random integers of unlimited size. However, called without the
2689 optional limit argument, @code{random} always returns an ordinary
2690 integer (@samp{int}).
2692 @defun random &optional limit
2693 Return a pseudo-random number.
2694 All integers representable in Lisp are equally likely.
2695 On most systems, this is 31 bits' worth.
2697 With positive integer argument @var{limit}, return random number in
2698 interval [0,@var{limit}).
2699 @var{limit} can be a big integer, in which case the range of possible
2702 With argument @code{t}, set the random number seed from the current
2707 (random (factorial 20))
2708 @result{} 2391898294963683867
2709 (random (factorial 20))
2710 @result{} 1300461496957250511
2713 @defun randomb limit
2714 Return a uniform pseudo-random number in the range
2715 @samp{[0, 2^@var{limit})}.
2719 @subsection Sequences
2721 Having ENT and the residue class subfeature enabled the sequence
2722 accessor functions accept residue classes as their input. This is a
2723 neat feature when round-robins over sequences are regarded.
2726 (let ((v (make-vector 12 0))
2729 (while (<= (aref v rr) 43)
2734 @result{} [48 49 50 51 52 53 54 55 44 45 46 47]
2737 The above example shows a counter (@var{rr}) which can be
2738 continuously incremented without the need to check if its value is
2739 still in the bounds of the vector. The same snippet with @var{rr}
2740 being set to @code{0} would survive for 12 cycles and then yield:
2741 @samp{Args out of range: [0 1 2 3 4 5 6 7 8 9 10 11], 12}.
2745 @c ent.texi ends here