pub trait TryFrom<T> {
    type Error;

    fn try_from(value: T) -> Result<Self, Self::Error>;
}
Expand description

Simple and safe type conversions that may fail in a controlled way under some circumstances. It is the reciprocal of TryInto.

This is useful when you are doing a type conversion that may trivially succeed but may also need special handling. For example, there is no way to convert an i64 into an i32 using the From trait, because an i64 may contain a value that an i32 cannot represent and so the conversion would lose data. This might be handled by truncating the i64 to an i32 (essentially giving the i64’s value modulo i32::MAX) or by simply returning i32::MAX, or by some other method. The From trait is intended for perfect conversions, so the TryFrom trait informs the programmer when a type conversion could go bad and lets them decide how to handle it.

Generic Implementations

  • TryFrom<T> for U implies TryInto<U> for T
  • try_from is reflexive, which means that TryFrom<T> for T is implemented and cannot fail – the associated Error type for calling T::try_from() on a value of type T is Infallible. When the ! type is stabilized Infallible and ! will be equivalent.

TryFrom<T> can be implemented as follows:

struct GreaterThanZero(i32);

impl TryFrom<i32> for GreaterThanZero {
    type Error = &'static str;

    fn try_from(value: i32) -> Result<Self, Self::Error> {
        if value <= 0 {
            Err("GreaterThanZero only accepts value superior than zero!")
        } else {
            Ok(GreaterThanZero(value))
        }
    }
}

Examples

As described, i32 implements TryFrom<i64>:

let big_number = 1_000_000_000_000i64;
// Silently truncates `big_number`, requires detecting
// and handling the truncation after the fact.
let smaller_number = big_number as i32;
assert_eq!(smaller_number, -727379968);

// Returns an error because `big_number` is too big to
// fit in an `i32`.
let try_smaller_number = i32::try_from(big_number);
assert!(try_smaller_number.is_err());

// Returns `Ok(3)`.
let try_successful_smaller_number = i32::try_from(3);
assert!(try_successful_smaller_number.is_ok());

Required Associated Types

The type returned in the event of a conversion error.

Required Methods

Performs the conversion.

Implementations on Foreign Types

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI16 to NonZeroU8.

Attempts to convert NonZeroI64 to NonZeroI16.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI128 to NonZeroI32.

Attempts to convert NonZeroU128 to NonZeroU32.

Attempts to convert u32 to NonZeroU32.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroUsize to NonZeroI32.

Attempts to convert u64 to NonZeroU64.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI8 to NonZeroU16.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert u128 to NonZeroU128.

Attempts to convert NonZeroIsize to NonZeroI8.

Attempts to convert NonZeroIsize to NonZeroU16.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroUsize to NonZeroU128.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI128 to NonZeroIsize.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU128 to NonZeroI16.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU32 to NonZeroI32.

Attempts to convert NonZeroI64 to NonZeroU8.

Attempts to convert NonZeroU128 to NonZeroUsize.

Attempts to convert NonZeroU32 to NonZeroU16.

Attempts to convert NonZeroU16 to NonZeroIsize.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroIsize to NonZeroU64.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU64 to NonZeroI16.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI8 to NonZeroU32.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI32 to NonZeroU128.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI16 to NonZeroU64.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU32 to NonZeroI8.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert u16 to NonZeroU16.

Attempts to convert NonZeroI64 to NonZeroI8.

Attempts to convert NonZeroI128 to NonZeroUsize.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI64 to NonZeroIsize.

Attempts to convert u8 to NonZeroU8.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU64 to NonZeroU32.

Attempts to convert NonZeroU64 to NonZeroU8.

Attempts to convert NonZeroUsize to NonZeroIsize.

Attempts to convert NonZeroI32 to NonZeroU16.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU64 to NonZeroUsize.

Attempts to convert NonZeroI128 to NonZeroU8.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI128 to NonZeroU128.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI64 to NonZeroU16.

Attempts to convert isize to NonZeroIsize.

Attempts to convert NonZeroU64 to NonZeroI32.

Attempts to convert NonZeroUsize to NonZeroI16.

Attempts to convert NonZeroUsize to NonZeroU16.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI8 to NonZeroU8.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU128 to NonZeroI8.

Attempts to convert NonZeroI16 to NonZeroUsize.

Attempts to convert NonZeroI64 to NonZeroUsize.

