Crate easy_cast[−][src]

Type conversion, success expected

This library is written to make numeric type conversions easy. Such conversions usually fall into one of the following cases:

  • the conversion must preserve values exactly (use From or Into or Conv or Cast)
  • the conversion is expected to preserve values exactly, though this is not ensured by the types in question (use Conv or Cast)
  • the conversion could fail and must be checked at run-time (use TryFrom or TryInto or Conv::try_conv or Cast::try_cast)
  • the conversion is from floating point values to integers and should round to the “nearest” integer (use ConvFloat or CastFloat)
  • the conversion is from f32 to f64 or vice-versa; in this case use of as f32 / as f64 is likely acceptable since f32 has special representations for non-finite values and conversion to f64 is exact
  • truncating conversion (modular arithmetic) is desired; in this case as probably does exactly what you want
  • saturating conversion is desired (less common; not supported here)

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

  • integer conversions may silently truncate
  • integer conversions to/from signed types silently reinterpret
  • 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 without having to proof-read code

When should you not use this library?

  • Only numeric conversions are supported
  • Conversions from floats do not provide fine control of rounding modes
  • This library has not been thoroughly tested correctness

Assertions

All type conversions which are potentially fallible assert on failure in debug builds. In release builds assertions may be omitted, thus making incorrect conversions possible.

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

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.

Enums

Error

Error types for conversions

Traits

Cast

Like Into, but for Conv

CastFloat

Like Into, but for ConvFloat

Conv

Like From, but supporting potentially-fallible conversions

ConvFloat

Nearest / floor / ceil conversions from floating point types