Conversions

• to-scientific-string – conversion to numeric string
• to-engineering-string – conversion to numeric string, using engineering notation
• to-number – conversion from numeric string

It is strongly recommended that implementations also provide conversions to and from a Binary Coded Decimal (BCD) representation, as appropriate for the implementation platform. Most decimal data are encoded in some form of BCD, and also a BCD form (especially one digit per byte) is easy to manipulate for further processing, formatting, etc.

It is recommended that implementations also provide conversions to and from binary floating-point or integer numbers, if appropriate (that is, if such encodings are supported in the environment of the implementation). It is suggested that such conversions be exact, if possible (that is, when converting from binary to decimal), or alternatively give the same results as converting using an appropriate string representation as an intermediate form. It is also recommended that if a number is too large to be converted to a given binary integer format then an exceptional or error condition be raised, rather than losing high-order significant bits (decapitating).

It is recommended that implementations also provide additional number formatting routines (including some which are locale-dependent), and if available should accept non-European decimal digits in strings.

Notes:

1. The setting of precision may be used to convert a number from any precision to any other precision, using the plus operation.
2. Integers are a proper subset of numbers, hence no conversion operation from an integer to a number is necessary. Conversion from a number to an integer with an exponent of zero is effected by using the quantize operation. Conversion from a number to an integral value (with a non-negative exponent) is effected by using the round-to-integral-value operation or the round-to-integral-exact operation. These meet the requirements of IEEE 754 §5.3.1 and §5.3.2.

Numeric string syntax

A numeric string is a character string that describes either a finite number or a special value.

• If it describes a finite number, it includes one or more decimal digits, with an optional decimal point. The decimal point may be embedded in the digits, or may be prefixed or suffixed to them. The group of digits (and optional point) thus constructed may have an optional sign (‘+’ or ‘-’) which must come before any digits or decimal point.
  The string thus described may optionally be followed by an ‘E’ (indicating an exponential part), an optional sign, and an integer following the sign that represents a power of ten that is to be applied. The ‘E’ may be in uppercase or lowercase.
• If it describes a special value, it is one of the case-independent names ‘Infinity’, ‘Inf’, ‘NaN’, or ‘sNaN’ (where the first two represent infinity and the second two represent quiet NaN and signaling NaN respectively). The name may be preceded by an optional sign, as for finite numbers. If a NaN, the name may also be followed by one or more digits, which encode any diagnostic information.

Formally:^[2] 

  sign           ::=  ’+’ | ’-’
  digit          ::=  ’0’ | ’1’ | ’2’ | ’3’ | ’4’ | ’5’ | ’6’ | ’7’ |
                      ’8’ | ’9’
  indicator      ::=  ’e’ | ’E’
  digits         ::=  digit [digit]...
  decimal-part   ::=  digits ’.’ [digits] | [’.’] digits
  exponent-part  ::=  indicator [sign] digits
  infinity       ::=  ’Infinity’ | ’Inf’
  nan            ::=  ’NaN’ [digits] | ’sNaN’ [digits]
  numeric-value  ::=  decimal-part [exponent-part] | infinity
  numeric-string ::=  [sign] numeric-value | [sign] nan

If an implementation supports the concept of diagnostic information on NaNs, the numeric strings for NaNs may include one or more digits, as shown above.^[3]  These digits encode the diagnostic information in an implementation-defined manner; however, conversions to and from string for diagnostic NaNs should be reversible if possible. If an implementation does not support diagnostic information on NaNs, these digits should be ignored where necessary. A plain ‘NaN’ is usually the same as ‘NaN0’.

Examples:

Some numeric strings are:

       "0"         -- zero
      "12"         -- a whole number
     "-76"         -- a signed whole number
      "12.70"      -- some decimal places
      "+0.003"     -- a plus sign is allowed, too
     "017."        -- the same as 17
        ".5"       -- the same as 0.5
      "4E+9"       -- exponential notation
       "0.73e-7"   -- exponential notation, negative power
      "Inf"        -- the same as Infinity
      "-infinity"  -- the same as -Inf
      "NaN"        -- not-a-Number
      "NaN8275"    -- diagnostic NaN

