# Struct Subspace :: sus :: num :: f64

A 64-bit floating point type.

This type is very similar to `f32`

, but has increased precision by using
twice as many bits.
Specifically, this type holds the same values
as the `double`

type specified by the C++ standard.

See the namespace level documentation for more.

# Static Data Members

Machine epsilon value for `f64`

.

This is the difference between 1.0 and the next larger representable number.

Approximate number of significant digits in base 2.

Maximum possible power of 10 exponent.

Largest finite primitive value.

Minimum possible normal power of 10 exponent.

Smallest positive normal `f64`

value.

Smallest finite primitive value.

Not a Number (NaN).

Note that IEEE-745 doesn't define just a single NaN value; a plethora of bit patterns are considered to be NaN. Furthermore, the standard makes a difference between a "signaling" and a "quiet" NaN, and allows inspecting its "payload" (the unspecified bits in the bit pattern). This constant isn't guaranteed to equal to any specific NaN bitpattern, and the stability of its representation over Subspace versions and target platforms isn't guaranteed.

This value is not constexpr because the value can differ in a constexpr evaluation context from a runtime context, leading to bugs.

Negative infinity.

# Static Methods

Construction from primitive types where no bits are lost.

Construction from floating point types where no bits are lost.

Default constructor, which sets the value to 0.

Satisfies the `Default`

concept.

Construction from floating point types where no bits are lost.

Construction from primitive floating point types where no bits are lost.

Construction from integer types where no bits are lost.

For `f32`

this includes integer types up to 16 bits.
For `f64`

this includes integer types up to 32 bits.

Construction from integer types where no bits are lost.

For `f32`

this includes integer types up to 16 bits.
For `f64`

this includes integer types up to 32 bits.

Create a floating point value from its representation as a byte array in big endian.

See `from_bits`

for why this function is
not constexpr.

Raw transmutation from `##_unsigned##`

.

This is identical to `std::bit_cast<f32, u32>`

, or
`std::bit_cast<f64, u64>`

. It turns out this is incredibly portable, for two
reasons:

- Floats and Ints have the same endianness on all modern platforms.
- IEEE 754 very precisely specifies the bit layout of floats.

However there is one caveat: prior to the 2008 version of IEEE 754, how to interpret the NaN signaling bit wasn’t actually specified. Most platforms (notably x86 and ARM) picked the interpretation that was ultimately standardized in 2008, but some didn’t (notably MIPS). As a result, all signaling NaNs on MIPS are quiet NaNs on x86, and vice-versa.

Rather than trying to preserve signaling-ness cross-platform, this implementation favors preserving the exact bits. This means that any payloads encoded in NaNs will be preserved even if the result of this method is sent over the network from an x86 machine to a MIPS one.

If the results of this method are only manipulated by the same architecture that produced them, then there is no portability concern.

If the input isn’t NaN, then there is no portability concern.

If you don’t care about signalingness (very likely), then there is no portability concern.

Note that this function is distinct from `Cast`

casting, which
attempts to preserve the *numeric* value, and not the bitwise value.

# Examples

```
auto v = f32::from_bits(0x41480000);
sus::check!(v, 12.5);
```

This function is not constexpr, as converting a NaN does not preserve the exact bits in a constexpr context.

Create a floating point value from its representation as a byte array in big endian.

See `from_bits`

for why this function is
not constexpr.

Create a floating point value from its representation as a byte array in native endian.

As the target platform's native endianness is used, portable code likely
wants to use `from_be_bytes`

or
`from_le_bytes`

, as appropriate
instead.

See `from_bits`

for why this function is
not constexpr.

Constructs a `f64 `

from an `Iterator`

by
computing the product of all elements in the iterator.

This method should rarely be called directly, as it is used to satisfy the
`Product`

concept so that
`Iterator::product()`

can be
called for iterators over `f64 `

.

Constructs a `f64 `

from an
`Iterator`

by computing the sum of all elements in
the iterator.

This method should rarely be called directly, as it is used to satisfy the
`Sum`

concept so that
`Iterator::sum()`

can be called for
iterators over `f64 `

