# Floating point and numerics

> The standard says very little about how floating point behaves, so IEEE 754 behaviour is something you check for, not something you get. This topic covers NaN and signed zero, conversions that are undefined, excess precision, and the library tools that behave well.

- **Source:** C++ Atlas (https://cppatlas.com/topics/floating-point-and-numerics)
- **Track:** Library utilities
- **Estimated reading time:** 13 minutes
- **ISO C++ clauses:** [basic.fundamental] (https://eel.is/c++draft/basic.fundamental), [conv.fpint] (https://eel.is/c++draft/conv.fpint), [conv.double] (https://eel.is/c++draft/conv.double), [expr.pre] (https://eel.is/c++draft/expr.pre), [expr.mul] (https://eel.is/c++draft/expr.mul), [expr.spaceship] (https://eel.is/c++draft/expr.spaceship), [cmp.partialord] (https://eel.is/c++draft/cmp.partialord), [numeric.limits.members] (https://eel.is/c++draft/numeric.limits.members), [charconv.to.chars] (https://eel.is/c++draft/charconv.to.chars), [charconv.from.chars] (https://eel.is/c++draft/charconv.from.chars), [numeric.ops.midpoint] (https://eel.is/c++draft/numeric.ops.midpoint), [c.math.lerp] (https://eel.is/c++draft/c.math.lerp)
- **cppreference links:** [Fundamental types (floating-point types)](https://en.cppreference.com/w/cpp/language/types), [std::numeric_limits<T>::is_iec559](https://en.cppreference.com/w/cpp/types/numeric_limits/is_iec559), [Floating-point conversions and exceptional values (implicit conversions)](https://en.cppreference.com/w/cpp/language/implicit_conversion), [std::to_chars](https://en.cppreference.com/w/cpp/utility/to_chars), [std::from_chars](https://en.cppreference.com/w/cpp/utility/from_chars), [std::midpoint](https://en.cppreference.com/w/cpp/numeric/midpoint), [std::lerp](https://en.cppreference.com/w/cpp/numeric/lerp), [Mathematical constants](https://en.cppreference.com/w/cpp/numeric/constants), [Extended floating-point types (header stdfloat)](https://en.cppreference.com/w/cpp/header/stdfloat), [FLT_EVAL_METHOD](https://en.cppreference.com/w/cpp/types/climits/FLT_EVAL_METHOD), [Common mathematical functions](https://en.cppreference.com/w/cpp/numeric/math)
- **Prerequisites:** fundamental-types-and-arithmetic-conversions, constant-expressions

## The one idea

C++ does not say that `double` is an IEEE 754 binary64 number. The core language only requires that the types `float`, `double` and `long double` hold a set of values where each set contains the one before, and that the value representation is implementation-defined. Everything you know about NaN, infinities, signed zero and round-to-nearest comes from the hardware and the compiler, not from the language.

The standard gives you one honest switch for asking. `std::numeric_limits<T>::is_iec559` is true when the type conforms to IEC 559, which is IEEE 754. You can `static_assert` on it, and that is the right way to document that a piece of code depends on IEEE behaviour.

> **Mental model.** A floating-point value is a point on a finite, uneven grid. Every operation computes an exact real answer and then snaps it to a nearby grid point. The standard leaves the grid and the snapping rule to the implementation, and `is_iec559` tells you the implementation chose the IEEE ones.

```cpp
#include <limits>

static_assert(std::numeric_limits<double>::is_iec559,
              "this code assumes IEEE 754 doubles");
static_assert(std::numeric_limits<double>::digits == 53);  // true for binary64
```

When `is_iec559` is true, `has_infinity`, `has_quiet_NaN` and `has_signaling_NaN` are true as well. Note also that division by zero is formally undefined in [expr.mul], including for floating-point operands. On an IEEE platform it yields an infinity or NaN in practice, which is why the `is_iec559` check matters before you rely on it.

## Why 0.1 + 0.2 is not 0.3

The decimal literal `0.1` has no finite binary expansion, so it is stored as the nearest binary64 value, which is slightly above one tenth. The same is true of `0.2` and `0.3`, each with its own small error. The sum of the first two is computed exactly and then rounded, and it lands one grid step above the grid point nearest to `0.3`.

```cpp
#include <cstdio>

int main() {
  double a = 0.1 + 0.2;
  std::printf("%d\n", a == 0.3);   // 0 on an IEEE binary64 platform
  std::printf("%.17g\n", a);       // 0.30000000000000004
}
```

The fix is never to compare computed floating-point values for equality unless you know the computation is exact. Compare with a tolerance chosen for the problem, which is relative for large magnitudes and absolute near zero. A single global epsilon is almost always wrong. `std::numeric_limits<double>::epsilon()` is the gap between 1.0 and the next value, so it is only a sensible tolerance for numbers near 1.

The grid is also uneven. Above 2 to the 24th power, `float` cannot represent every integer, so `16777216.0f + 1.0f` is `16777216.0f` again. Integers are exact in `double` only up to 2 to the 53rd power.

## NaN, ordering, and signed zero

A NaN is not equal to anything, including itself, and every ordered comparison with a NaN is false. The only comparison that is true is `!=`.

```cpp
#include <compare>
#include <limits>

int main() {
  double n = std::numeric_limits<double>::quiet_NaN();
  bool a = n == n;   // false
  bool b = n != n;   // true
  bool c = n < 1.0;  // false
  bool d = n >= 1.0; // false

  std::partial_ordering o = n <=> 1.0;
  bool u = (o == std::partial_ordering::unordered);  // true
  bool l = o < 0;    // false: unordered is not less
  bool g = o > 0;    // false: nor greater
  (void)a; (void)b; (void)c; (void)d; (void)u; (void)l; (void)g;
}
```

That is why `operator<=>` on a floating-point type returns `std::partial_ordering`, not `strong_ordering`. It has four values: less, equivalent, greater, and unordered. Because `unordered` compares false against every ordering test, `std::sort` with a plain `<` on data that contains a NaN breaks the strict weak ordering requirement, and the behaviour is undefined. Filter NaNs out first, or sort with `std::strong_order`, which is a total order that places NaNs consistently. The details of orderings belong to `three-way-comparison` and `strict-weak-ordering-and-comparators`.

> **Pitfall.** `std::max(a, b)` is defined with `<`. If `a` is a NaN, the comparison is false and the result depends on argument order. `std::fmax`, on the other hand, returns the non-NaN argument. Neither choice is wrong, but mixing them in one codebase gives results that change when a NaN appears.

Signed zero is the other trap. Under IEEE, `+0.0` and `-0.0` compare equal, yet they are different values with different bit patterns, and `std::signbit` and `std::copysign` can tell them apart. Functions such as `std::atan2`, and division in an IEEE environment, give different results for the two zeros. `<=>` treats them as `equivalent`, so a `bit_cast` to an integer is the way to ask whether two doubles are the same object, not just equal numbers.

## Rounding, precision, and `FLT_EVAL_METHOD`

The language lets an implementation evaluate floating-point operands and results in greater range and precision than the type requires, without changing the type. This is [expr.pre]. The macro `FLT_EVAL_METHOD` in `<cfloat>` reports what the implementation does: 0 means each operation is evaluated in its own type, and other values mean wider evaluation. Historic x87 builds used a wider format, which made `a + b == c` depend on whether the intermediate stayed in a register. On the arm64 machine used for the examples in this topic the value is 0.

Fused multiply-add is a modern relative of the same problem, and contraction is allowed whatever `FLT_EVAL_METHOD` says. A compiler that turns `a * b + c` into one fused instruction rounds once instead of twice, which changes the last bit of the result. In a test on this machine, both g++-16 and clang++ at `-O2` produced the fused answer for a carefully chosen input, and `-ffp-contract=off` produced the unfused one. If you need the same bits everywhere, call `std::fma` when you want one rounding, and disable contraction when you want two.

The rounding mode itself is dynamic state. The `<cfenv>` header lets you change it, but the compiler may assume the default mode unless the program says otherwise, so changing it casually is unreliable. The mode is not part of the type, and `std::numeric_limits<T>::round_style` describes the arithmetic's default.

## Conversions that are undefined

Converting a floating-point value to an integer truncates toward zero. If the truncated value does not fit in the destination type, the behaviour is undefined, whether the source is infinity, a NaN, or just a large finite number. This is [conv.fpint]. Converting between floating-point types is similar: a value in range but not exactly representable becomes an implementation-defined choice of one of the two neighbours, and a value out of range is undefined. In practice an IEEE platform gives an infinity, but the language does not promise it.

```cpp
constexpr int a = static_cast<int>(3.99);   // OK: 3
constexpr int b = static_cast<int>(-3.99);  // OK: -3, truncation toward zero

// constexpr int c = static_cast<int>(1e10);
// ill-formed: undefined behaviour is not a constant expression
```

Constant evaluation is a useful probe here. The commented line is rejected by both compilers because the conversion is not a constant expression. At run time the same code compiles and does whatever the hardware does, which is often saturation on arm64 and `INT_MIN` on x86.

Going the other way, from an integer to a floating-point type, an integer that is not exactly representable is rounded to one of the neighbours chosen by the implementation, and one that is out of range is undefined.

## The library tools that behave

`std::midpoint(a, b)` in `<numeric>`, since C++20, computes the average without overflowing. For integers the half-way case rounds toward the first argument, so `std::midpoint(1, 2)` is 1 and `std::midpoint(2, 1)` is 2. For floating-point arguments at most one inexact operation occurs.

`std::lerp(a, b, t)` in `<cmath>`, also C++20, interpolates and is specified to return exactly `a` at `t == 0` and exactly `b` at `t == 1`, to be finite for `t` in `[0, 1]`, to be monotonic in `t`, and to extrapolate for `t` outside that range. It is not the same as `a + t * (b - a)`, which fails to return `b` at `t == 1` for some inputs.

`std::to_chars` and `std::from_chars` in `<charconv>` are the correct way to move floating-point numbers through text. The plain `to_chars(first, last, value)` overload produces the shortest representation that `from_chars` will read back to exactly the same value. That is the round-trip guarantee, and the standard only provides it when both functions come from the same implementation. `from_chars` does not accept a leading plus sign or leading white space, it accepts `nan` and `inf`, and when the value is out of range it returns `result_out_of_range` and leaves the destination unmodified.

```cpp
#include <charconv>
#include <cstdio>

int main() {
  char buf[64];
  auto r = std::to_chars(buf, buf + sizeof buf, 0.1 + 0.2);
  *r.ptr = '\0';
  std::puts(buf);                  // 0.30000000000000004

  double back = 0;
  std::from_chars(buf, r.ptr, back);
  std::printf("%d\n", back == 0.1 + 0.2);  // 1: exact round trip

  double v = 7;
  const char s[] = "1e400";
  auto fr = std::from_chars(s, s + 5, v);
  // fr.ec == std::errc::result_out_of_range, and v is still 7
  (void)fr;
}
```

The constants in `<numbers>`, such as `std::numbers::pi` and `std::numbers::e`, come as variable templates such as `std::numbers::pi_v<float>`, plus plain `double` variables such as `std::numbers::pi`. You never need to write `3.14159` by hand.

## Constexpr math, extended types, and fast-math

Before C++23 most of `<cmath>` could not be used in constant expressions. C++23 made constexpr the functions that do not depend on the floating-point environment, among them `fabs`, `floor`, `ceil`, `fmod` and `fma`. C++26 extended this to most of the rest, including `sqrt`, which is not constexpr in C++23. GCC treats many built-ins as constant-foldable as an extension, so a compiler accepting a call is not evidence that the standard allows it.

C++23 also added optional extended floating-point types in `<stdfloat>`: `std::float16_t`, `std::float32_t`, `std::float64_t`, `std::float128_t` and `std::bfloat16_t`. An implementation declares each one through a macro such as `__STDCPP_FLOAT64_T__`. They are distinct types even when they have the same layout as a standard one, so `std::float64_t` is not `double`, and overloads and templates see them separately. On this machine, g++-16 provides all five.

`-ffast-math` is not a faster version of the standard. It is a family of compiler flags that licenses reassociation, ignores NaN and infinity, and assumes no signed zeros. Code that relies on NaN checks, `is_iec559` or exact rounding can silently change meaning. Treat the flag as leaving the standard, and keep it out of any code that handles NaNs or needs reproducible rounding.

## What to remember

- The standard does not require IEEE 754; use `static_assert(std::numeric_limits<T>::is_iec559)` to document the dependency.
- `0.1 + 0.2 != 0.3` because the literals and the sum are each rounded to the binary grid; compare with a problem-specific tolerance.
- A NaN is unequal to everything, and `<=>` on floating point yields `std::partial_ordering`, whose `unordered` value fails every ordering test.
- `+0.0 == -0.0`, but `signbit` and `copysign` see the difference.
- Excess precision and fused multiply-add are allowed, so results can differ between builds; `FLT_EVAL_METHOD` reports the evaluation format.
- Out-of-range float-to-integer conversion is undefined, and constant evaluation rejects it.
- `midpoint` and `lerp` avoid overflow and endpoint errors; integer `midpoint` rounds toward its first argument.
- `to_chars` and `from_chars` round-trip exactly, but only within one implementation.
- C++23 makes the environment-independent `<cmath>` functions constexpr and adds `<stdfloat>`; C++26 adds constexpr for most of the rest.
- `-ffast-math` abandons the semantics above.

## Concept Map Outline

- **Floating point and numerics:** The standard fixes little; IEEE behaviour is something you test for with is_iec559, not something you get.
  - **What the standard requires:** Only that float values are a subset of double values, which are a subset of long double; the representation is implementation-defined.
    - **is_iec559:** numeric_limits<T>::is_iec559 reports IEC 559 (IEEE 754) conformance; static_assert on it to document the dependency.
    - **Division by zero:** Formally undefined in [expr.mul]; IEEE platforms give an infinity or NaN.
    - **Extended types (C++23):** <stdfloat> adds optional float16_t to float128_t and bfloat16_t, each a distinct type from float, double and long double.
  - **Equality and ordering:** Floating-point comparison is not a total order, and equality is the wrong tool for computed values.
    - **0.1 + 0.2 != 0.3:** Each literal and the sum are rounded to the binary grid, so the sum lands one step from the nearest double to 0.3.
    - **NaN compares:** A NaN is unequal to everything including itself, and only != is true.
    - **partial_ordering:** <=> on floating point returns partial_ordering, whose unordered value fails less, equal and greater tests.
    - **Signed zero:** +0.0 equals -0.0, but signbit, copysign and a bit_cast can tell them apart.
  - **Precision and rounding:** Results can differ between builds because the standard permits wider evaluation and fused operations.
    - **Excess precision:** [expr.pre] lets operands and results use more range and precision than their type, without changing the type.
    - **FLT_EVAL_METHOD:** The <cfloat> macro that reports the evaluation format; 0 means each operation uses its own type.
    - **Contraction and fma:** A fused a*b+c rounds once; std::fma asks for that, and -ffp-contract=off forbids it.
  - **Conversions:** Narrowing from floating point can be undefined, and constant evaluation exposes it.
    - **Float to int:** Truncates toward zero; undefined when the result does not fit, including for infinities and NaNs.
    - **Float to float:** In range but inexact picks a neighbour, implementation-defined; out of range is undefined.
    - **Constant evaluation:** An out-of-range float-to-int conversion is not a constant expression, so constexpr rejects it.
  - **Library helpers:** Utilities that avoid the usual overflow, endpoint and text-conversion mistakes.
    - **midpoint:** Overflow-free average; integer results round toward the first argument.
    - **lerp:** Exact at t == 0 and t == 1, monotonic in t, and extrapolates outside the unit interval.
    - **to_chars and from_chars:** Shortest text that parses back exactly, guaranteed only within one implementation.
    - **numbers constants:** pi, e and friends as double variables, with _v variable templates for other types.
  - **Constexpr math and fast-math:** Which cmath functions work at compile time, and why optimization flags can leave the standard.
    - **C++23 constexpr cmath:** Functions independent of the floating-point environment, such as fabs, floor and fma, became constexpr.
    - **C++26 constexpr cmath:** Most remaining functions, including sqrt and sin, became constexpr in C++26.
    - **-ffast-math:** Licenses reassociation and ignoring NaN, infinity and signed zero; the program no longer follows the standard's rules.

## Standardese Quiz Questions

### Question 1 [warmup] ([basic.fundamental], [expr.pre])

Assume `double` is IEEE 754 binary64 and `FLT_EVAL_METHOD` is 0. What is printed?

```cpp
#include <cstdio>

int main() {
  double a = 0.1 + 0.2;
  std::printf("%d\n", a == 0.3);
}
```

A. 1
B. 0
C. Undefined behavior
D. Ill-formed: `==` on floating-point operands is not allowed

**Answer (B):** 0

**Why:** The literals `0.1`, `0.2` and `0.3` are each rounded to the nearest binary64 value, and the sum of the first two is rounded again. The result is `0.30000000000000004`, one grid step above the double nearest to `0.3`, so the comparison is false. Comparing floating-point values with `==` is allowed, it is just rarely what you want.

### Question 2 [warmup] ([expr.eq], [expr.rel])

Assume `double` is IEEE 754 binary64. What is printed?

```cpp
#include <cmath>
#include <cstdio>

int main() {
  double n = std::nan("");
  std::printf("%d%d%d%d\n", n == n, n != n, n < n, n >= n);
}
```

A. 1010
B. 0101
C. 0100
D. 1111

**Answer (C):** 0100

**Why:** A NaN is unordered with everything, itself included. So `n == n` is 0, `n != n` is 1, and the ordered comparisons `n < n` and `n >= n` are both 0. Only `!=` is true for a NaN, which is the trap in the `0101` option: `>=` is not the negation of `<` when NaNs exist.

### Question 3 [warmup] ([basic.fundamental])

Assume `double` is IEEE 754 binary64. What is printed?

```cpp
#include <cmath>
#include <cstdio>

int main() {
  double x = -0.0, y = 0.0;
  std::printf("%d %g\n", x == y, std::copysign(1.0, x));
}
```

A. 1 1
B. 0 -1
C. 0 1
D. 1 -1

**Answer (D):** 1 -1

**Why:** Negative zero compares equal to positive zero, so `x == y` is 1. But it keeps its sign bit, and `std::copysign(1.0, x)` copies that sign onto 1.0, giving -1. The option `1 1` assumes the two zeros are the same value in every respect, which holds only for comparison.

### Question 4 [tricky] ([expr.spaceship], [cmp.partialord])

Assume `double` is IEEE 754 binary64. What is printed?

```cpp
#include <cmath>
#include <compare>
#include <cstdio>

int main() {
  auto o = std::nan("") <=> 1.0;
  std::printf("%d%d%d%d\n", o < 0, o == 0, o > 0,
              o == std::partial_ordering::unordered);
}
```

A. 0000
B. 0001
C. 1001
D. Ill-formed: `double` has no `operator<=>`

**Answer (B):** 0001

**Why:** `<=>` on `double` yields `std::partial_ordering`. With a NaN operand the result is `unordered`. That value is not less than, equivalent to, or greater than zero, so the first three tests print 0, and only the comparison with `std::partial_ordering::unordered` is true. The option `0000` forgets that `unordered` is a distinct, comparable value.

### Question 5 [tricky] ([conv.fpint], [expr.const])

In C++23, what is the status of this declaration?

```cpp
constexpr int i = static_cast<int>(1e10);

int main() { return 0; }
```

A. Well-formed, and `i` is `INT_MAX`
B. Well-formed, and `i` wraps modulo 2^32
C. Well-formed, and `i` has an implementation-defined value
D. Ill-formed: the initializer is not a constant expression

**Answer (D):** Ill-formed: the initializer is not a constant expression

**Why:** Converting a floating-point value to an integer type is undefined when the truncated value is not representable in the destination. Undefined behavior is never a constant expression, so a `constexpr` variable cannot be initialized this way and the compiler must diagnose it. Saturation or wraparound at run time is what some hardware does, not something the language promises.

### Question 6 [tricky] ([numeric.ops.midpoint])

In C++20 or later, what is printed?

```cpp
#include <cstdio>
#include <numeric>

int main() {
  std::printf("%d %d\n", std::midpoint(0, 3), std::midpoint(3, 0));
}
```

A. 1 1
B. 2 1
C. 1 2
D. 2 2

**Answer (C):** 1 2

**Why:** `std::midpoint(a, b)` for integers computes the half-way value without overflow, and when the sum is odd the result is rounded toward the first argument. The mathematical midpoint of 0 and 3 is 1.5, so `midpoint(0, 3)` is 1 and `midpoint(3, 0)` is 2. The answer `1 1` is what a truncating `(a + b) / 2` would print for both calls.

### Question 7 [standardese] ([basic.fundamental], [expr.mul], [numeric.limits.members])

Which statement about `double` does the C++23 standard guarantee on every conforming implementation?

A. It has a 53-bit significand
B. Every value of type `float` is also a value of type `double`
C. Dividing by zero produces an infinity
D. It has both an infinity and a quiet NaN

**Answer (B):** Every value of type `float` is also a value of type `double`

**Why:** [basic.fundamental] requires that the set of values of `float` is a subset of those of `double`, which in turn is a subset of those of `long double`. It leaves the representation implementation-defined. The significand width, the existence of an infinity or NaN (check `has_infinity` and `has_quiet_NaN`), and the meaning of division by zero (undefined in [expr.mul]) are all things you can only rely on when `is_iec559` says so.

### Question 8 [standardese] ([charconv.to.chars], [charconv.from.chars])

A program writes a `double` with the overload `std::to_chars(first, last, value)` that takes no format or precision, and another program parses the text with `std::from_chars`. What does the standard guarantee about recovering the exact value?

A. It is guaranteed only when both calls come from the same implementation
B. It is guaranteed for any pair of conforming implementations
C. It is guaranteed only if the writer passes precision 17
D. Nothing is guaranteed: the text is only an approximation

**Answer (A):** It is guaranteed only when both calls come from the same implementation

**Why:** The no-argument overload chooses the shortest representation that `from_chars` reads back to exactly the same value, but the standard attaches that guarantee to the same implementation. Passing a precision is not needed for the guarantee, which is why the precision-17 habit from `printf` is unnecessary here. The last option is wrong because the same-implementation round trip is exact.
