Decimal Arithmetic Specification, version 1.70
Copyright (c) IBM Corporation, 2009. All rights reserved. ©
 7 Apr 2009 
[previous  contents  next]

This section defines the required conversions between
the abstract representation of numbers and string (character) form.^{[1]}
Two numbertostring conversions and one stringtonumber conversion are
defined.
These are:
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 floatingpoint 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 highorder significant bits (decapitating).
It is recommended that implementations also provide additional
number formatting routines (including some which are localedependent),
and if available should accept nonEuropean decimal digits in strings.
Notes:

The setting of precision may be used to convert a number from
any precision to any other precision, using the plus operation.

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 nonnegative
exponent) is effected by using the
roundtointegralvalue operation or the
roundtointegralexact operation.
These meet the requirements of IEEE 754 §5.3.1 and §5.3.2.
Strings which are acceptable for conversion to the abstract
representation of numbers, or which might result from conversion from
the abstract representation to a string, are called numeric
strings.
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
caseindependent 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.
No blanks or other white space characters are permitted in a numeric
string.
Formally:^{[2]}
sign ::= ’+’  ’’
digit ::= ’0’  ’1’  ’2’  ’3’  ’4’  ’5’  ’6’  ’7’ 
’8’  ’9’
indicator ::= ’e’  ’E’
digits ::= digit [digit]...
decimalpart ::= digits ’.’ [digits]  [’.’] digits
exponentpart ::= indicator [sign] digits
infinity ::= ’Infinity’  ’Inf’
nan ::= ’NaN’ [digits]  ’sNaN’ [digits]
numericvalue ::= decimalpart [exponentpart]  infinity
numericstring ::= [sign] numericvalue  [sign] nan
where the characters in the strings accepted for infinity
and nan may be in any case.
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
implementationdefined 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.73e7"  exponential notation, negative power
"Inf"  the same as Infinity
"infinity"  the same as Inf
"NaN"  notaNumber
"NaN8275"  diagnostic NaN
Notes:

A single period alone or with a sign is not a valid numeric string.

A sign alone is not a valid numeric string.

Significant (after the decimal point) and insignificant leading zeros
are permitted.
This operation converts a number to a string, using scientific notation
if an exponent is needed.
The operation is not affected by the context.
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+(clength1),
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).
Otherwise (the number is a special value):

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’.
In all cases, the entire string is prefixed by a minus sign character^{[5]}
(‘’) if sign is 1. No sign character is prefixed
if sign is 0.
Examples:
For each abstract representation
[sign, coefficient, exponent],
[sign, specialvalue], or
[sign, specialvalue, 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.23E8"
[1,123,12] "1.23E10"
[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] "5E7"
[0,inf] "Infinity"
[1,inf] "Infinity"
[0,qNaN] "NaN"
[0,qNaN,123] "NaN123"
[1,sNaN] "sNaN"
Notes:

There is a onetoone mapping between abstract representations and the
result of this conversion. That is, every abstract representation has a
unique toscientificstring representation. Also, if that
string representation is converted back to an abstract representation
using tonumber with sufficient precision,
then the original abstract representation will be recovered.
This onetoone mapping guarantees that there is no hidden information
in the internal representation of the numbers (‘what you see is
exactly what you’ve got’).

The values quiet NaN and signaling NaN are
distinguished in string form in order to preserve the onetoone mapping
just described.
The strings chosen are those suggested by the IEEE 754 review
committee and permitted by IEEE 7542008.

The digits required for an exponent may be more than the number of
digits required for E_{max} when a finite number is
subnormal.
This operation converts a number to a string, using engineering notation
if an exponent is needed.
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 nonzero, 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 tonumber
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.3E9"
[1,123,12] "123E12"
[0,7,7] "700E9"
[0,7,1] "70"
[0,0,1] "0.00E+3"
This operation converts a string to a number, as defined by its abstract
representation.
The string is expected to conform to the numeric string
syntax.
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 decimalpart and exponentpart (if any) are then extracted from the
string and the exponentpart (following the indicator) is converted to
form the integer exponent which will be negative if the
exponentpart began with a ‘’ sign. If there is no
exponentpart, the exponent is set to 0.
If the decimalpart 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 decimalpart 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 systemdependent 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.
The result of attempting to convert a string which does not have the
syntax of a numeric string is [0,qNaN].
Examples:
For each string on the left, the resulting abstract representation
[sign, coefficient, exponent],
[sign, specialvalue], or
[sign, specialvalue, 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.23E12" [1,123,14]
"1234.5E4" [0,12345,5]
"0" [1,0,0]
"0.00" [1,0,2]
"0E+7" [0,0,7]
"0E7" [1,0,7]
"inf" [0,inf]
"+inFiniTy" [0,inf]
"Infinity" [1,inf]
"NaN" [0,qNaN]
"NAN" [1,qNaN]
"SNaN" [0,sNaN]
"Fred" [0,qNaN]
Footnotes:
[1] 
See also IEEE 754 §5.12.

[2] 
Where quotes surround terminal characters, ‘::=’ means ‘is
defined as’, ‘’ means ‘or’, ‘[]’
encloses an optional item, and ‘[]...’ encloses an item
which is repeated 0 or more times.

[3] 
In IEEE 754 interchange formats, the diagnostic information (payload)
is held in a similar manner to the coefficient of a finite number in
the same format, but has one digit fewer.

[4] 
This is a deviation from IEEE 8541987 (see Notes) but is permitted
by IEEE 7542008.

[5] 
This specification defines only the glyph representing a minus sign
character.
Depending on the implementation, this will often correspond to a hyphen
rather than to a distinguishable ‘minus’ character.

[previous  contents  next]