17. Numeric Types

17.1 Abstract Interface

The following types are always defined in the same manner:

• fixnum Whatever fits in the Lisp_Object type.
• integer The union of the fixnum and bignum types.
• rational The union of the integer and ratio types.
• float The equivalent of a C double.
• floating The union of the float and bigfloat types.
• real The union of the rational and floating types.
• number The union of the real and complex types. Since there is no complex type, this is currently equivalent to the real type.

The remaining types (bignum, ratio, and bigfloat) are defined by library-specific drivers, as detailed in the remaining sections of this chapter. A given driver may define one or more of these types to be empty. In fact, the default configuration makes all three types empty, so that integer and rational are the same types as fixnum, etc. The configure script sets zero or more of the symbols HAVE_BIGNUM, HAVE_RATIO, and HAVE_BIGFLOAT to indicate which types are nonempty. These are the consequences of an empty type:

• bignum Then bignump(x) is false for all x. Any attempt to create a bignum causes an error to be raised.
• ratio Then ratiop(x) is false for all x. Any attempt to create a ratio causes an error to be raised.
• bigfloat Then bigfloat(x) is false for all x. Any attempt to create a bigfloat causes an error to be raised.

We (provide) the following symbols, so that Lisp code can determine when the various numeric types are available for use:

• (provide 'bignum) if HAVE_BIGNUM is set
• (provde 'ratio) if HAVE_RATIO is set
• (provide 'bigfloat) if HAVE_BIGFLOAT is set

C code should use one of the following macros to create a Lisp integer, depending on the type of the C integer to be converted.

• make_fixnum(x) if x is guaranteed to fit into a Lisp fixnum.
• make_integer(x) if x is a signed C integer of any type.
• make_unsigned_integer(x) if x is an unsigned C integer of any type.

The make_integer(x) and make_unsigned_integer(x) macros both create a fixnum if possible, and a bignum otherwise. The value x can be a C integer of any size up to and including the size of a C long long int. The make_fixnum(x) macro is intended to signal the programmer’s intent that only fixnum-sized integers will be used. In some cases, if the compiler cannot prove that the parameter is always in the fixnum range, this macro is also a code optimization.

17.2 GMP driver

The GNU Multiple Precision library (http://gmplib.org/) and its fork, the Multiple Precision Integers and Rationals library (http://www.mpir.org/), provide large integers, ratios, and floating point numbers. The same driver supports both GMP and MPIR, and provides all 3 of the optional types: bignums, ratios, and bigfloats, implemented with the types mpz_t, mpq_t, and mpf_t, respectively. Most of the abstract numeric interface is defined in terms of macros that expand directly into GMP or MPIR API calls, since GMP and MPIR provide a rich interface.

17.3 BSD MP driver

The BSD MP interface is less rich than its GMP and MPIR counterparts. It provides only large integers, implemented as type MINT *; ratios and bigfloats are not available. BSD MP libraries are supplied by multiple vendors, with some small variations. This driver is intended to work with any variation.

Some BSD MP libraries use function names that are likely cause name collisions, such as gcd, mult, and pow. Others follow the Single Unix Specification recommendation (see https://www.freebsd.org/cgi/man.cgi?query=mp_mcmp&apropos=0&sektion=0&manpath=SunOS+5.10&arch=default&format=html) and prefix all of the function names with “mp_”: mp_gcd, mp_mult, mp_pow, etc. The XEmacs configure script detects which of the two interfaces is in use, and defines MP_PREFIX for the latter case. We use macros (MP_MULT, etc.) to hide this difference.

Another variation is that some, but not all, BSD MP libraries supply a function named move or mp_move that copies its first argument into its second argument. We define the move operation as setting the destination number to the source number plus zero for those libraries that do not supply this function.

The BSD MP interface does not directly support many of the operations that we need, so the implementations sometimes consist of complex functions. See the implementation of bignum_random, for example.

17.4 OpenSSL bignum driver

OpenSSL has its own bignum interface, which is the actual implementation behind FreeBSD’s libmp. It only has arbitrary precision integers, and thus, by lacking ratios and bigfloats, is less expressive than the GMP and MPIR interfaces. On the other hand, the API has proper error return codes for out of memory scenarioes, unlike the GMP and MPIR interfaces, which call abort(3) internally, terminating the whole process.

Most of the internal bignum API of XEmacs have direct representations in the OpenSSL API, but some operations, like bignum_set_string or the bit operations require explicit implementations.

The other major BSD derivatives besides FreeBSD have altogether dropped the BSD MP library (see section BSD MP driver), to the point that they don’t even have it in their third party software repositories. In essence, the BSD MP interface has been deprecated. On the other hand, OpenSSL (or LibreSSL) is included in virtually all modern operating system distributions, including Microsoft Windows.

17.5 Numeric driver interface

17.5.1 Bignum interface

Each bignum implementation defines HAVE_BIGNUM and an appropriate bignum type. For example, the GMP driver uses this definition:

typedef mpz_t bignum;

The following names are defined for each driver, either as real C functions or as C preprocessor macros.

• void bignum_init(bignum b) Does any necessary initialization before the bignum b can be used. This function typically allocates memory for the bignum.
• void bignum_fini(bignum b) Cleans up any resources held by the bignum b, typically deallocating the memory dedicated to that bignum. The object referred to by b must not be accessed after this call returns.
• unsigned int bignum_hashcode(bignum b) Returns a hash code for the bignum, suitable for use in XEmacs hash tables.
• int bignum_sign(bignum b) Returns a positive value, zero, or a negative value to indicate that b is positive, zero, or negative, respectively.
• int bignum_evenp(bignum b) Returns a nonzero value if b is an even number, zero if it is odd.
• int bignum_oddp(bignum b) Returns a nonzero value if b is an odd number, zero if it is even.
• int bignum_fits_int_p(bignum b) Returns a nonzero value if b can be represented in a C int, zero otherwise.
• int bignum_fits_uint_p(bignum b) Returns a nonzero value if b can be represented in a C unsigned int, zero otherwise.
• int bignum_fits_long_p(bignum b) Returns a nonzero value if b can be represented in a C long int, zero otherwise.
• int bignum_fits_ulong_p(bignum b) Returns a nonzero value if b can be represented in a C unsigned long int, zero otherwise.
• int bignum_fits_llong_p(bignum b) Returns a nonzero value if b can be represented in a C long long int, zero otherwise.
• int bignum_fits_ullong_p(bignum b) Returns a nonzero value if b can be represented in a C unsigned long long int, zero otherwise.
• void bignum_to_string(bignum b, int base) Converts b into a string representation using the given base, which is an integer between 2 and 36, inclusive.
• int bignum_to_int(bignum b) Converts b into a C int. If b does not fit into a C int, the results are undefined.
• unsigned int bignum_to_uint(bignum b) Converts b into a C unsigned int. If b does not fit into a C unsigned int, the results are undefined.
• long bignum_to_long(bignum b) Converts b into a C long int. If b does not fit into a C long int, the results are undefined.
• unsigned long bignum_to_ulong(bignum b) Converts b into a C unsigned long int. If b does not fit into a C unsigned long int, the results are undefined.
• long long bignum_to_llong(bignum b) Converts b into a C long long int. If b does not fit into a C long long int, the results are undefined.
• unsigned long long bignum_to_ullong(bignum b) Converts b into a C unsigned long long int. If b does not fit into a C unsigned long long int, the results are undefined.
• double bignum_to_double(bignum b) Converts b into a C double. If b is too large to represent as a C double, the results are implementation-specific. Typically, the result is positive or negative infinity, for implementations that can represent infinity.
• void bignum_set(bignum b1, bignum b2) Assigns the value of b2 to the bignum b1 by copying.
• void bignum_set_string(bignum b, const char *s, int base) Assigns b the value of the integer contained in string s, which is a number in base base.
• void bignum_set_long(bignum b, long l) Assigns b the value of the long integer l.
• void bignum_set_ulong(bignum b, unsigned long l) Assigns b the value of the unsigned long integer l.
• void bignum_set_llong(bignum b, long long l) Assigns b the value of the long long integer l.
• void bignum_set_ullong(bignum b, unsigned long long l) Assigns b the value of the unsigned long long integer l.
• void bignum_set_double(bignum b, double d) Assigns b to the truncated value of d; i.e, the fractional part of d is dropped.
• void bignum_set_ratio(bignum b, ratio r) Assigns b to the truncated value of r; i.e., the non-integer part of r is dropped. This function exists only if the driver supports ratios.
• void bignum_set_bigfloat(bignum b, bigfloat f) Assigns b to the truncated value of f; i.e., the fractional part of f is dropped. This function exists only if the driver supports bigfloats.
• int bignum_cmp(bignum b1, bignum b2) Returns a positive value, zero, or a negative value as b1 is greater than, equal to, or less than b2, respectively.
• int bignum_lt(bignum b1, bignum b2) Returns nonzero if b1 is less than b2, zero otherwise.
• int bignum_le(bignum b1, bignum b2) Returns nonzero if b1 is less than or equal to b2, zero otherwise.
• int bignum_eql(bignum b1, bignum b2) Returns nonzero if b1 is equal to b2, zero otherwise.
• int bignum_ge(bignum b1, bignum b2) Returns nonzero if b1 is greater than or equal to b2, zero otherwise.
• int bignum_gt(bignum b1, bignum b2) Returns nonzero if b1 is greater than b2, zero otherwise.
• void bignum_neg(bignum b, bignum b2) Sets b to the negation of b2.
• void bignum_abs(bignum b, bignum b2) Sets b to the absolute value of b2.
• void bignum_add(bignum b, bignum b1, bignum b2) Sets b to the sum of b1 and b2.
• void bignum_sub(bignum b, bignum b1, bignum b2) Sets b to the value of b1 minus b2.
• void bignum_mul(bignum b, bignum b1, bignum b2) Sets b to the product of b1 and b2.
• int bignum_divisible_p(bignum b1, bignum b2) Returns nonzero if b1 is evenly divisible by b2.
• void bignum_div(bignum b, bignum b1, bignum b2) Sets b to the truncated value of b1 divided by b2. That is, this function rounds toward zero.
• void bignum_ceil(bignum b, bignum b1, bignum b2) Sets b to the ceiling of b1 divided by b2. That is, ths function rounds toward positive infinity.
• void bignum_floor(bignum b, bignum b1, bignum b2) Sets b to the floor of b1 divided by b2. That is, ths function rounds toward negative infinity.
• void bignum_mod(bignum b, bignum b1, bignum b2) Sets b to b1 mod b2; i.e., the remainder after dividing b1 by b2. The sign is ignored; b is always nonnegative after this operation.
• void bignum_pow(bignum res, bignum b, unsigned int pow) Sets res to b to the powth power.
• void bignum_gcd(bignum res, bignum b1, bignum b2) Sets res to the greatest common divisor of b1 and b2.
• void bignum_lcm(bignum res, bignum b1, bignum b2) Sets res to the least common multiple of b1 and b2.
• void bignum_and(bignum res, bignum b1, bignum b2) Sets res to the bitwise AND of b1 and b2.
• void bignum_ior(bignum res, bignum b1, bignum b2) Sets res to the bitwise inclusive OR of b1 and b2.
• void bignum_xor(bignum res, bignum b1, bignum b2) Sets res to the bitwise exclusive OR of b1 and b2.
• void bignum_not(bignum res, bignum b) Sets res to the bitwise NOT of b.
• void bignum_setbit(bignum b, unsigned int bit) Sets the bitth bit of b to one, where the zeroth bit is the least significant.
• void bignum_clrbit(bignum b, unsigned int bit) Clears the bitth bit of b (i.e., sets it to zero), where the zeroth bit is the least significant.
• int bignum_testbit(bignum b, unsigned int bit) Returns the bitth bit of b, where the zeroth bit is the least significant.
• void bignum_lshift(bignum res, bignum b, unsigned int bits) Sets res to the value of b shifted left by bits bits.
• void bignum_rshift(bignum res, bignum b, unsigned int bits) Sets res to the value of b shifted right by bits bits.
• void bignum_random_seed(unsigned int seed) If the implementing library has its own pseudorandom number generator, then this function seeds the generator. If there is no generator, this function is a no-op.
• void bignum_random(bignum res, bignum limit) Sets res to a random number between zero (inclusive) and limit (exclusive).

17.5.2 Ratio interface

Each ratio implementation defines HAVE_RATIO and an appropriate ratio type. For example, the GMP driver uses this definition:

typedef mpq_t ratio;

The following names are defined for each driver, either as real C functions or as C preprocessor macros.

• void ratio_init(ratio r) Does any necessary initialization before the ratio r can be used. This function typically allocates memory for the ratio.
• void ratio_fini(ratio r) Cleans up any resources held by the ratio r, typically deallocating the memory dedicated to that ratio. The object referred to by r must not be accessed after this call returns.
• unsigned int ratio_hashcode(ratio r) Returns a hash code for the ratio, suitable for use in XEmacs hash tables.
• int ratio_sign(ratio r) Returns a positive value, zero, or a negative value to indicate that r is positive, zero, or negative, respectively.
• bignum ratio_numerator(ratio r) Returns the numerator of r.
• bignum ratio_denominator(ratio r) Returns the denominator of r.
• void ratio_canonicalize(ratio r) Removes any common factors from the numerator and denominator of r.
• void ratio_to_string(ratio r, int base) Converts r into a string representation using the given base, which is an integer between 2 and 36, inclusive.
• int ratio_to_int(ratio r) Converts r into a C int by truncating the ratio. If the truncation of r does not fit into a C int, the results are undefined.
• unsigned int ratio_to_uint(ratio r) Converts r into a C unsigned int by truncating the ratio. If the truncation of r does not fit into a C unsigned int, the results are undefined.
• long ratio_to_long(ratio r) Converts r into a C long int by truncating the ratio. If the truncation of r does not fit into a C long int, the results are undefined.
• unsigned long ratio_to_ulong(ratio r) Converts r into a C unsigned long int by truncating the ratio. If r does not fit into a C unsigned long int, the results are undefined.
• double ratio_to_double(ratio r) Converts r into a C double. If r is too large to represent as a C double, the results are implementation-specific. Typically, the result is positive or negative infinity, for implementations that can represent infinity.
• void ratio_set(ratio r1, ratio r2) Assigns the value of r2 to the ratio r1 by copying.
• void ratio_set_string(ratio r, const char *s, int base) Assigns r the value of the ratio contained in string s, which is a pair of numbers in base base separated by a forward slash.
• void ratio_set_long(ratio r, long l) Assigns r the value of the long integer l.
• void ratio_set_ulong(ratio r, unsigned long l) Assigns r the value of the unsigned long integer l.
• void ratio_set_double(ratio r, double d) Assigns r to the exact value of d. There is no rounding.
• void ratio_set_bignum(ratio r, bignum b) Assigns r to the value of b; i.e., the denominator is set to one.
• void ratio_set_bigfloat(ratio b, bigfloat f) Assigns b to the exact value of f. There is no rounding. This function exists only if the driver supports bigfloats.
• void ratio_set_long_ulong(ratio r, long num, unsigned long den) Assigns r the canonicalized ratio resulting from the division of num by den.
• void ratio_set_ulong_ulong(ratio r, unsigned long num, unsigned long den) Assigns r the canonicalized ratio resulting from the division of num by den.
• void ratio_set_bignum_bignum(ratio r, bignum num, bignum den) Assigns r the canonicalized ratio resulting from the division of num by den.
• int ratio_cmp(ratio r1, ratio r2) Returns a positive value, zero, or a negative value as r1 is greater than, equal to, or less than r2, respectively.
• int ratio_lt(ratio r1, ratio r2) Returns nonzero if r1 is less than r2, zero otherwise.
• int ratio_le(ratio r1, ratio r2) Returns nonzero if r1 is less than or equal to r2, zero otherwise.
• int ratio_eql(ratio r1, ratio r2) Returns nonzero if r1 is equal to r2, zero otherwise.
• int ratio_ge(ratio r1, ratio r2) Returns nonzero if r1 is greater than or equal to r2, zero otherwise.
• int ratio_gt(ratio r1, ratio r2) Returns nonzero if r1 is greater than r2, zero otherwise.
• void ratio_neg(ratio q, ratio q2) Sets q to the negation of q2.
• void ratio_abs(ratio q, ratio q2) Sets q to the absolute value of q2.
• void ratio_inv(ratio q, ratio q2) Sets q to the inverse of q2.
• void ratio_add(ratio res, ratio q1, ratio q2) Sets res to the sum of q1 and q2.
• void ratio_sub(ratio res, ratio q1, ratio q2) Sets res to the value of q1 minus q2.
• void ratio_mul(ratio res, ratio q1, ratio q2) Sets res to the product of q1 and q2.
• void ratio_div(ratio res, ratio q1, ratio q2) Sets res to the value of q1 divided by q2.

17.5.3 Bigfloat interface

Each bigfloat implementation defines HAVE_BIGFLOAT and an appropriate bigfloat type. For example, the GMP driver uses this definition:

typedef mpf_t bigfloat;

The following names are defined for each driver, either as real C functions or as C preprocessor macros.

• void bigfloat_init(bigfloat f) Does any necessary initialization before the bigfloat f can be used. This function typically allocates memory for the bigfloat.
• void bigfloat_init_prec(bigfloat f, unsigned int prec) Like bigfloat_init, but also sets the precision of f to at least prec bits.
• void bigfloat_fini(bigfloat f) Cleans up any resources held by the bigfloat f, typically deallocating the memory dedicated to that bigfloat. The object referred to by f must not be accessed after this call returns.
• unsigned int bigfloat_hashcode(bigfloat f) Returns a hash code for the bigfloat, suitable for use in XEmacs hash tables.
• int bigfloat_sign(bigfloat f) Returns a positive value, zero, or a negative value to indicate that f is positive, zero, or negative, respectively.
• unsigned int bigfloat_get_prec(bigfloat f) Returns the precision of f in bits.
• void bigfloat_set_prec(bigfloat f, unsigned int prec) Sets the precision of f to at least prec bits.
• void bigfloat_set_default_prec(unsigned int prec) Sets the default precision of newly created bigfloats.
• unsigned int bigfloat_get_default_prec(void) Gets the default precision of newly created bigfloats.
• void bigfloat_to_string(bigfloat f, int base) Converts f into a string representation using the given base, which is an integer between 2 and 36, inclusive.
• int bigfloat_to_int(bigfloat f) Converts f into a C int by truncating the bigfloat. If the truncation of f does not fit into a C int, the results are undefined.
• unsigned int bigfloat_to_uint(bigfloat f) Converts f into a C unsigned int by truncating the bigfloat. If the truncation of f does not fit into a C unsigned int, the results are undefined.
• long bigfloat_to_long(bigfloat f) Converts f into a C long int by truncating the bigfloat. If the truncation of f does not fit into a C long int, the results are undefined.
• unsigned long bigfloat_to_ulong(bigfloat f) Converts f into a C unsigned long int by truncating the bigfloat. If f does not fit into a C unsigned long int, the results are undefined.
• double bigfloat_to_double(bigfloat f) Converts f into a C double. If f is too large to represent as a C double, the results are implementation-specific. Typically, the result is positive or negative infinity, for implementations that can represent infinity.
• void bigfloat_set(bigfloat f1, bigfloat f2) Assigns the value of f2 to the bigfloat f1 by copying.
• void bigfloat_set_string(bigfloat f, const char *s, int base) Assigns f the value of the bigfloat contained in string s.
• void bigfloat_set_long(bigfloat f, long l) Assigns f the value of the long integer l.
• void bigfloat_set_ulong(bigfloat f, unsigned long l) Assigns f the value of the unsigned long integer l.
• void bigfloat_set_double(bigfloat f, double d) Assigns f the value of d.
• void bigfloat_set_bignum(bigfloat f, bignum b) Assigns f to the value of b.
• void bigfloat_set_ratio(bigfloat b, ratio r) Assigns b to the result of dividing the numerator of r by its denominator.
• int bigfloat_cmp(bigfloat f1, bigfloat f2) Returns a positive value, zero, or a negative value as f1 is greater than, equal to, or less than f2, respectively.
• int bigfloat_lt(bigfloat f1, bigfloat f2) Returns nonzero if f1 is less than f2, zero otherwise.
• int bigfloat_le(bigfloat f1, bigfloat f2) Returns nonzero if f1 is less than or equal to f2, zero otherwise.
• int bigfloat_eql(bigfloat f1, bigfloat f2) Returns nonzero if f1 is equal to f2, zero otherwise.
• int bigfloat_ge(bigfloat f1, bigfloat f2) Returns nonzero if f1 is greater than or equal to f2, zero otherwise.
• int bigfloat_gt(bigfloat f1, bigfloat f2) Returns nonzero if f1 is greater than f2, zero otherwise.
• void bigfloat_neg(bigfloat f, bigfloat f2) Sets f to the negation of f2.
• void bigfloat_abs(bigfloat f, bigfloat f2) Sets f to the absolute value of f2.
• void bigfloat_add(bigfloat res, bigfloat f1, bigfloat f2) Sets res to the sum of f1 and f2.
• void bigfloat_sub(bigfloat res, bigfloat f1, bigfloat f2) Sets res to the value of f1 minus f2.
• void bigfloat_mul(bigfloat res, bigfloat f1, bigfloat f2) Sets res to the product of f1 and f2.
• void bigfloat_div(bigfloat res, bigfloat f1, bigfloat f2) Sets res to the value of f1 divided by f2.
• void bigfloat_ceil(bigfloat res, bigfloat f) Sets res to the ceiling of f.
• void bigfloat_floor(bigfloat res, bigfloat f) Sets res to the floor of f.
• void bigfloat_trunc(bigfloat res, bigfloat f) Sets res to the truncation of f.
• void bigfloat_sqrt(bigfloat res, bigfloat f) Sets res to the square root of f.
• void bigfloat_pow(bigfloat res, bigfloat f, unsigned int exp) Sets res to the value of f raised to the expth power.

This document was generated on September 25, 2026 using texi2html 1.82.