Crate easy_cast

source ·

Expand description

Type conversion, success expected

This library exists to make fallible numeric type conversions easy, without resorting to the as keyword.

Conv is like From, but supports fallible conversions
Cast is to Conv what Into is to From
ConvApprox and CastApprox support fallible, approximate conversion
ConvFloat and CastFloat are similar, providing precise control over rounding

If you are wondering “why not just use as”, there are a few reasons:

integer conversions may silently truncate or sign-extend which does not preserve value
prior to Rust 1.45.0 float-to-int conversions were not fully defined; since this version they use saturating conversion (NaN converts to 0)
you want some assurance (at least in debug builds) that the conversion will preserve values correctly

Why might you not want to use this library?

You want saturating / truncating / other non-value-preserving conversion
You want to convert non-numeric types (From supports a lot more conversions than Conv does)!
You want a thoroughly tested library (we’re not quite there yet)

Error handling

All traits support two methods:

try_* methods return a Result and always fail if the correct conversion is not possible
other methods may panic or return incorrect results

In debug builds, methods not returning Result must panic on failure. As with the overflow checks on Rust’s standard integer arithmetic, this is considered a tool for finding logic errors. In release builds, these methods are permitted to return defined but incorrect results similar to the as keyword.

If the always_assert feature flag is set, assertions will be turned on in all builds. Some additional feature flags are available for finer-grained control (see Cargo.toml).