Next: , Previous: , 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)
(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 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: Bit operations, Previous: Numerical operations, Up: Numbers   [Contents][Index]