Crate easy_cast 

Converting values

This library exists to make numeric type conversions easy and generic without resorting to the as keyword.

• Use Cast and Conv instead of Into and From for exact conversions
• Use CastApprox and ConvApprox for approximate conversions (rounding mode is implementation-defined just like as)
• Use CastTo and ConvTo for conversions with a specific rounding mode (see § Rounding modes).

If this sounds like a lot of traits, consider the above are all essentially syntactic sugar for ConvTo (see § Implementing traits).

Quick example

use easy_cast::{Cast, Conv, CastApprox, CastTo, Nearest};
let _: i32 = 15_usize.cast();           // exact conversion
let _ = usize::conv(20_u32);            // exact conversion
let _: f32 = u32::MAX.cast_approx();    // approximates to 2^32
let _: i32 = 11.9_f32.cast_to(Nearest); // rounds to 12

Rounding modes

The Rounding trait (used with CastTo and ConvTo) supports genericity over rounding modes:

• Exact specifies that no rounding is allowed (loss of precision is an error)
• Approx specifies that rounding is allowed. The rounding mode used is a property of the implementation, but usually aligns with as numeric casts.
• Trunc, Floor, Ceil and Nearest allow more precise control over rounding

All rounding modes require that the result is close to the input value. For a more precise definition, see § Limits of approximation.

Error handling

Unlike From or TryFrom, this library’s traits are implemented regardless of fallibility. All conversion traits have an associated Error type which is expected to be one of:

• std::convert::Infallible for infallible conversions
• RangeError for conversions which may fail due to domain errors
• Error for conversions which may fail due to domain or loss-of-precision errors.

Further, all traits have two methods:

• A try_ method (e.g. Cast::try_cast) which returns a Result
• A “derived” method (e.g. Cast::cast) with § Fallback behaviour

Fallback behaviour

In debug builds, the “derived” method must panic on failure. This is also the case if the always_assert feature flag is enabled (for this library’s implementations).

Otherwise (in release builds without extra assertions enabled), more flexible behaviour of the “derived” methods is allowed. The implementations provided by easy-cast mostly reduce to as numeric casts (with extra rounding where required).

Implementing traits

Implement conversions which cannot lose precision using ConvExact. Implement all other conversions using ConvTo for one or several Rounding modes.

Modules

traits

Traits

Macros

impl_via_from

Implement ConvExact infallibly over a From implementation

impl_via_identity

Implement an identity “conversion” via ConvExact infallibly

Structs

Approx

Approximate conversion

Ceillibm or std

Round towards positive infinity (ceiling)

Exact

Exact conversion only

Floorlibm or std

Round towards negative infinity (floor)

Nearestlibm or std

Round to the nearest representable value

RangeError

Source value lies outside of target type’s range

Trunc

Truncation towards zero

Enums

Error

Error types for conversions

Traits

Cast

Like Into, but for Conv

CastApprox

Like Into, but for ConvApprox

CastTo

Generic “into” conversion trait with specified rounding mode

Conv

Like From, but supports fallible conversions

ConvApprox

Like From, but for approximate numerical conversions

ConvExact

Generic “from” conversion trait for exact conversions

ConvTo

Generic “from” conversion trait with specified rounding mode

Rounding

Rounding mode