ACP: Add constants `f32::BITS` and `f64::BITS`

[tyhdefu]

Proposal

Problem statement

I am writing a virtual machine for a virtual assembly language which allows different sized registers, that means it supports many different widths of integers and floats, such as u11, u32, u64, f32, f64.
Obviously, emulating u32 is easy, whereas u11 needs much more complicated logic.
I special case these using match statements so I need to have constants and ideally these should be short and obviously correct.

Another potential use case is when reading from a binary file, but I haven't personally needed these constants then, so I won't discuss them here.

Motivating examples or use cases

For integers this comes out cleanly as:

match width {
   u32::BITS => compute<u32>() // Arithmetic using u32s
   u64::BITS => compute<u64>() // Arithmetic using u64s
   _ => {} // Arbitrary precision 

However for floats I currently have

match width {
    32 => compute<f32>() // Arithmetic using f32s
    64 => compute<f64>() // Arithmetic using f64s
    _ => {} // Arbitrary precision floats
}

Additionally to store these effectively I have special data structures for these primitives, which looks roughly like:

fn store(width: u32, index: u32, val: f32) {
    assert_eq!(width == 32)
}

It would be nice if here I could assert (as I do with u32, u64, i32, i64):

assert_eq!(width == f32::BITS)

This shows intent much more clearly.

Solution sketch

Add f32::BITS and f64::BITS constants:

impl f32 {
    pub const BITS: u32 = 32;
}

impl f64 {
    pub const BITS: u32 = 64;
}

u32 is already used as the type for BITS for signed and unsigned primitives, so we should keep it the same.

This brings f32 and f64 in line with other primitives: u8, u32, u64, i8, i32, i64.
The documentation for f32 specifically defines it as a A 32-bit floating-point type - this just introduces a constant for it.
Additionally, to_le_bytes, is already defined as returning [u8; 4] so the size is already well-specified.

https://doc.rust-lang.org/std/primitive.u32.html#associatedconstant.BITS

Alternatives

Of course, a user constant could easily be defined as F32_BITS but this would have to be imported in every file and not be as clear.
They could also define a trait and bring it into scope that defined these constants.

Additionally, for some use-cases, using size_of<T>() might be sufficient, however this does not work for my use case since it can't be used in a match expression and returns something of type usize instead of u32, which doesn't match u32::BITS.
Additionally, I understand size_of more as how much memory space is used not an indication of "precision":

More specifically, this is the offset in bytes between successive elements in an array with that item type including alignment padding. Thus, for any type T and length n, [T; n] has a size of n * size_of::() - https://doc.rust-lang.org/std/mem/fn.size_of.html

In a hypothetical case where there was a f4 introduced, size_of would give 1 byte due to padding.

Obviously I understand this is low-hanging fruit, but it would be nice to have a more uniform API between floats and integers.

Links and related work

Java defines a BYTES constant for floats and doubles:

• https://docs.oracle.com/javase/8/docs/api/java/lang/Float.html#BYTES
• https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html#BYTES

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.

[tgross35]

I've wanted these for simple things like writing macros that cover all the types.

If accepted, please add these for f16 and f128 as well.

[programmerjake]

if you copied it out of your code, I spotted a bug:
64 => compute<f32>() // Arithmetic using f64s
looks like you meant to use f64 but wrote f32 again.

[tyhdefu]

if you copied it out of your code, I spotted a bug: 64 => compute<f32>() // Arithmetic using f64s looks like you meant to use f64 but wrote f32 again.

Oops - I had simplified my actual code - compute actually takes a few parameters, but I've fixed the code in the issue.

[kpreid]

An alternative to adding these constants is to use size_of::<f32>() * 8 instead. A possible justification for this is that uXX::BITS is a number directly related to the range of possible values, whereas the bit size of f32 and f64 does not so directly relate (at a minimum, you also need to know the split between the significand and exponent) and so fXX::BITS is only useful as an alternate description of the size_of rather than as a numeric quantity closely related to the numeric range of the type.

I don’t think this is a very good justification for not adding them, but perhaps it should be mentioned and rejected in the alternatives, or some piece of it might be useful for discussion.

[hanna-kruppe]

(at a minimum, you also need to know the split between the significand and exponent)

FWIW, fN::MANTISSA_DIGITS already exists and determines the exponent/significand split together with the proposed fN::BITS. Though in my experience trying to do any bit pattern manipulation with these kinds of constants is awkward at best.

[programmerjake]

I'll note that I'm hoping Rust adds generic bit-width integers where if you have a bit-width that's not a multiple of 8 then Int::BITS != size_of::<Int>() * 8.

[tyhdefu]

An alternative to adding these constants is to use size_of::<f32>() * 8 instead. A possible justification for this is that uXX::BITS is a number directly related to the range of possible values, whereas the bit size of f32 and f64 does not so directly relate (at a minimum, you also need to know the split between the significand and exponent) and so fXX::BITS is only useful as an alternate description of the size_of rather than as a numeric quantity closely related to the numeric range of the type.

Its a very good point to be made, so I've listed it as an alternative and why it doesn't quite meet my needs for this problem - size_of is more of an indication of how much memory will be used by a given structure (including padding). So for a hypothetical, but not impossible f4 (rust-lang/rfcs#3686) I would want 4 bits (not 1 byte).
For my problem, what I care about is the precision in general, using f64s when 64-bit precision is requested and f32s when 64-bits are requested.

However my use-case is obviously niche and for most applications a size_of would likely suffice.

[cuviper]

For my problem, what I care about is the precision in general, using f64s when 64-bit precision is requested and f32s when 64-bits are requested.

Isn't MANTISSA_DIGITS a better measure of float precision though?

[the8472]

Note that there are two different 16bit floats in common use: bf16 and f16

[joshtriplett]

We discussed this in today's @rust-lang/libs-api meeting, and agreed to accept this. We'd be happy to see a PR adding fN::BITS = N for each N.

[joshtriplett]

Please close this when you open a tracking issue.