.

# Methods

Computes the arccosine of a number. Return value is in radians in the range [0, pi] or NaN if the number is outside the range [-1, 1].

Inverse hyperbolic cosine function, or NaN if the number is less than -1.

Returns a mutable pointer to the underlying C++ primitive value type.

This allows Subspace numerics be used with APIs that expect a pointer to a C++ primitive type.

Returns a const pointer to the underlying C++ primitive value type.

This allows Subspace numerics be used with APIs that expect a pointer to a C++ primitive type.

Computes the arcsine of a number. Return value is in radians in the range [-pi/2, pi/2] or NaN if the number is outside the range [-1, 1].

Inverse hyperbolic sine function.

Computes the arctangent of a number. Return value is in radians in the range [-pi/2, pi/2];

Computes the four quadrant arctangent of self (y) and other (x) in radians.

- x = 0, y = 0: 0
- x >= 0: arctan(y/x) -> [-pi/2, pi/2]
- y >= 0: arctan(y/x) + pi -> (pi/2, pi]
- y < 0: arctan(y/x) - pi -> (-pi, -pi/2)

Returns NaN if both `self`

and `other`

are 0.

Inverse hyperbolic tangent function.

Returns the cube root of a number.

Returns the smallest integer greater than or equal to self.

Restrict a value to a certain interval unless it is NaN.

Returns max if self is greater than max, and min if self is less than min. Otherwise this returns self.

Note that this function returns NaN if the initial value was NaN as well.

# Panics

Panics if min > max, min is NaN, or max is NaN.

Returns the floating point category of the number.

If only one property is going to be tested, it is generally faster to use the specific predicate instead.

Returns a number composed of the magnitude of self and the sign of sign.

Equal to self if the sign of self and sign are the same, otherwise equal to -self. If self is a NaN, then a NaN with the sign bit of sign is returned. Note, however, that conserving the sign bit on NaN across arithmetical operations is not generally guaranteed.

Computes the cosine of a number (in radians).

Hyperbolic cosine function.

Calculates Euclidean division, the matching method for
`rem_euclid`

.

This computes the integer `n`

such that `self = n * rhs + self.rem_euclid(rhs)`

. In other words, the result is `self / rhs`

rounded
to the integer `n`

such that `self >= n * rhs`

.

Returns `e^(self)`

, (the exponential function).

Returns `2^(self)`

.

Returns `e^(self) - 1`

in a way that is accurate even if the number is
close to zero.

Returns the largest integer less than or equal to self.

Calculates the length of the hypotenuse of a right-angle triangle given legs of length x and y.

Returns true if this number is neither infinite nor NaN.

Returns true if this value is positive infinity or negative infinity, and false otherwise.

Returns true if this value is NaN.

Returns true if the number is neither zero, infinite, subnormal, or NaN.

Returns true if self has a negative sign, including -0.0, NaNs with negative sign bit and negative infinity.

Note that IEEE-745 doesn't assign any meaning to the sign bit in case of a NaN

Returns true if self has a positive sign, including +0.0, NaNs with positive sign bit and positive infinity.

Note that IEEE-745 doesn't assign any meaning to the sign bit in case of a NaN.

Returns true if the number is subnormal.

Returns the natural logarithm of the number.

Returns ln(1+n) (natural logarithm) more accurately than if the operations were performed separately.

Returns the logarithm of the number with respect to an arbitrary base.

The result might not be correctly rounded owing to implementation details; self.log2() can produce more accurate results for base 2, and self.log10() can produce more accurate results for base 10.

Returns the base 10 logarithm of the number.

Returns the base 2 logarithm of the number.

Returns the maximum of the two numbers, ignoring NaN.

If one of the arguments is NaN, then the other argument is returned.

Returns the minimum of the two numbers, ignoring NaN.

If one of the arguments is NaN, then the other argument is returned.

Fused multiply-add. Computes `(self * a) + b`

with only one rounding
error, yielding a more accurate result than an unfused multiply-add.

Using mul_add may be more performant than an unfused multiply-add if the target architecture has a dedicated fma CPU instruction. However, this is not always true, and will be heavily dependent on designing algorithms with specific target hardware in mind.

