63.4 Coercion

Like for non-ENT-SXEmacsen, various coercions (conversions) can be done. Hereby, on coercion numbers may lose some of their information. Possibly this loss of information totally destroys the numeric value of a number, and thusly makes coercion uninvertable in general.

Function: coerce-number number type &optional precision

Convert NUMBER to the indicated type, possibly losing information. See coerce.

TYPE is one of the symbols: - fixnum or int to convert to built-in integers - bigz or bignum to convert to bigz integers - integer to convert to the most suitable type out of bigz or int

- bigq or ratio to convert to bigq fractions - rational to convert to the most suitable type out of bigq, bigz or int

- float to convert to built-in floats - bigf or bigfloat to convert to bigf floats - bigfr to convert to bigfr floats - real to convert to the type indicated by read-real-as with a fallback to float

- bigg to convert to a Gaussian - bigc to convert to a bigc complex number

Note: Not all of these types may be supported.

The optional argument precision is the number of bits of precision to use when converting to reals; it is ignored otherwise. If nil, the default precision is used.

Note that some conversions lose information. No error is signaled in such cases; the information is silently lost.

(coerce-number 1 'bigz)
     ⇒ 1
(bigzp (coerce-number 1 'bigz))
     ⇒ t

(coerce-number 1 'integer)
     ⇒ 1
(coerce-number (exp 40) 'integer)
     ⇒ 235385266837019985
(bigzp (coerce-number 1 'integer))
     ⇒ nil
(bigzp (coerce-number (exp 40) 'integer))
     ⇒ t

(coerce-number 8/2 'bigq)
     ⇒ 4
(coerce-number 8/2 'rational)
     ⇒ 4
(bigqp (coerce-number 8/2 'bigq))
     ⇒ t
(bigqp (coerce-number 8/2 'rational))
     ⇒ nil

Now an example for how to effectively lose information and hence make coercion uninvertable.

(coerce-number 4/3 'bigfr)
     ⇒ 1.333333333333333333333333333333333333335
(coerce-number (coerce-number 4/3 'bigfr) 'bigq)
     ⇒ 105637550019019116791391933781/79228162514264337593543950336

Besides, the types ‘bigf’, ‘bigfr’ and ‘bigc’ allow you to pass a precision to coerce-number and some mathematical functions. In order to get a notion of varying precisions, we will first present some examples:

(coerce-number 49000 'bigfr 16)
     ⇒ 49000.0
(coerce-number 49000 'bigfr 13)
     ⇒ 49000.
(coerce-number 49000 'bigfr 12)
     ⇒ 48992.
(coerce-number 49000 'bigfr 10)
     ⇒ 49024.
(coerce-number 49000 'bigfr 9)
     ⇒ 49020
(coerce-number 49000 'bigfr 8)
     ⇒ 48900
(coerce-number 49000 'bigfr 7)
     ⇒ 49150
(coerce-number 49000 'bigfr 4)
     ⇒ 49200

Here you can see precisely how rounding affects the actual value of a number. Also note, with precision 9 or lower the number is not actually a float anymore, because the radix would require more digits in order to be set. Whenever something like this occurs, we fill the output with trailing zeroes instead of using the scientific exponential notation. That means, we write ‘48900’ instead of ‘4.89E+4’.

Even more complicated is the situation with one-way coercions. Numbers of the category ‘complex’ cannot be coerced to numbers of the category ‘comparable’. This is because there exist a dozen methods to do that, and it is not clear which one to use.

(coerce-number 1 'bigg)
     ⇒ 1+0i
(coerce-number (coerce-number 1 'bigg))
     ⇒ Wrong type argument: comparablep, 1+0i

To ease that pain a little you can explicitly use your favourite embedding into comparables. For example:

(defun my-coerce-from-bigg (num)
  (if (zerop (imaginary-part num))
      (real-part num)
    (canonical-norm num)))
     ⇒ my-coerce-from-bigg

(let ((num (coerce-number 3 'bigg)))
  (my-coerce-from-bigg num))
     ⇒ 3

(let ((num 3+2i))
  (my-coerce-from-bigg num))
     ⇒ 13

There are some abbreviated forms for number coercion.

Function: int number &optional precision

Return the ordinary integer numerically equal to number. The optional argument precision is unused.

This is equivalent to (coerce-number number 'int precision)

Function: bigz (number &optional precision)

Return the MPZ number numerically equal to number. The optional argument precision is unused.

This is equivalent to (coerce-number number 'bigz precision)

Function: bigq (number &optional precision)

Return the MPQ number numerically equal to number. The optional argument precision is unused.

This is equivalent to (coerce-number number 'bigq precision)

Function: rational (number &optional precision)

Return a rational most suitable to represent number. The optional argument precision is unused.

This is equivalent to (coerce-number number 'rational precision)

Function: float number

Return the floating point number numerically equal to number.

Function: bigf (number &optional precision)

Return the MPF number numerically equal to number. If optional argument precision is non-nil, its value (an integer) is used as precision.

This is equivalent to (coerce-number number 'bigf precision)

Function: bigfr (number &optional precision)

Return the MPFR number numerically equal to number. If optional argument precision is non-nil, its value (an integer) is used as precision.

This is equivalent to (coerce-number number 'bigfr precision)

Function: real (number &optional precision)

Return a real with respect to read-real-as numerically equal to number. If optional argument precision is non-nil, its value (an integer) is used as precision.

This is equivalent to (coerce-number number 'real precision)

Function: bigg (number &optional precision)

Return the Gaussian number numerically equal to number. The optional argument precision is unused.

This is equivalent to (coerce-number number 'bigg precision)

Function: bigc (number &optional precision)

Return the MPC number numerically equal to number. If optional argument precision is non-nil, its value (an integer) is used as precision.

This is equivalent to (coerce-number number 'bigc precision)