Easy-cast

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).

Performance

Performance is "good enough that it hasn't been a concern".

In debug builds and when always_assert is enabled, the priority is testing but overhead should be small.

In release builds without always_assert, conv* methods should reduce to x as T (with necessary additions for rounding).

no_std support

When the crate's default features are disabled (and std is not enabled) then the library supports no_std. In this case, [ConvFloat] and [CastFloat] are only available if the libm optional dependency is enabled.

MSRV and no_std

The Minumum Supported Rust Version is 1.53.0 (IntoIterator for [T; N]).

By default, std support is required. With default features disabled no_std is supported, but the ConvFloat and CastFloat traits are unavailable. Enabling the libm feature will re-enable these traits.

Copyright and Licence

The COPYRIGHT file includes a list of contributors who claim copyright on this project. This list may be incomplete; new contributors may optionally add themselves to this list.

The easy-cast library is published under the terms of the Apache License, Version 2.0. You may obtain a copy of this licence from the LICENSE file or on the following webpage: https://www.apache.org/licenses/LICENSE-2.0