floating-point NaN payload functions

[phayes]

Proposal

Some background reading on NaN payloads for those unfamiliar: https://www.codegenes.net/blog/why-does-ieee-754-reserve-so-many-nan-values

Problem statement

Rust exposes floating-point bit patterns through to_bits() and from_bits(), but it does not provide a direct hard-to-misuse way to get or set the payload bits of a NaN. This currently leaves every user who wants to use NaN payloads to implenent their own solution using to_bits(), from_bits(), and low-level bit-twiddling. This current approach is error prone.

Given that NaN payloads are an official part of the standard ( See IEEE 754-2019 3.5.2 and 9.7.0), they should be properly supported by the rust standard lilbrary.

Motivating examples or use cases

Some software uses NaN payloads as a compact metadata channel for values that are already represented as floating-point numbers. A common pattern is NaN-boxing or tagging schemes, where certain non-number cases are represented by quiet NaNs carrying payload bits.

Some possible modivating examples:

1. A NaN payload might contain an application specific error code that encodes the reason why that value is a NaN.
2. A NaN payload might contain the ID of the sensor that produced the NaN value
3. My specific use-case is in real-time audio processing, where I wish to use it to communicate signalling metadata (num channels, sample rate etc) within an f32 audio stream. I am in a very contrained environment and wish to avoid the overhead of using an enum.

This proposal is not motivated by arithmetic semantics. Rust explicitly documents that arithmetic operations may choose NaN payloads non-deterministically from a constrained set, and that results do not generally preserve a chosen payload. NaN payoads should not be expected to survive any arithmetic operation.

Solution sketch

/// Errors that can occur when setting a NaN payload.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SetNanPayloadError {
    /// The value is not a NaN.
    NotNan,
    /// The provided payload does not fit within the available payload bits.
    PayloadOutOfRange,
}

impl f32 {
    /// Returns the payload bits of this NaN, if the value is NaN.
    ///
    /// The payload does not include the sign bit or the quiet/signaling bit.
    /// For `f32`, the payload is 22 bits wide.
    ///
    /// Returns `None` if this value is not NaN.
    ///
    /// # Examples
    ///
    /// ```
    /// let x = f32::NAN.set_nan_payload(5).unwrap();
    /// assert_eq!(x.get_nan_payload(), Some(5));
    ///
    /// let x = 1.0f32;
    /// assert_eq!(x.get_nan_payload(), None);
    /// ```
    pub fn get_nan_payload(&self) -> Option<u32>;

    /// Returns a new NaN with the payload bits set to `payload`.
    ///
    /// This function only succeeds if `self` is NaN and `payload` fits within
    /// the available payload bits (22 bits for `f32`).
    ///
    /// The sign bit and the quiet/signaling state of the NaN are preserved.
    /// Only the payload bits are modified.
    ///
    /// # Errors
    ///
    /// - Returns [`SetNanPayloadError::NotNan`] if `self` is not NaN.
    /// - Returns [`SetNanPayloadError::PayloadOutOfRange`] if `payload`
    ///   does not fit within 22 bits.
    ///
    /// # Examples
    ///
    /// ```
    /// let x = f32::NAN.set_nan_payload(7).unwrap();
    /// assert_eq!(x.get_nan_payload(), Some(7));
    /// ```
    ///
    /// # Notes
    ///
    /// This method operates purely on the bit-level representation of the float.
    /// No guarantees are made about preservation of payload bits through
    /// arithmetic operations.
    pub fn set_nan_payload(self, payload: u32) -> Result<f32, SetNanPayloadError>;
}

impl f64 {
    /// Returns the payload bits of this NaN, if the value is NaN.
    ///
    /// The payload does not include the sign bit or the quiet/signaling bit.
    /// For `f64`, the payload is 51 bits wide.
    ///
    /// Returns `None` if this value is not NaN.
    ///
    /// # Examples
    ///
    /// ```
    /// let x = f64::NAN.set_nan_payload(5).unwrap();
    /// assert_eq!(x.get_nan_payload(), Some(5));
    ///
    /// let x = 1.0f64;
    /// assert_eq!(x.get_nan_payload(), None);
    /// ```
    pub fn get_nan_payload(&self) -> Option<u64>;

