ACP: Add float constants for min/max limits of consecutive integers that convert to unique floats

[okaneco]

Proposal

Problem statement

Some ranges of integers can be losslessly round-tripped to and from floating point values but the standard library doesn't easily facilitate doing that.

From<T> for f32 exists for u8, i8, u16, and i16 but TryFrom implementations don't exist for larger integers and are unlikely to be implemented.
as is needed to cast to floating point values but that doesn't offer insight into whether the conversion was lossy or not, likewise for float to integer.

Motivating examples or use cases

These constants can be used to determine whether a value is in range to not lose precision when converting between float/int.

fn to_float_exact(x: u32) -> Option<f32> {
    if x <= f32::MAX_INT.cast_unsigned() {
        Some(x as f32)
    } else {
        None
    }
}

fn to_int_exact(x: f32) -> Option<i32> {
    if x.abs() <= f32::MAX_INT_AS_FLOAT && x.trunc() == x {
        unsafe { Some(x.to_int_unchecked()) }
    } else {
        None
    }
}

Above this range, more than one integer may be rounded to the same floating point value.
For example, 2i32.pow(24) as f32 == (2i32.pow(24) + 1) as f32 evaluates to true.

Solution sketch

Taking f32 as an example, the consecutive range of integers which can be represented exactly in floating point and only have one unique mapping from integer to float consists of the set from -16777215 to 16777215 inclusively, or from -2²⁴+1 to 2²⁴-1 (with 24 being the mantissa digits constant).

While 16777216 can be exactly represented, both 16777216_i32 and 16777217_i32 will convert to 16777216.0.

This definition aligns with the Javascript definition of Number.MAX_SAFE_INTEGER and MIN_SAFE_INTEGER (which would correspond to f64).

impl fN {
    pub const MAX_UNIQUE_INTEGER: iN = (1 << $float::MANTISSA_DIGITS) - 1;
    pub const MIN_UNIQUE_INTEGER: iN = -Self::MAX_UNIQUE_INTEGER;

    // Alternatively, this could be represented as a range::RangeInclusive<Self>
    pub const MAX_UNIQUE_INTEGER_AS_FLOAT: fN = Self::MAX_UNIQUE_INTEGER as Self;
    pub const MIN_UNIQUE_INTEGER_AS_FLOAT: fN = Self::MIN_UNIQUE_INTEGER as Self;
}

Naming is open for discussion.

Alternatives

1. Do nothing.
2. Work on one of the various trait proposals for num conversion in the standard library.
3. Additionally, provide "exact" converting functions between iN/uN and fN using these constants.

Links and related work

Names for this concept in some other languages:

• JavaScript, defined as 2⁵³-1:
  • MDN Number.MAX_SAFE_INTEGER
  • ECMA-262
• Julia, defined as 2^{mantissa_digits}:
  • maxintfloat

Enumeration of how integers are represented when converted to float and the rounding that occurs between exponent ranges
https://en.wikipedia.org/wiki/Single-precision_floating-point_format#Precision_limitations_on_integer_values

The accepted answer here is wrong or incomplete, but the user udoprog provides the proper context for doing this correctly as shown in the playground link
Check if a float can be converted to integer without loss - https://stackoverflow.com/a/48500414
https://play.rust-lang.org/?version=stable&mode=debug&edition=2015&gist=6ccbd5d51c8f2ae11f3b3569ecd0ff55

Internals thread that prompted me to finally write this
https://internals.rust-lang.org/t/pre-acp-tryfrom-for-exact-float-int-conversions/23828

[RFC] Conversions: FromLossy and TryFromLossy traits
rust-lang/rfcs#2484

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[cuviper]

These constants are needed to determine whether a value can be losslessly represented as a float/integer and allow users to handle cases that would lose precision.

Well, cases beyond these limits may lose precision -- but some are still lossless, like 16777218 that you mentioned. Even with the limit values you've given, note that 1 << n is a n+1-bit number, so with n=MANTISSA_DIGITS this is already relying on an implicit trailing zero beyond the actual mantissa's significant bits.

I agree these are the limits of consecutive integers though.

For non-consecutive lossless integers, we could compute the number of significant bits needed like:

impl uN {
    fn significant_bits(self) -> u32 {
        if self == 0 {
            0
        } else {
            Self::BITS - self.leading_zeros() - self.trailing_zeros()
        }
    }
}

impl iN {
    fn significant_bits(self) -> u32 {
        self.unsigned_abs().significant_bits()
    }
}

So 16777218 fits in f32 with 24 significant bits, but 16777217 needs 25.

[scottmcm]

pub const MAX_INTEGER_AS_FLOAT: fN = ...

Note that we don't need new constants to define this; it's 2.0 / Self::EPSILON. https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=7b749dddc16fcae4859952a849c0ed71

Said otherwise, it's the one value where x.next_up() - x == 2.0 and x - x.next_down() == 1.0. So I wonder if there's a name phrasing on the "ULP of 1 or less" that could work.

I do like the point that this isn't "the max representable integer", since all values >= 1.0 / EPSILON are integers (well, other than +∞ where it's hard to say).

---

Hmm, could also consider using things other than just scalars. Something like

const INTEGER_RANGE: range::RangeInclusive<Self> = -2.0 / Self::EPSILON..=2.0 / Self::EPSILON;

could potentially work, as the range in which the float works fine as an integer type.

[programmerjake]

imo we should have actual constants for this since writing 2.0 / fN::EPSILON is not obvious

[programmerjake]

names for this constant in some other languages:

• JavaScript: Number.MAX_SAFE_INTEGER
• Julia: maxintfloat

[okaneco]

names for this constant in some other languages:

• JavaScript: Number.MAX_SAFE_INTEGER

Thanks for those references, I couldn't remember which language had the definition that Javascript uses and had trouble searching for it.

In Javascript, MAX_SAFE_INTEGER is defined as as 2⁵³-1 which has an additional property that we might want too:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger#description

An integer n is a "safe integer" if and only if the Number value for n is not the Number value for any other integer.

---

I've updated the proposal addressing some of the feedback. The naming part is still challenging since "safe" has a different meaning.

• I've changed the definition to align with the Javascript "min/max safe integer" definitions, ±(2^{mantissa_digits}-1). I think the property of a unique mapping for each integer to each float is nice to have, but I'm fine if the larger consecutive range is preferred.
• Removed "representable" verbiage since it's wrong/misleading

[hanna-kruppe]

Is there any use case for these constants other than the range check of lossless conversions? If not, I think it’s better to provide the conversions directly. Just providing the constants (with one particular type!) doesn’t make it trivial to implement the lossless conversion correctly, so as a user I’d still define my own helper functions/extension traits (or import a third party library) for it, and in that case the constants might as well live there instead of in std.

[kennytm]

i think both the conversion function and the constants are useful e.g. you can refer to the constant in the conversion error message.