1. A single period alone or with a sign is not a valid numeric string.
2. A sign alone is not a valid numeric string.
3. Significant (after the decimal point) and insignificant leading zeros are permitted.

to-scientific-string – conversion to numeric string

If the number is a finite number then:

• The coefficient is first converted to a string in base ten using the characters 0 through 9 with no leading zeros (except if its value is zero, in which case a single 0 character is used).
  Next, the adjusted exponent is calculated; this is the exponent, plus the number of characters in the converted coefficient, less one. That is, exponent+(clength-1), where clength is the length of the coefficient in decimal digits.
  If the exponent is less than or equal to zero and the adjusted exponent is greater than or equal to -6, the number will be converted to a character form without using exponential notation. In this case, if the exponent is zero then no decimal point is added. Otherwise (the exponent will be negative), a decimal point will be inserted with the absolute value of the exponent specifying the number of characters to the right of the decimal point. ‘0’ characters are added to the left of the converted coefficient as necessary. If no character precedes the decimal point after this insertion then a conventional ‘0’ character is prefixed.
  Otherwise (that is, if the exponent is positive, or the adjusted exponent is less than -6), the number will be converted to a character form using exponential notation. In this case, if the converted coefficient has more than one digit a decimal point is inserted after the first digit. An exponent in character form is then suffixed to the converted coefficient (perhaps with inserted decimal point); this comprises the letter ‘E’ followed immediately by the adjusted exponent converted to a character form. The latter is in base ten, using the characters 0 through 9 with no leading zeros, always prefixed by a sign character (‘-’ if the calculated exponent is negative, ‘+’ otherwise).

• If the special value is quiet NaN then the resulting string is ‘NaN’, optionally followed by one or more digits representing diagnostic information. The digits will have no leading zeros.
• If the special value is signaling NaN then the resulting string is ‘sNaN’,^[4]  optionally followed by one or more digits representing diagnostic information, as for a quiet NaN.
• If the special value is infinity then the resulting string is ‘Infinity’.

Examples:

For each abstract representation [sign, coefficient, exponent], [sign, special-value], or [sign, special-value, diagnostic] on the left, the resulting string is shown on the right.

  [0,123,0]       "123"
  [1,123,0]       "-123"
  [0,123,1]       "1.23E+3"
  [0,123,3]       "1.23E+5"
  [0,123,-1]      "12.3"
  [0,123,-5]      "0.00123"
  [0,123,-10]     "1.23E-8"
  [1,123,-12]     "-1.23E-10"
  [0,0,0]         "0"
  [0,0,-2]        "0.00"
  [0,0,2]         "0E+2"
  [1,0,0]         "-0"
  [0,5,-6]        "0.000005"
  [0,50,-7]       "0.0000050"
  [0,5,-7]        "5E-7"
  [0,inf]         "Infinity"
  [1,inf]         "-Infinity"
  [0,qNaN]        "NaN"
  [0,qNaN,123]    "NaN123"
  [1,sNaN]        "-sNaN"

1. There is a one-to-one mapping between abstract representations and the result of this conversion. That is, every abstract representation has a unique to-scientific-string representation. Also, if that string representation is converted back to an abstract representation using to-number with sufficient precision, then the original abstract representation will be recovered.
   This one-to-one mapping guarantees that there is no hidden information in the internal representation of the numbers (‘what you see is exactly what you’ve got’).
2. The values quiet NaN and signaling NaN are distinguished in string form in order to preserve the one-to-one mapping just described. The strings chosen are those suggested by the IEEE 754 review committee and permitted by IEEE 754-2008.
3. The digits required for an exponent may be more than the number of digits required for E_max when a finite number is subnormal.

to-engineering-string – conversion to numeric string

The conversion exactly follows the rules for conversion to scientific numeric string except in the case of finite numbers where exponential notation is used. In this case,

• if the number is non-zero, the converted exponent is adjusted to be a multiple of three (engineering notation) by positioning the decimal point with one, two, or three characters preceding it (that is, the part before the decimal point will range from 1 through 999); this may require the addition of either one or two trailing zeros (otherwise, if after the adjustment the decimal point would not be followed by a digit then it is not added)
• if the number is a zero, the zero will have a decimal point and one or two trailing zeros added, if necessary, so that the original exponent of the zero would be recovered by the to-number conversion.