    /// Returns a new NaN with the payload bits set to `payload`.
    ///
    /// This function only succeeds if `self` is NaN and `payload` fits within
    /// the available payload bits (51 bits for `f64`).
    ///
    /// The sign bit and the quiet/signaling state of the NaN are preserved.
    /// Only the payload bits are modified.
    ///
    /// # Errors
    ///
    /// - Returns [`SetNanPayloadError::NotNan`] if `self` is not NaN.
    /// - Returns [`SetNanPayloadError::PayloadOutOfRange`] if `payload`
    ///   does not fit within 51 bits.
    ///
    /// # Examples
    ///
    /// ```
    /// let x = f64::NAN.set_nan_payload(7).unwrap();
    /// assert_eq!(x.get_nan_payload(), Some(7));
    /// ```
    ///
    /// # Notes
    ///
    /// This method operates purely on the bit-level representation of the float.
    /// No guarantees are made about preservation of payload bits through
    /// arithmetic operations.
    pub fn set_nan_payload(self, payload: u64) -> Result<f64, SetNanPayloadError>;
}

Alternatives

Alternative 1. Do nothing.

Currently users need to do something like this:

fn nan_payload_f32(x: f32) -> Option<u32> {
    let bits = x.to_bits();
    let exp_mask = 0x7f80_0000;
    let frac_mask = 0x007f_ffff;
    let quiet_mask = 0x0040_0000;

    if bits & exp_mask != exp_mask || bits & frac_mask == 0 {
        return None;
    }

    Some(bits & (frac_mask ^ quiet_mask))
}

fn with_nan_payload_f32(x: f32, payload: u32) -> f32 {
    let sign = x.to_bits() & 0x8000_0000;
    let exp  = 0x7f80_0000;
    let quiet = 0x0040_0000;
    let payload = payload & 0x003f_ffff;
    f32::from_bits(sign | exp | quiet | payload)
}

Alternative 2. Implement exactly as the standard suggests.

The IEEE Std 754-2019 says the following:

9.7 NaN payload operations 9.7.0
Language standards should define the following homogeneous quiet-computational operations to provide generic
access to payloads. These operations signal no exceptions.
  ― sourceFormat getPayload(source)
       If the source operand is a NaN, the result is the payload as a non-negative floating-point integer.
       If the source operand is not a NaN, the result is −1.
       The preferred exponent is 0.
  ― sourceFormat setPayload(source)
      If the source operand is a non-negative floating-point integer whose value is one of an
      implementation-defined set of admissible payloads for the operation, 
      the result is a quiet NaN with that payload. Otherwise, the result is +0, with a preferred exponent of 0.
  ― sourceFormat setPayloadSignaling(source)
      If the source operand is a non-negative floating-point integer whose value is one of an 
      implementation-defined set of admissible payloads for the operation, the result is a 
      signaling NaN with that payload. Otherwise, the result is +0, with a preferred exponent of 0.

NOTE — An implementation may restrict the payloads that can be set. Thus getPayload might return a
value that is not an admissible operand for setPayload or setPayloadSignaling. (A program can check by
applying the isNaN operation to the result of setPayload or setPayloadSignaling.)

**should** indicates that among several possibilities, one is recommended as particularly suitable, 
without mentioning or excluding others; or that a certain course of action is preferred
but not necessarily required; 

We could adhere exactly as the standard suggests, so the error type would not include NotNan and instead signal this error by returning −1. I think this is undesirable since we are returning a Result anyways for an invalid payload (which is allowed as per the standard), so we might as well make use of it for all error conditions.

Alternative 3. Implement as a crate.

This could be implemented as a crate, but I do not see any "float_util" crates or similar where it would naturally fit. On it's own it's a bit small to justfiy a full standalone crate.

Links and related work

1. https://www.codegenes.net/blog/why-does-ieee-754-reserve-so-many-nan-values
2. EEE Std 754-2019
3. D programming language GetNanPayload, NaN with payload
4. glibc NAN Payload operations

[phayes]

