Numerical input and output (MIT/GNU Scheme 11.2)

Next: Fixnum and Flonum Operations, Previous: Numerical operations, Up: Numbers [Contents][Index]

### 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)
                              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 is deprecated; use `param:flonum-printer-cutoff` instead.

parameter: param:flonum-printer-cutoff

  This parameter controls the action of `number->string` when number is a flonum (and consequently controls all printing of flonums). This parameter may be called with an argument to set its value.

  The value of this parameter is normally a list of three items:

  rounding-type

    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.

  precision

    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.

  format-type

    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 754-2008 binary64 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 `param:flonum-printer-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 `param:flonum-printer-cutoff`:

    (number->string (* 4 (atan 1 1)))
                                        ⇒ "3.141592653589793"
    (parameterize ((param:flonum-printer-cutoff '(relative 5)))
      (number->string (* 4 (atan 1 1))))
                                        ⇒ "3.1416"
    (parameterize ((param:flonum-printer-cutoff '(relative 5)))
      (number->string (* 4000 (atan 1 1))))
                                        ⇒ "3141.6"
    (parameterize ((param:flonum-printer-cutoff '(relative 5 scientific)))
      (number->string (* 4000 (atan 1 1))))
                                        ⇒ "3.1416e3"
    (parameterize ((param:flonum-printer-cutoff '(relative 5 scientific)))
      (number->string (* 40000 (atan 1 1))))
                                        ⇒ "3.1416e4"
    (parameterize ((param:flonum-printer-cutoff '(relative 5 engineering)))
      (number->string (* 40000 (atan 1 1))))
                                        ⇒ "31.416e3"
    (parameterize ((param:flonum-printer-cutoff '(absolute 5)))
      (number->string (* 4 (atan 1 1))))
                                        ⇒ "3.14159"
    (parameterize ((param:flonum-printer-cutoff '(absolute 5)))
      (number->string (* 4000 (atan 1 1))))
                                        ⇒ "3141.59265"
    (parameterize ((param:flonum-printer-cutoff '(absolute -4)))
      (number->string (* 4e10 (atan 1 1))))
                                        ⇒ "31415930000."
    (parameterize ((param:flonum-printer-cutoff '(absolute -4 scientific)))
      (number->string (* 4e10 (atan 1 1))))
                                        ⇒ "3.141593e10"
    (parameterize ((param:flonum-printer-cutoff '(absolute -4 engineering)))
      (number->string (* 4e10 (atan 1 1))))
                                        ⇒ "31.41593e9"
    (parameterize ((param:flonum-printer-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`.

Next: Fixnum and Flonum Operations, Previous: Numerical operations, Up: Numbers [Contents][Index]