Returns the next representable value of the float type after `self`

in the
direction of `toward`

. If `self == toward`

, `toward`

is returned. If either
`self`

or `toward`

is NAN, NAN is returned.

This is implemented by the cmath library, see the documentation for details on errors.

Raises a number to a floating point power.

Raises a number to an integer point power.

Using this function may be faster than using `powf`

. It
might have a different sequence of rounding operations than
`powf`

, so the results are not guaranteed to agree.

Takes the reciprocal (inverse) of a number, `1/x`

.

Calculates the least nonnegative remainder of `self (mod rhs)`

.

In particular, the return value `r`

satisfies `0.0 <= r < rhs.abs()`

in
most cases. However, due to a floating point round-off error it can
result in `r == rhs.abs()`

, violating the mathematical definition, if
`self`

is much smaller than `rhs.abs()`

in magnitude and `self < 0.0`

.
This result is not an element of the function's codomain, but it is the
closest floating point number in the real numbers and thus fulfills the
property `self == self.div_euclid(rhs) * rhs + self.rem_euclid(rhs)`

approximately.

Returns the nearest integer to `self`

. If a value is half-way between two
integers, round away from `0.0`

.

This rounding behaviour matches the behaviour of the `std::round`

standard library
function, but is much slower and less conformant than `round_ties`

which often makes the latter a better
choice.

If `self`

is a `NaN`

, infinity, or zero, the same will be returned, though
a different `NaN`

may be returned.

As in Rust's `round`

,
this method preserves the sign bit when the result is `-0.0`

, but this is
unlike `std::round`

.

Returns the nearest integer to `self`

. If a value is half-way between two
integers, respects the current rounding mode. The default mode
will round ties to the nearest even number.

This rounding operation is faster and more standard conformant than
`round`

, making it generally preferable.
However it breaks with the legacy behaviour of `std::round`

.

If `self`

is a `NaN`

, infinity, or zero, the same will be returned, though
a different `NaN`

may be returned.

Rust has the unstable `round_ties_even`

method that always uses the `FE_TONEAREST`

rounding mode. In
C++ the rounding mode can be controlled by the user with
`std::fesetround`

.

As in Rust's `round`

and with `std::nearbyint`

, this method
preserves the sign bit when the result is `-0.0`

.

Returns the nearest `i16`

representable by `self`

.

This is equivalent to `sus::cast<i16>(self.round_ties())`

but it may require
fewer instructions on some platforms.

Like `round_ties`

, but unlike
`round`

, the current rounding mode will be respected
to break ties. The default mode will round ties to the nearest even number.

A `NaN`

input will return 0.

Returns the nearest `i32`

representable by `self`

.

This is equivalent to `sus::cast<i32>(self.round_ties())`

but it may require
fewer instructions on some platforms.

Like `round_ties`

, but unlike
`round`

, the current rounding mode will be respected
to break ties. The default mode will round ties to the nearest even number.

A `NaN`

input will return 0.

Returns the nearest `i64`

representable by `self`

.

This is equivalent to `sus::cast<i64>(self.round_ties())`

but it may require
fewer instructions on some platforms.

Like `round_ties`

, but unlike
`round`

, the current rounding mode will be respected
to break ties. The default mode will round ties to the nearest even number.

A `NaN`

input will return 0.

Returns the nearest `i8`

representable by `self`

.

This is equivalent to `sus::cast<i8>(self.round_ties())`

but it may require
fewer instructions on some platforms.

`round_ties`

, but unlike
`round`

, the current rounding mode will be respected
to break ties. The default mode will round ties to the nearest even number.

A `NaN`

input will return 0.

Returns the nearest `isize`

representable by `self`

.

This is equivalent to `sus::cast<isize>(self.round_ties())`

but it may
require fewer instructions on some platforms.

`round_ties`

, but unlike
`round`

, the current rounding mode will be respected
to break ties. The default mode will round ties to the nearest even number.

A `NaN`

input will return 0.

Returns a number that represents the sign of self.