I'd be happy to create either a test crate or a PR directly against the rust standard library, depending on how folks want to approach this.

[tgross35]

For the C prior art, getpayload and setpayload are part of C23. I can't find any docs online so here's from the spec:

// Return the payload as an integer float if a NaN, -1.0 otherwise
double getpayload(const double *x);

// Store a qNaN with `pl` payload to `res`. Returns nonzero on success, zero if
// the payload is not representable.
int setpayload(double *res, double pl);

// Same as the above but works with a signaling NaN.
int setpayloadsig(double *res, double pl);

And there is the older double nan( const char*); that parses a string.

They're following the IEEE spec of using integer-valued floats to represent the payload. I wonder if this is to get around the lack of an obvious integer for types like long double/_Float64x and _Float128? Seems like an inconvenience for most cases.

[kennytm]

    pub fn get_nan_payload(&self) -> Option<u32>;

why is self passed by-reference rather than by-copy? i think copying is bit-pattern preserving.

    pub fn set_nan_payload(self, payload: u32) -> Result<f32, SetNanPayloadError>;

rust currently does not have an SNaN constant, making an SNaN with payload is no easier than f32::from_bits. calling this always with f32::NAN feels silly. so i think these are better as constructors

    pub fn nan_with_payload(payload: u32) -> Option<f32>;
    pub fn signaling_nan_with_payload(payload: NonZero<u32>) -> Option<f32>;

[tgross35]

For our implementation, I think signatures like this may make more sense (sorry Kenny, had this typed before seeing yours):

impl fX {
    /// `None` if YaN
    pub const fn nan_payload(self) -> Option<uX>;
    /// `None` if out of range
    pub const fn nan(payload: u32) -> Option<fX>;
}

There doesn't seem to be much point to taking self in set_nan_payload/nan if the only thing may preserve is is the sign bit and signaling bit. You can just .copysign(-1) if needed, and working with sNaNs is rare enough that I think it's fine to require doing something bitwise.

---

An alternative that I kind of like: rather than treating the quiet bit as something magic, just consider it part of the payload. Separately, provide a quiet bit constant.

impl fX {
    const QUIET_NAN_MASK: uX; /* 0b00000010_00000000 for f16 */

    // Returns `self & Self::MANTISSA_MASK` if NaN
    pub const fn nan_payload(self) -> Option<NonZero<uX>>;

    // Must have at least one bit set, `QUIET_NAN_MASK` if you want a normal qNaN.
    //
    // `None` indicates out of range.
    pub const fn nan(payload: NonZero<uX>) -> Option<fX> 
}

Couple of reasons:

1. Rust doesn't really need to care about what is a sNaN vs. a qNaN
2. It gives a sNaN constructor that we don't currently have
3. You can also construct unusual NaNs like for MIPS prior to EF_MIPS_NAN2008, where sNaN and qNaN are flipped
4. NonZero makes the requirements clear and eliminates one error condition that might surprise users. (Compared to this proposal but taking a uX rather than NonZero<uX>)

There is also some chance that the next IEEE 754 rev says it's okay to not support sNaNs and instead just treat it as any other payload, which I think this maps well to. This is also more or less how Rust already treats sNaNs in many places. (Basically just a rumor at this point so this may not be worth too much weight.)

[phayes]

Appreciate the comments!

I like the idea of functions that just give back a nan-with-payload as constructors.

I dont like the idea of including the signalling bit inside the payload. If conflates two different concepts (both NaN related but different conceptually). The spec even suggests having different "setPayload" and "setPayloadSignaling" functions that give back either a silent NaN or signalling NaN as seperate functions.

If we're going to introduce sNaN support, it might make sense to have a convenience function that can set the sNaN / qNaN bit without specifying whether you're setting it to quiet or signalling (keeping it somewhat platform independent). But I think sNaN support is orthagonal and different to payload support.

So I would propose either @kennytms' suggestion of either:

    pub fn nan_with_payload(payload: u32) -> Option<f32>;
    pub fn signaling_nan_with_payload(payload: NonZero<u32>) -> Option<f32>;

Or combine them into a single function

