Crate conv

This crate provides a number of conversion traits with more specific semantics than those provided by as or From/Into.

The goal with the traits provided here is to be more specific about what generic code can rely on, as well as provide reasonably self-describing alternatives to the standard From/Into traits. For example, the although T: From<U> might be satisfied, it imposes no restrictions on the kind of conversion being implemented. As such, the traits in this crate try to be very specific about what conversions are allowed. This makes them less generally applicable, but more useful where they do apply.

In addition, From/Into requires all conversions to succeed or panic. All conversion traits in this crate define an associated error type, allowing code to react to failed conversions as appropriate.

Links

• Latest Release
• Latest Docs
• Repository

Compatibility

conv is compatible with Rust 1.2 and higher.

Change Log

v0.3.2

• Added integer ↔ char conversions.
• Added missing isize/usize → f32/f64 conversions.
• Fixed the error type of i64 → usize for 64-bit targets.

v0.3.1

• Change to unwrap_ok for better codegen (thanks bluss).
• Fix for Rust breaking change (code in question was dodgy anyway; thanks m4rw3r).

v0.3.0

• Added an Error constraint to all Err associated types. This will break any user-defined conversions where the Err type does not implement Error.
• Renamed the Overflow and Underflow errors to PosOverflow and NegOverflow respectively. In the context of floating point conversions, “underflow” usually means the value was too close to zero to correctly represent.

v0.2.1

• Added ConvUtil::into_as<Dst> as a shortcut for Into::<Dst>::into.
• Added #[inline] attributes.
• Added Saturate::saturate, which can saturate Results arising from over/underflow.

v0.2.0

• Changed all error types to include the original input as payload. This breaks pretty much everything. Sorry about that. On the bright side, there’s now no downside to using the conversion traits for non-Copy types.
• Added the normal rounding modes for float → int approximations: RoundToNearest, RoundToNegInf, RoundToPosInf, and RoundToZero.
• ApproxWith is now subsumed by a pair of extension traits (ConvUtil and ConvAsUtil), that also have shortcuts for TryInto and ValueInto so that you can specify the destination type on the method.

Overview

The following traits are used to define various conversion semantics:

• ApproxFrom/ApproxInto - approximate conversions, with selectable approximation scheme (see ApproxScheme).
• TryFrom/TryInto - general, potentially failing value conversions.
• ValueFrom/ValueInto - exact, value-preserving conversions.

When defining a conversion, try to implement the *From trait variant where possible. When using a conversion, try to depend on the *Into trait variant where possible. This is because the *Into traits automatically use *From implementations, but not the reverse. Implementing *From and using *Into ensures conversions work in as many contexts as possible.

These extension methods are provided to help with some common cases:

• ConvUtil::approx_as<Dst> - approximates to Dst with the DefaultApprox scheme.
• ConvUtil::approx_as_by<Dst, S> - approximates to Dst with the scheme S.
• ConvUtil::into_as<Dst> - converts to Dst using Into::into.
• ConvUtil::try_as<Dst> - converts to Dst using TryInto::try_into.
• ConvUtil::value_as<Dst> - converts to Dst using ValueInto::value_into.
• ConvAsUtil::approx - approximates to an inferred destination type with the DefaultApprox scheme.
• ConvAsUtil::approx_by<S> - approximates to an inferred destination type with the scheme S.
• Saturate::saturate - saturates on overflow.
• UnwrapOk::unwrap_ok - unwraps results from conversions that cannot fail.
• UnwrapOrInf::unwrap_or_inf - saturates to ±∞ on failure.
• UnwrapOrInvalid::unwrap_or_invalid - substitutes the target type’s “invalid” sentinel value on failure.
• UnwrapOrSaturate::unwrap_or_saturate - saturates to the maximum or minimum value of the target type on failure.

A macro is provided to assist in implementing conversions:

• TryFrom! - derives an implementation of TryFrom.

If you are implementing your own types, you may also be interested in the traits contained in the misc module.

Provided Implementations

The crate provides several blanket implementations:

• *From<A> for A (all types can be converted from and into themselves).
• *Into<Dst> for Src where Dst: *From<Src> (*From implementations imply a matching *Into implementation).