If the final exponent is zero then no indicator letter and exponent is suffixed.

Examples:

For each abstract representation [sign, coefficient, exponent] on the left, the resulting string is shown on the right.

  [0,123,1]       "1.23E+3"
  [0,123,3]       "123E+3"
  [0,123,-10]     "12.3E-9"
  [1,123,-12]     "-123E-12"
  [0,7,-7]        "700E-9"
  [0,7,1]         "70"
  [0,0,1]         "0.00E+3"

to-number – conversion from numeric string

Specifically, if the string represents a finite number then:

• If it has a leading sign, then the sign in the resulting abstract representation is set appropriately (1 for ‘-’, 0 for ‘+’). Otherwise the sign is set to 0.
  The decimal-part and exponent-part (if any) are then extracted from the string and the exponent-part (following the indicator) is converted to form the integer exponent which will be negative if the exponent-part began with a ‘-’ sign. If there is no exponent-part, the exponent is set to 0.
  If the decimal-part included a decimal point the exponent is then reduced by the count of digits following the decimal point (which may be zero) and the decimal point is removed. The remaining string of digits has any leading zeros removed (except for the rightmost digit) and is then converted to form the coefficient which will be zero or positive.
  A numeric string to finite number conversion is always exact unless there is an underflow or overflow (see below) or the number of digits in the decimal-part of the string is greater than the precision in the context. In this latter case the coefficient will be rounded (shortened) to exactly precision digits, using the rounding algorithm, and the exponent is increased by the number of digits removed. The rounded and other flags may be set, as if an arithmetic operation had taken place (see below).
  If the value of the adjusted exponent is less than E_min, then the number is subnormal. In this case, the calculated coefficient and exponent form the result, unless the value of the exponent is less than E_tiny, in which case the exponent will be set to E_tiny, and the coefficient will be rounded (possibly to zero) to match the adjustment of the exponent, with the sign remaining as set above. If this rounding gives an inexact result then the Underflow exceptional condition is raised.
  If (after any rounding of the coefficient) the value of the adjusted exponent is larger than E_max, then an exceptional condition (overflow) results. In this case, the result is as defined under the Overflow exceptional condition, and may be infinite. It will have the sign as set above.

If the string represents a special value then:

• For all special values, the sign of the number is set to 1 if the string has a leading ‘–’. Otherwise (there is a leading ‘+’, or no leading sign) the sign is set to 0.
• The strings ‘Infinity’ and ‘Inf’, independent of case, will be converted to infinity.
• The string ‘NaN’, independent of case, is converted to quiet NaN. If any digits follow the string ‘NaN’, any leading zeros are removed and the digits are then converted to form the diagnostic information for the NaN in a system-dependent way. If the implementation does not support diagnostic information on NaNs the digits should be ignored.
• The string ‘sNaN’, independent of case, is converted to signaling NaN. If any digits follow the string ‘sNaN’, they are treated in the same way as for quiet NaNs.

Examples:

For each string on the left, the resulting abstract representation [sign, coefficient, exponent], [sign, special-value], or [sign, special-value, diagnostic] is shown on the right. precision is at least 3.

  "0"            [0,0,0]
  "0.00"         [0,0,-2]
  "123"          [0,123,0]
  "-123"         [1,123,0]
  "1.23E3"       [0,123,1]
  "1.23E+3"      [0,123,1]
  "12.3E+7"      [0,123,6]
  "12.0"         [0,120,-1]
  "12.3"         [0,123,-1]
  "0.00123"      [0,123,-5]
  "-1.23E-12"    [1,123,-14]
  "1234.5E-4"    [0,12345,-5]
  "-0"           [1,0,0]
  "-0.00"        [1,0,-2]
  "0E+7"         [0,0,7]
  "-0E-7"        [1,0,-7]
  "inf"          [0,inf]
  "+inFiniTy"    [0,inf]
  "-Infinity"    [1,inf]
  "NaN"          [0,qNaN]
  "-NAN"         [1,qNaN]
  "SNaN"         [0,sNaN]
  "Fred"         [0,qNaN]