Next: , Previous: Numerical operations, Up: Numbers

4.6 Numerical input and output

— procedure: number->string number [radix]

Radix must be an exact integer, either 2, 8, 10, or 16. If omitted, radix defaults to 10. The procedure number->string takes a number and a radix and returns as a string an external representation of the given number in the given radix such that

          (let ((number number)
                (radix radix))
            (eqv? number
                  (string->number (number->string number radix)

is true. It is an error if no possible result makes this expression true.

If number is inexact, the radix is 10, and the above expression can be satisfied by a result that contains a decimal point, then the result contains a decimal point and is expressed using the minimum number of digits (exclusive of exponent and trailing zeroes) needed to make the above expression true; otherwise the format of the result is unspecified.

The result returned by number->string never contains an explicit radix prefix.

Note: The error case can occur only when number is not a complex number or is a complex number with an non-rational real or imaginary part.

Rationale: If number is an inexact number represented using flonums, and the radix is 10, then the above expression is normally satisfied by a result containing a decimal point. The unspecified case allows for infinities, NaNs, and non-flonum representations.

— variable: flonum-parser-fast?

This variable controls the behavior of string->number when parsing inexact numbers. Specifically, it allows the user to trade off accuracy against speed.

When set to its default value, #f, the parser provides maximal accuracy, as required by the Scheme standard. If set to #t, the parser uses faster algorithms that will sometimes introduce small errors in the result. The errors affect a few of the least-significant bits of the result, and consequently can be tolerated by many applications.

— variable: flonum-unparser-cutoff

This variable controls the action of number->string when number is a flonum (and consequently controls all printing of flonums). The value of this variable is normally a list of three items:

One of the following symbols: normal, relative, or absolute. The symbol normal means that the number should be printed with full precision. The symbol relative means that the number should be rounded to a specific number of digits. The symbol absolute means that the number should be rounded so that there are a specific number of digits to the right of the decimal point.
An exact integer. If rounding-type is normal, precision is ignored. If rounding-type is relative, precision must be positive, and it specifies the number of digits to which the printed representation will be rounded. If rounding-type is absolute, the printed representation will be rounded precision digits to the right of the decimal point; if precision is negative, the representation is rounded (- precision) digits to the left of the decimal point.
One of the symbols: normal, scientific, or engineering. This specifies the format in which the number will be printed.
scientific specifies that the number will be printed using scientific notation: x.xxxeyyy. In other words, the number is printed as a significand between zero inclusive and ten exclusive, and an exponent. engineering is like scientific, except that the exponent is always a power of three, and the significand is constrained to be between zero inclusive and 1000 exclusive. If normal is specified, the number will be printed in positional notation if it is “small enough”, otherwise it is printed in scientific notation. A number is “small enough” when the number of digits that would be printed using positional notation does not exceed the number of digits of precision in the underlying floating-point number representation; ieee double-precision floating-point numbers have 17 digits of precision.

This three-element list may be abbreviated in two ways. First, the symbol normal may be used, which is equivalent to the list (normal 0 normal). Second, the third element of the list, format-type, may be omitted, in which case it defaults to normal.

The default value for flonum-unparser-cutoff is normal. If it is bound to a value different from those described here, number->string issues a warning and acts as though the value had been normal.

Some examples of flonum-unparser-cutoff:

     (number->string (* 4 (atan 1 1)))
                                         => "3.141592653589793"
     (fluid-let ((flonum-unparser-cutoff '(relative 5)))
       (number->string (* 4 (atan 1 1))))
                                         => "3.1416"
     (fluid-let ((flonum-unparser-cutoff '(relative 5)))
       (number->string (* 4000 (atan 1 1))))
                                         => "3141.6"
     (fluid-let ((flonum-unparser-cutoff '(relative 5 scientific)))
       (number->string (* 4000 (atan 1 1))))
                                         => "3.1416e3"
     (fluid-let ((flonum-unparser-cutoff '(relative 5 scientific)))
       (number->string (* 40000 (atan 1 1))))
                                         => "3.1416e4"
     (fluid-let ((flonum-unparser-cutoff '(relative 5 engineering)))
       (number->string (* 40000 (atan 1 1))))
                                         => "31.416e3"
     (fluid-let ((flonum-unparser-cutoff '(absolute 5)))
       (number->string (* 4 (atan 1 1))))
                                         => "3.14159"
     (fluid-let ((flonum-unparser-cutoff '(absolute 5)))
       (number->string (* 4000 (atan 1 1))))
                                         => "3141.59265"
     (fluid-let ((flonum-unparser-cutoff '(absolute -4)))
       (number->string (* 4e10 (atan 1 1))))
                                         => "31415930000."
     (fluid-let ((flonum-unparser-cutoff '(absolute -4 scientific)))
       (number->string (* 4e10 (atan 1 1))))
                                         => "3.141593e10"
     (fluid-let ((flonum-unparser-cutoff '(absolute -4 engineering)))
       (number->string (* 4e10 (atan 1 1))))
                                         => "31.41593e9"
     (fluid-let ((flonum-unparser-cutoff '(absolute -5)))
       (number->string (* 4e10 (atan 1 1))))
                                         => "31415900000."
— procedure: string->number string [radix]

Returns a number of the maximally precise representation expressed by the given string. Radix must be an exact integer, either 2, 8, 10, or 16. If supplied, radix is a default radix that may be overridden by an explicit radix prefix in string (e.g. "#o177"). If radix is not supplied, then the default radix is 10. If string is not a syntactically valid notation for a number, then string->number returns #f.

          (string->number "100")        =>  100
          (string->number "100" 16)     =>  256
          (string->number "1e2")        =>  100.0
          (string->number "15##")       =>  1500.0

Note that a numeric representation using a decimal point or an exponent marker is not recognized unless radix is 10.