Conversions for the builtin numeric (integer and floating point) types are provided. In general, ValueFrom conversions exist for all pairs except for float → integer (since such a conversion is generally unlikely to exactly succeed) and f64 → f32 (for the same reason). ApproxFrom conversions with the DefaultApprox scheme exist between all pairs. ApproxFrom with the Wrapping scheme exist between integers.

Errors

A number of error types are defined in the errors module. Generally, conversions use whichever error type most narrowly defines the kinds of failures that can occur. For example:

• ValueFrom<u8> for u16 cannot possibly fail, and as such it uses NoError.
• ValueFrom<i8> for u16 can only fail with a negative overflow, thus it uses the NegOverflow type.
• ValueFrom<i32> for u16 can overflow in either direction, hence it uses RangeError.
• Finally, ApproxFrom<f32> for u16 can overflow (positive or negative), or attempt to convert NaN; FloatError covers those three cases.

Because there are numerous error types, the GeneralError enum is provided. From<E, T> for GeneralError<T> exists for each error type E<T> defined by this crate (even for NoError!), allowing errors to be translated automatically by try!. In fact, all errors can be “expanded” to all more general forms (e.g. NoError → NegOverflow, PosOverflow → RangeError → FloatError).

Aside from NoError, the various error types wrap the input value that you attempted to convert. This is so that non-Copy types do not need to be pre-emptively cloned prior to conversion, just in case the conversion fails. A downside is that this means there are many, many incompatible error types.

To help alleviate this, there is also GeneralErrorKind, which is simply GeneralError<T> without the payload, and all errors can be converted into it directly.

The reason for not just using GeneralErrorKind in the first place is to statically reduce the number of potential error cases you need to deal with. It also allows the Unwrap* extension traits to be defined without the possibility for runtime failure (e.g. you cannot use unwrap_or_saturate with a FloatError, because what do you do if the error is NotANumber; saturate to max or to min? Or panic?).

Examples

// This *cannot* fail, so we can use `unwrap_ok` to discard the `Result`.
assert_eq!(u8::value_from(0u8).unwrap_ok(), 0u8);

// This *can* fail.  Specifically, it can overflow toward negative infinity.
assert_eq!(u8::value_from(0i8),     Ok(0u8));
assert_eq!(u8::value_from(-1i8),    Err(NegOverflow(-1)));

// This can overflow in *either* direction; hence the change to `RangeError`.
assert_eq!(u8::value_from(-1i16),   Err(RangeError::NegOverflow(-1)));
assert_eq!(u8::value_from(0i16),    Ok(0u8));
assert_eq!(u8::value_from(256i16),  Err(RangeError::PosOverflow(256)));

// We can use the extension traits to simplify this a little.
assert_eq!(u8::value_from(-1i16).unwrap_or_saturate(),  0u8);
assert_eq!(u8::value_from(0i16).unwrap_or_saturate(),   0u8);
assert_eq!(u8::value_from(256i16).unwrap_or_saturate(), 255u8);

// Obviously, all integers can be "approximated" using the default scheme (it
// doesn't *do* anything), but they can *also* be approximated with the
// `Wrapping` scheme.
assert_eq!(
    <u8 as ApproxFrom<_, DefaultApprox>>::approx_from(400u16),
    Err(PosOverflow(400)));
assert_eq!(
    <u8 as ApproxFrom<_, Wrapping>>::approx_from(400u16),
    Ok(144u8));

// This is rather inconvenient; as such, there are a number of convenience
// extension methods available via `ConvUtil` and `ConvAsUtil`.
assert_eq!(400u16.approx(),                       Err::<u8, _>(PosOverflow(400)));
assert_eq!(400u16.approx_by::<Wrapping>(),        Ok::<u8, _>(144u8));
assert_eq!(400u16.approx_as::<u8>(),              Err(PosOverflow(400)));
assert_eq!(400u16.approx_as_by::<u8, Wrapping>(), Ok(144));

// Integer -> float conversions *can* fail due to limited precision.
// Once the continuous range of exactly representable integers is exceeded, the
// provided implementations fail with overflow errors.
assert_eq!(f32::value_from(16_777_216i32), Ok(16_777_216.0f32));
assert_eq!(f32::value_from(16_777_217i32), Err(RangeError::PosOverflow(16_777_217)));