/// Creates an `f32` NaN (Not-a-Number) value with an explicit quiet / signalling bit, and a custom payload.
///
/// The `quiet_bit` controls whether the NaN is quiet or signalling:
/// - `true` typically produces a *quiet NaN (qNaN)*
/// - `false` typically produces a *signalling NaN (sNaN)*
///
/// Note that the interpretation of this bit is not fully consistent across all
/// platforms and hardware. Some architectures may use the opposite convention,
/// so the resulting NaN may be treated differently depending on the target.
///
/// The `payload` provides the NaN payload bits. For `f32`, the payload is limited
/// to 22 bits. The maximum allowed value is therefore `4_194_303` (2²² − 1).
///
/// # Returns
/// - `Some(f32)` containing the constructed NaN if `payload` is within range
/// - `None` if `payload` exceeds the 22-bit limit
///
/// # Notes
/// - The exact bit-level behavior of NaNs, especially signalling NaNs, may be
///   altered by compiler optimizations or hardware during arithmetic operations.
/// - Payload preservation is not guaranteed across operations.
pub fn create_nan(quiet_bit: bool, payload: u32) -> Option<Self>

impl f32 {
    /// Returns the value of the “quiet bit” of this floating-point number.
    ///
    /// The quiet bit is used to distinguish quiet NaNs from signalling NaNs in
    /// IEEE-754 representations.
    ///
    /// # Returns
    /// - `Some(true)` or `Some(false)` if the value is a NaN and the quiet bit
    ///   can be meaningfully read.
    /// - `None` if the value is not a NaN.
    ///
    /// # Semantics
    /// On most platforms, `true` indicates a *quiet* NaN and `false` indicates a
    /// *signalling* NaN. Some platforms use the opposite convention.
    ///
    /// This function exposes the raw bit value without interpreting it beyond
    /// the current platform’s representation.
    ///
    /// # Portability
    /// The meaning of the returned boolean is not portable. Do not rely on
    /// `true` or `false` consistently mapping to quiet or signalling NaNs across
    /// different architectures or targets.
    pub const fn get_nan_quiet_bit(self) -> Option<bool>

    /// Returns the payload bits of this NaN, if the value is NaN.
    ///
    /// The payload does not include the sign bit or the quiet/signaling bit.
    ///
    /// Returns `None` if this value is not NaN.
    pub const fn get_nan_payload(self) -> Option<u32>
}

I think it makes a bit more sense to combine them into a single create_nan function since then we dont' need to commit to a specific semantic interpretation of true vs false for qNaN vs sNaN.

The other alternative I suppose is to be explicit about the signalling bit, something like this:

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum NanKind {
    Signalling,
    Quiet,
}

impl NanKind {
    #[inline]
    pub const fn from_bit(bit: bool) -> Self {
        #[cfg(not(any(
            target_arch = "mips",
            target_arch = "mips64",
            target_arch = "mips32r6",
            target_arch = "mips64r6",
        )))]
        {
            // standard convention
            if bit {
                Self::Quiet
            } else {
                Self::Signalling
            }
        }

        #[cfg(any(
            target_arch = "mips",
            target_arch = "mips64",
            target_arch = "mips32r6",
            target_arch = "mips64r6",
        ))]
        {
            // reversed convention
            if bit {
                Self::Signalling
            } else {
                Self::Quiet
            }
        }
    }

    #[inline]
    pub const fn to_bit(self) -> bool {
        #[cfg(not(any(
            target_arch = "mips",
            target_arch = "mips64",
            target_arch = "mips32r6",
            target_arch = "mips64r6",
        )))]
        {
            // standard convention
            matches!(self, Self::Quiet)
        }

        #[cfg(any(
            target_arch = "mips",
            target_arch = "mips64",
            target_arch = "mips32r6",
            target_arch = "mips64r6",
        ))]
        {
            // reversed convention
            matches!(self, Self::Signalling)
        }
    }
}

impl From<bool> for NanKind {
    #[inline]
    fn from(value: bool) -> Self {
        Self::from_bit(value)
    }
}

impl From<NanKind> for bool {
    #[inline]
    fn from(value: NanKind) -> Self {
        value.to_bit()
    }
}

