# Docs/ Floats

Amazon Ion supports IEEE-754 binary floating point values using the IEEE-754
32-bit (`binary32`

) and 64-bit (`binary64`

) encodings.
In the data model, all floating point values are treated as though they are
`binary64`

(all `binary32`

encoded values can be represented exactly in `binary64`

).

## Ion Text and Binary Considerations

In text, binary float is represented using familiar base-10 digits. While
this is convenient for human representation, there is no explicit notation
for expressing a particular floating point value as `binary32`

or `binary64`

.
Furthermore, many base-10 real numbers are irrational with respect to base-2 and
cannot be expressed exactly in either binary floating point encoding
(e.g. `1.1e0`

).

Because of this asymmetry, the rules for Ion text float notation when round-tripping to Ion binary MUST be observed:

- Any text notation that can be exactly represented as
`binary32`

MAY be encoded as either`binary32`

or`binary64`

in Ion binary. - Any text notation that can only be exactly represented as
`binary64`

MUST be encoded as`binary64`

in Ion binary. - Any text notation that has no exact representation (i.e. irrational in base-2
or more precision than the
`binary64`

mantissa), MUST be encoded as`binary64`

. This is to ensure that irrational numbers or truncated values are represented in the highest fidelity of the`float`

data type.

When encoding a decimal real number that is irrational in base-2 or has
more precision than can be stored in `binary64`

, the exact `binary64`

value is determined by using the IEEE-754 *round-to-nearest* mode with
a *round-half-to-even* as the tie-break. This mode/tie-break is the
common default used in most programming environments and is discussed in detail
in “Correctly Rounded Binary-Decimal and Decimal-Binary Conversions”.
This conversion algorithm is illustrated in a straightforward way in Clinger’s Algorithm.

When encoding a `binary32`

or `binary64`

value in text notation, an
implementation MAY want to consider the approach described in
“Printing Floating-Point Numbers Quickly and Accurately”.

### Special Values

The IEEE-754 binary floating point encoding supports special *non-number*
values. These are represented in the binary format as per the encoding rules
of the IEEE-754 specification, and are represented in text by the following
keywords:

`nan`

denotes the*not a number*(NaN) value.`+inf`

denotes*positive infinity*.`-inf`

denotes*negative infinity*.

The Ion data model considers all encodings of *positive infinity* to be equivalent
to one another and all encodings of *negative infinity* to be equivalent to one
another. Thus, an implementation encoding `+inf`

or `-inf`

in Ion binary
MAY choose to encode it using the `binary32`

or `binary64`

form.

The IEEE-754 specification has many encodings of NaN, but the Ion data model
considers all encodings of NaN (i.e. all forms of *signaling* or *quiet* NaN)
to be equivalent. Note that the text keyword `nan`

does not map to any
particular encoding, the only requirement is that an implementation emit
a bit-pattern that represents an IEEE-754 NaN value when converting to binary
(e.g. the `binary64`

bit pattern of `0x7FF8000000000000`

).

An important consideration is that NaN is not treated in a consistent
manner between programming environments. For example, Java defines that there
is only one canonical NaN value and it happens to be *signaling*. On C/C++,
on the other hand, NaN is mostly platform defined, but on platforms that support
it, the `NAN`

macro is a *quiet* NaN. In general, common programming
environments give testing routines for NaN, but no consistent way to represent
it.

## Examples

To illustrate the text/binary round-tripping rules above, consider the following examples.

The Ion text literal `2.147483647e9`

overflows the 23-bits of
significand in `binary32`

and MUST be encoded in Ion binary
as a `binary64`

value. The Ion binary encoding for this text literal is as
follows:

```
0x48 0x41 0xDF 0xFF 0xFF 0xFF 0xC0 0x00 0x00
```

The base-2 irrational literal `1.2e0`

following the rounding and encoding
rules MUST be encoded in Ion binary as:

```
0x48 0x3F 0xF3 0x33 0x33 0x33 0x33 0x33 0x33
```

Although the textual representative of `1.2e0`

itself is irrational, its
canonical form in the data model is not (based on the rounding rules), thus
the following text forms all map to the same `binary64`

value:

```
// the most human-friendly representation
1.2e0
// the exact textual representation in base-10 for the binary64 value 1.2e0 represents
1.1999999999999999555910790149937383830547332763671875e0
// a shortened, irrational version, but still the same value
1.1999999999999999e0
// a lengthened, irrational version that is still the same value
1.19999999999999999999999999999999999999999999999999999999e0
```