Clarify story on libm bindings

[alexcrichton]

Currently the f32 and f64 types provide a number of functions that are just bindings to libm (e.g. trigonometric functions). There are many unbound functions, however (see #25780 for some), which can in theory be added over time. It's unclear, however, whether we want to continue this trend and bind all functions or instead try to move away from libm (one possibility being deprecating existing functionality in favor of an external crate).

It would be nice to have a comprehensive understanding on the functions libm provides (beyond those we bind today) and what our story here should be!

[nagisa]

While I’d like to see us move away from libm very much, glibc’s libm has been tuned so much over time it would be very hard to provide comparably accurate, compliant and performant implementations.

On the other hand, there’s also a bunch of functions that could easily be implemented in libcore but are currently bound in libstd. A few examples would be abs, signum, min, max and all the rounding functions.

I’m also really glad we do not bind more obscure functions as tgamma. I believe that they belong in a crate and not stdlib.

[alexcrichton]

Ah yes to be clear I don't think we should reimplement trigonometric functions for example, just perhaps deprecate the in-tree versions for an external set of bindings to libm. The stable usage of the standard library in theory does not need to depend on libm.

[Nashenas88]

Would it be beneficial to put a trait behind some of these? For example, abs, min, and max. Abs could be in std::ops and defined as fn abs<T>(&self) -> T, right? I had trouble with this trying to implement something. I wanted the function to work over all integral types, but there was no way to do this and use abs at the same time.

[steveklabnik]

Triage: I know @japaric has been messing with various aspects of libm, but I don't think it's directly relevant to this issue.

[workingjubilee]

For this matter, I do not believe that the GNU math.h is quite as overwhelmingly tuned for all our supported platforms as suggested, and we also have to consider e.g. inconsistency over musl, msvc, darwin, etc. Being able to have these methods be part of our own libm story is very useful, because it allows consistency across Rust and thus coherently const-evaluating these methods.

In addition, having to depend on an external libm at runtime for these means that we run into issues where e.g. we have a SIMD vector type and are forced to scalarize everything, breaking apart the vector into its components, calling the math.h on each component, and reassembling the vector. For those, we can gain significantly by providing not only libm, but equivalents to the much more niche and underdeveloped "libmvec". These are nuances of how Rust code interacts with floating point that runtimes written for C don't try to handle.

This was discussed last week by T-libs, and one of the concerns that was brought up that it is a lot of code to maintain, and it might be a bad idea to just wholesale add every single method from libm, especially for smaller platforms which might get punished by e.g. code size, and duplicate lookup tables for CORDIC or similar. So adopting any of these would only be a clear win if the overhead of calling a library function itself would be higher than the statically inlined code size. We don't necessarily want this, as a result, for big methods which might use huge tables like cos, sin, atan, etc.

Nonetheless, it might be that for certain comparatively "well-behaved" and easy to implement functions that this is acceptable, and T-libs expressed openness to seeing something happen. This is useful for both the aforementioned functions (abs, min, max) and also e.g. ceil, floor, and trunc, where the answer should be fairly obvious and relatively easy to implement.

It is quite probable we don't want to further expand our bindings to libm within std, however, not even for replacing it. As noted, tgamma is... rather "specialty", even in terms of numeric code.

In other words, the context for this issue includes issues like

• Audit for binary IEEE 754-2008 compliance on relevant platforms #10087
• Tracking issue for f32 and f64 methods in libcore #50145
• float rounding is slow #55107
• Implementation of std::f64::powi function gives inconsistent answers in multiple Rust tool-chains #73920
• extern "platform-intrinsics" float functions often call libm portable-simd#76
• Create a Vector Math library to allow SimdF32::sin and similar to work in core portable-simd#109