`1.0`

if the number is positive,`+0.0`

or`INFINITY`

.`-1.0`

if the number is negative,`-0.0`

or`NEG_INFINITY`

.`NaN`

if the number is`NaN`

. The input value is returned exactly, preserving signaling NaNs.

Computes the sine of a number (in radians).

Hyperbolic sine function.

Returns the square root of a number.

Returns NaN if self is a negative number other than `-0.0`

.

Computes the tangent of a number (in radians).

Hyperbolic tangent function.

Return the memory representation of this floating point number as a byte array in big-endian (network) byte order.

Raw transmutation to ##UnsignedT##.

This is identical to `std::bit_cast<u32, f32>`

, or
`std::bit_cast<u64, f64>`

.

See `from_bits()`

for some discussion of the portability of this operation
(there are almost no issues).

Note that this function is distinct from `Cast`

casting, which
attempts to preserve the *numeric* value, and not the bitwise value.

Converts radians to degrees.

sus::num::Integer<Int>

Rounds toward zero and converts to any safe integer type assuming that the value is finite and fits in that type.

# Safety

To avoid Undefined Behaviour, the value must:

- Not be
`NaN`

. - Not be infinite.
- Be representable in the return type
`Int`

, after truncating off its fractional part.

Return the memory representation of this floating point number as a byte array in little-endian byte order.

Return the memory representation of this floating point number as a byte array in native byte order.

As the target platform's native endianness is used, portable code should
use `to_be_bytes`

or
`to_le_bytes`

, as appropriate, instead.

Converts degrees to radians.

Return the ordering between `*this`

and `other`

.

Unlike the standard partial comparison between floating point numbers, this comparison always produces an ordering in accordance to the totalOrder predicate as defined in the IEEE 754 (2008 revision) floating point standard. The values are ordered in the following sequence:

negative quiet NaN negative signaling NaN negative infinity negative numbers negative subnormal numbers negative zero positive zero positive subnormal numbers positive numbers positive infinity positive signaling NaN positive quiet NaN.

The ordering established by this function does not always agree with the
`PartialOrd`

and `Eq`

implementations of `f64`

. For example, they
consider negative and positive zero equal, while
`total_cmp`

doesn't.

The interpretation of the signaling NaN bit follows the definition in the IEEE 754 standard, which may not match the interpretation by some of the older, non-conformant (e.g. MIPS) hardware implementations.

# Why does this method satisfy `Ord`

and not `StrongOrd`

?

This method returns
`std::weak_ordering`

which can be used in situations that require `Ord`

because different NaNs will be ordered equivalently.

Returns the integer part of self. This means that non-integer numbers are always truncated towards zero.

# Conversions

sus::num::PrimitiveFloat<U>

::sus::mem::size_of<U>() >= ::sus::mem::size_of<_primitive>()

Conversion from the numeric type to a C++ primitive type.

This converts to floating point primitives which are at least as large as
the `f64`

.

```
auto d = double{3_f64}; // Compiles.
auto e = double(3_f64); // Compiles.
double f = 3_f64; // Compiles.
auto d = float{3_f64}; // Does not compile.
auto e = float(3_f64); // Does not compile.
float f = 3_f64; // Does not compile.
```

Potentially-lossy type conversions can be forced through the
`Cast`

concept, such as
`sus::cast<float>(3_f64)`

or `sus::cast<f32>(3_f64)`

.

# Operators

Satisfies the `RemAssign<f64>`

concept.

Assigns the remainder from the division of two floats.

The remainder has the same sign as the dividend and is computed as:
`l - (l / r).trunc() * r`

.

Satisfies the `MulAssign<f64>`

concept.

Satisfies the `AddAssign<f64>`

concept.

Satisfies the `Neg<f64>`

concept.

Satisfies the `SubAssign<f64>`

concept.

Satisfies the `DivAssign<f64>`

concept.

Assignment from floating point types where no bits are lost.

Assignment from primitive types where no bits are lost.

# Data Members

The inner primitive value. Prefer to cast to the desired primitive type,
such as with `float{n}`

for a numeric value `n`

.