// Float -> integer conversions have to be done using approximations.  Although
// exact conversions are *possible*, "advertising" this with an implementation
// is misleading.
//
// Note that `DefaultApprox` for float -> integer uses whatever rounding
// mode is currently active (*i.e.* whatever `as` would do).
assert_eq!(41.0f32.approx(), Ok(41u8));
assert_eq!(41.3f32.approx(), Ok(41u8));
assert_eq!(41.5f32.approx(), Ok(41u8));
assert_eq!(41.8f32.approx(), Ok(41u8));
assert_eq!(42.0f32.approx(), Ok(42u8));

assert_eq!(255.0f32.approx(), Ok(255u8));
assert_eq!(256.0f32.approx(), Err::<u8, _>(FloatError::PosOverflow(256.0)));

// Sometimes, it can be useful to saturate the conversion from float to
// integer directly, then account for NaN as input separately.  The `Saturate`
// extension trait exists for this reason.
assert_eq!((-23.0f32).approx_as::<u8>().saturate(), Ok(0));
assert_eq!(302.0f32.approx_as::<u8>().saturate(), Ok(255u8));
assert!(std::f32::NAN.approx_as::<u8>().saturate().is_err());

// If you really don't care about the specific kind of error, you can just rely
// on automatic conversion to `GeneralErrorKind`.
fn too_many_errors() -> Result<(), GeneralErrorKind> {
    assert_eq!({let r: u8 = try!(0u8.value_into()); r},  0u8);
    assert_eq!({let r: u8 = try!(0i8.value_into()); r},  0u8);
    assert_eq!({let r: u8 = try!(0i16.value_into()); r}, 0u8);
    assert_eq!({let r: u8 = try!(0.0f32.approx()); r},   0u8);
    Ok(())
}

Re-exports

• pub use errors::NoError;
• pub use errors::GeneralError;
• pub use errors::GeneralErrorKind;
• pub use errors::Unrepresentable;
• pub use errors::NegOverflow;
• pub use errors::PosOverflow;
• pub use errors::FloatError;
• pub use errors::RangeError;
• pub use errors::RangeErrorKind;
• pub use errors::Saturate;
• pub use errors::UnwrapOk;
• pub use errors::UnwrapOrInf;
• pub use errors::UnwrapOrInvalid;
• pub use errors::UnwrapOrSaturate;

Modules

• errors
  This module defines the various error types that can be produced by a failed conversion.
• macros
  This module provides convenience macros to help with implementing the conversion traits.
• misc
  This module defines some additional traits not directly tied to conversions.
• prelude
  Publicly re-exports the most generally useful set of items.

Macros

• TryFrom
  See the documentation for the macros module for details.

Enums

• DefaultApprox
  The “default” approximation scheme. This scheme does whatever would generally be expected of a lossy conversion, assuming no additional context or instruction is given.
• RoundToNearest
  This scheme is used to convert a value by rounding it to the nearest representable value, with ties rounding away from zero.
• RoundToNegInf
  This scheme is used to convert a value by rounding it toward negative infinity to the nearest representable value.
• RoundToPosInf
  This scheme is used to convert a value by rounding it toward positive infinity to the nearest representable value.
• RoundToZero
  This scheme is used to convert a value by rounding it toward zero to the nearest representable value.
• Wrapping
  This scheme is used to convert a value by “wrapping” it into a narrower range.

Traits

• ApproxFrom
  This trait is used to perform a conversion that is permitted to approximate the result, but not to wrap or saturate the result to fit into the destination type’s representable range.
• ApproxInto
  This is the dual of ApproxFrom; see that trait for information.
• ApproxScheme
  This trait is used to mark approximation scheme types.
• ConvAsUtil
  This extension trait exists to simplify using various conversions.
• ConvUtil
  This extension trait exists to simplify using various conversions.
• TryFrom
  This trait is used to perform a conversion between different semantic types which might fail.
• TryInto
  This is the dual of TryFrom; see that trait for information.
• ValueFrom
  This trait is used to perform an exact, value-preserving conversion.
• ValueInto
  This is the dual of ValueFrom; see that trait for information.