I think I prefer the simpler version without an NanKind enum and just leave it up to the user to interpret it. Thoughts?

[tgross35]

I dont like the idea of including the signalling bit inside the payload. If conflates two different concepts (both NaN related but different conceptually). The spec even suggests having different "setPayload" and "setPayloadSignaling" functions that give back either a silent NaN or signalling NaN as seperate functions.

If we're going to introduce sNaN support, it might make sense to have a convenience function that can set the sNaN / qNaN bit without specifying whether you're setting it to quiet or signalling (keeping it somewhat platform independent). But I think sNaN support is orthagonal and different to payload support.

I'm not convinced that we need to add any API reinforcing the idea that sNaN is a distinct concept. It's a bit of a legacy misfeature that Rust/LLVM doesn't really thoroughly support, and is inconsistent across platforms. IMO it's easier to explain to users that a NaN payload can be anything other than zero, but the top bit is lossy through many operations. Which disagrees with the spec's setPayloadSignaling, but we already deviate from the spec in every possible aspect related to sNaNs so I don't see this as the biggest loss.

So I'd prefer either something where the quiet bit is treated as part of the payload, or only supporting qNaNs.

[phayes]

So I'd prefer either something where the quiet bit is treated as part of the payload, or only supporting qNaNs.

I think it could be confusing / surprising for those not deeply familiar with the intricacies of floats to have part of the payload change unexpectedly, so I think "only supporting qNaNs" is the right choice here.

So in that case we would only have:

pub fn nan_with_payload(payload: u32) -> Option<f32>;
impl f32 {
   pub fn get_nan_payload(self) -> Option<u32>
}

I would be supportive of this!

[tgross35]

Note that convention is typically to omit the get_ prefix, and the constructor should also be an associated function. But other than that, yeah I think that’s fine.

[programmerjake]

So I'd prefer either something where the quiet bit is treated as part of the payload, or only supporting qNaNs.

I think future Rust will gain support for LLVM's strictfp mode, where it does properly implement IEEE 754 including the intricacies around signaling NaNs and rounding modes and FP exceptions (though it may be buggy on x87 and old mips), so we should not build the assumption that signaling NaNs never matter into our APIs.

[phayes]

I think future Rust will gain support for LLVM's strictfp mode, where it does properly implement IEEE 754 including the intricacies around signaling NaNs and rounding modes and FP exceptions (though it may be buggy on x87 and old mips), so we should not build the assumption that signaling NaNs never matter into our APIs.

Thanks @programmerjake . So I think this proposal would work:

impl f32 {
   pub fn nan_with_payload(payload: u32) -> Option<f32>; // returns qNaN
   pub fn nan_payload(self) -> Option<u32>
}

If / when in the future rust gets support for strictfp, we could add:

impl f32 {
   pub fn signalling_nan_with_payload(payload: u32) -> Option<f32>; // returns sNaN
}

But we wouldn't worry about implementing signalling_nan_with_payload now, but keep it as a possible future addition.

Does that make sense to you @programmerjake ?

[programmerjake]

I'd be fine with the option to declare the quiet/signaling to just be the top bit of the payload, I'm less fine with saying qNaN is all you could ever need.

[programmerjake]

maybe we should instead just phrase it as set_mantissa (or significand if you prefer), so you set the NaN payload with f32::NAN.set_mantissa(my_nonzero_payload)

[phayes]

I'd be fine with the option to declare the quiet/signaling to just be the top bit of the payload, I'm less fine with saying qNaN is all you could ever need.

Could you explain a bit more about your thinking?

I would imagine that if rust ever gets strictfp, we would want to be more explicit about separating the concept of payload from the concept of the quiet / signalling bit, since having them together as "payload" could result in the user accidentally setting the signalling bit and resulting in unintended traps / exceptions. In other words, if we ever supported strictfp, we would actually to clearly separate the concepts of quiet-bit and payload in the API for users to avoid accidental misuse and surprising side-effects.

I guess there a tension between "API surface that doesn't make assumptions about qNAN / sNAN / payload" and "api that is hard to misuse". Can we find the right balance?