Attempts to convert NonZeroI16 to NonZeroU128.

Attempts to convert NonZeroU128 to NonZeroU64.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroUsize to NonZeroU32.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU128 to NonZeroI64.

Attempts to convert NonZeroIsize to NonZeroU128.

Attempts to convert NonZeroI128 to NonZeroU16.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU64 to NonZeroU16.

Attempts to convert NonZeroI64 to NonZeroU128.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroUsize to NonZeroU8.

Attempts to convert NonZeroU16 to NonZeroU8.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU16 to NonZeroI8.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI32 to NonZeroI8.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroIsize to NonZeroI16.

Map char with code point in U+0000..=U+00FF to byte in 0x00..=0xFF with same value, failing if the code point is greater than U+00FF.

See impl From<u8> for char for details on the encoding.

Attempts to convert NonZeroU32 to NonZeroU8.

Attempts to convert NonZeroU8 to NonZeroI8.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU64 to NonZeroI64.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroIsize to NonZeroU32.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI32 to NonZeroU32.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroIsize to NonZeroI64.

Attempts to convert NonZeroI128 to NonZeroI16.

Attempts to convert NonZeroIsize to NonZeroU8.

Attempts to convert NonZeroUsize to NonZeroU64.

Attempts to convert NonZeroU32 to NonZeroI16.

Attempts to convert NonZeroI16 to NonZeroI8.

Attempts to convert NonZeroU128 to NonZeroU16.

Attempts to convert NonZeroU16 to NonZeroI16.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI8 to NonZeroU64.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert usize to NonZeroUsize.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI8 to NonZeroU128.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI32 to NonZeroUsize.

Attempts to convert NonZeroU128 to NonZeroU8.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI16 to NonZeroU32.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert i64 to NonZeroI64.

Attempts to convert NonZeroUsize to NonZeroI64.

Attempts to convert NonZeroI128 to NonZeroU32.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU128 to NonZeroI128.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI16 to NonZeroU16.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert i128 to NonZeroI128.

Attempts to convert i8 to NonZeroI8.

Attempts to convert NonZeroI64 to NonZeroU32.

Attempts to convert NonZeroIsize to NonZeroUsize.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert i32 to NonZeroI32.

Attempts to convert NonZeroI128 to NonZeroI8.

Attempts to convert NonZeroI32 to NonZeroU64.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroUsize to NonZeroI128.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI64 to NonZeroI32.

Attempts to convert NonZeroU128 to NonZeroIsize.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroUsize to NonZeroI8.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI32 to NonZeroU8.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI64 to NonZeroU64.

Attempts to convert NonZeroI32 to NonZeroIsize.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroI128 to NonZeroU64.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU32 to NonZeroUsize.

Attempts to convert NonZeroI8 to NonZeroUsize.

Attempts to convert NonZeroI128 to NonZeroI64.

Attempts to convert NonZeroU64 to NonZeroIsize.

Attempts to convert i16 to NonZeroI16.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU64 to NonZeroI8.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU128 to NonZeroI32.

Attempts to convert NonZeroIsize to NonZeroI128.

Attempts to convert NonZeroI32 to NonZeroI16.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Attempts to convert NonZeroU32 to NonZeroIsize.

Attempts to convert NonZeroIsize to NonZeroI32.

Try to create the target number type from a source number type. This returns an error if the source value is outside of the range of the target type.

Gets the entire contents of the Vec<T> as an array, if its size exactly matches that of the requested array.

Examples
assert_eq!(vec![1, 2, 3].try_into(), Ok([1, 2, 3]));
assert_eq!(<Vec<i32>>::new().try_into(), Ok([]));

If the length doesn’t match, the input comes back in Err:

let r: Result<[i32; 4], _> = (0..10).collect::<Vec<_>>().try_into();
assert_eq!(r, Err(vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9]));

If you’re fine with just getting a prefix of the Vec<T>, you can call .truncate(N) first.

let mut v = String::from("hello world").into_bytes();
v.sort();
v.truncate(2);
let [a, b]: [_; 2] = v.try_into().unwrap();
assert_eq!(a, b' ');
assert_eq!(b, b'd');

Attempts to convert a Box<[T]> into a Box<[T; N]>.

The conversion occurs in-place and does not require a new memory allocation.

Errors

Returns the old Box<[T]> in the Err variant if boxed_slice.len() does not equal N.

Implementors