Module std::prim_f32

A 32-bit floating point type (specifically, the “binary32” type defined in IEEE 754-2008).

This type can represent a wide range of decimal numbers, like 3.5, 27, -113.75, 0.0078125, 34359738368, 0, -1. So unlike integer types (such as i32), floating point types can represent non-integer numbers, too.

However, being able to represent this wide range of numbers comes at the cost of precision: floats can only represent some of the real numbers and calculation with floats round to a nearby representable number. For example, 5.0 and 1.0 can be exactly represented as f32, but 1.0 / 5.0 results in 0.20000000298023223876953125 since 0.2 cannot be exactly represented as f32. Note, however, that printing floats with println and friends will often discard insignificant digits: println!("{}", 1.0f32 / 5.0f32) will print 0.2.

Additionally, f32 can represent some special values:

• −0.0: IEEE 754 floating point numbers have a bit that indicates their sign, so −0.0 is a possible value. For comparison −0.0 = +0.0, but floating point operations can carry the sign bit through arithmetic operations. This means −0.0 × +0.0 produces −0.0 and a negative number rounded to a value smaller than a float can represent also produces −0.0.
• ∞ and −∞: these result from calculations like 1.0 / 0.0.
• NaN (not a number): this value results from calculations like (-1.0).sqrt(). NaN has some potentially unexpected behavior:
  • It is not equal to any float, including itself! This is the reason f32 doesn’t implement the Eq trait.
  • It is also neither smaller nor greater than any float, making it impossible to sort by the default comparison operation, which is the reason f32 doesn’t implement the Ord trait.
  • It is also considered infectious as almost all calculations where one of the operands is NaN will also result in NaN. The explanations on this page only explicitly document behavior on NaN operands if this default is deviated from.
  • Lastly, there are multiple bit patterns that are considered NaN. Rust does not currently guarantee that the bit patterns of NaN are preserved over arithmetic operations, and they are not guaranteed to be portable or even fully deterministic! This means that there may be some surprising results upon inspecting the bit patterns, as the same calculations might produce NaNs with different bit patterns.

When the number resulting from a primitive operation (addition, subtraction, multiplication, or division) on this type is not exactly representable as f32, it is rounded according to the roundTiesToEven direction defined in IEEE 754-2008. That means:

• The result is the representable value closest to the true value, if there is a unique closest representable value.
• If the true value is exactly half-way between two representable values, the result is the one with an even least-significant binary digit.
• If the true value’s magnitude is ≥ f32::MAX + 2^{(f32::MAX_EXP − f32::MANTISSA_DIGITS − 1)}, the result is ∞ or −∞ (preserving the true value’s sign).

For more information on floating point numbers, see Wikipedia.

See also the std::f32::consts module.