Enum ConvertError

pub enum ConvertError<A, S, V> {
    Alignment(A),
    Size(S),
    Validity(V),
}

Zerocopy’s generic error type.

Generally speaking, zerocopy’s conversions may fail for one of up to three reasons:

• AlignmentError: the conversion source was improperly aligned
• SizeError: the conversion source was of incorrect size
• ValidityError: the conversion source contained invalid data

However, not all conversions produce all errors. For instance, FromBytes::ref_from_bytes may fail due to alignment or size issues, but not validity issues. This generic error type captures these (im)possibilities via parameterization: A is parameterized with AlignmentError, S is parameterized with SizeError, and V is parameterized with [Infallible].

Zerocopy never uses this type directly in its API. Rather, we provide three pre-parameterized aliases:

• CastError: the error type of reference conversions
• TryCastError: the error type of fallible reference conversions
• TryReadError: the error type of fallible read conversions

Variants

Alignment(A)

The conversion source was improperly aligned.

Size(S)

The conversion source was of incorrect size.

Validity(V)

The conversion source contained invalid data.

Implementations

impl<Src, Dst: ?Sized> ConvertError<AlignmentError<Src, Dst>, SizeError<Src, Dst>, Infallible>

pub fn into_src(self) -> Src

Produces the source underlying the failed conversion.

pub fn map_src<NewSrc>( self, f: impl Fn(Src) -> NewSrc, ) -> CastError<NewSrc, Dst>

Maps the source value associated with the conversion error.

This can help mitigate issues with Send, Sync and 'static bounds.

Examples

use zerocopy::*;

let source: [u8; 3] = [0, 1, 2];

// Try to read a `u32` from `source`. This will fail because there are insufficient
// bytes in `source`.
let maybe_u32: Result<&u32, CastError<&[u8], u32>> = u32::ref_from_bytes(&source[..]);

// Map the error's source to its size and address.
let maybe_u32: Result<&u32, CastError<(usize, usize), u32>> = maybe_u32.map_err(|err| {
    err.map_src(|src| (src.len(), src.as_ptr() as usize))
});

impl<Src, Dst: ?Sized + TryFromBytes> ConvertError<AlignmentError<Src, Dst>, SizeError<Src, Dst>, ValidityError<Src, Dst>>

pub fn into_src(self) -> Src

Produces the source underlying the failed conversion.

pub fn map_src<NewSrc>( self, f: impl Fn(Src) -> NewSrc, ) -> TryCastError<NewSrc, Dst>

Maps the source value associated with the conversion error.

This can help mitigate issues with Send, Sync and 'static bounds.

Examples

use core::num::NonZeroU32;
use zerocopy::*;

let source: [u8; 3] = [0, 0, 0];

// Try to read a `NonZeroU32` from `source`.
let maybe_u32: Result<&NonZeroU32, TryCastError<&[u8], NonZeroU32>>
    = NonZeroU32::try_ref_from_bytes(&source[..]);

// Map the error's source to its size and address.
let maybe_u32: Result<&NonZeroU32, TryCastError<(usize, usize), NonZeroU32>> =
    maybe_u32.map_err(|err| {
        err.map_src(|src| (src.len(), src.as_ptr() as usize))
    });

impl<Src, Dst: ?Sized + TryFromBytes> ConvertError<Infallible, SizeError<Src, Dst>, ValidityError<Src, Dst>>

pub fn into_src(self) -> Src

Produces the source underlying the failed conversion.

pub fn map_src<NewSrc>( self, f: impl Fn(Src) -> NewSrc, ) -> TryReadError<NewSrc, Dst>

Maps the source value associated with the conversion error.

This can help mitigate issues with Send, Sync and 'static bounds.

Examples

use core::num::NonZeroU32;
use zerocopy::*;

let source: [u8; 3] = [0, 0, 0];

// Try to read a `NonZeroU32` from `source`.
let maybe_u32: Result<NonZeroU32, TryReadError<&[u8], NonZeroU32>>
    = NonZeroU32::try_read_from_bytes(&source[..]);

// Map the error's source to its size.
let maybe_u32: Result<NonZeroU32, TryReadError<usize, NonZeroU32>> =
    maybe_u32.map_err(|err| {
        err.map_src(|src| src.len())
    });

Trait Implementations

impl<A: Debug, S: Debug, V: Debug> Debug for ConvertError<A, S, V>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A: Display, S: Display, V: Display> Display for ConvertError<A, S, V>

Produces a human-readable error message.

The message differs between debug and release builds. When debug_assertions are enabled, this message is verbose and includes potentially sensitive information.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A, S, V> Error for ConvertError<A, S, V>

where A: Display + Debug, S: Display + Debug, V: Display + Debug,

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl<Src, Dst: ?Sized, S, V> From<AlignmentError<Src, Dst>> for ConvertError<AlignmentError<Src, Dst>, S, V>

fn from(err: AlignmentError<Src, Dst>) -> Self

Converts to this type from the input type.

impl<Src, Dst: ?Sized + Unaligned, S, V> From<ConvertError<AlignmentError<Src, Dst>, S, V>> for ConvertError<Infallible, S, V>

fn from( err: ConvertError<AlignmentError<Src, Dst>, S, V>, ) -> ConvertError<Infallible, S, V>

Infallibly discards the alignment error from this ConvertError since Dst is unaligned.

Since Dst: Unaligned, it is impossible to encounter an alignment error. This method permits discarding that alignment error infallibly and replacing it with [Infallible].

Examples

use core::convert::Infallible;
use zerocopy::*;

#[derive(TryFromBytes, KnownLayout, Unaligned, Immutable)]
#[repr(C, packed)]
struct Bools {
    one: bool,
    two: bool,
    many: [bool],
}

impl Bools {
    fn parse(bytes: &[u8]) -> Result<&Bools, AlignedTryCastError<&[u8], Bools>> {
        // Since `Bools: Unaligned`, we can infallibly discard
        // the alignment error.
        Bools::try_ref_from_bytes(bytes).map_err(Into::into)
    }
}

impl<Src, Dst: ?Sized + TryFromBytes> From<ConvertError<AlignmentError<Src, Dst>, SizeError<Src, Dst>, Infallible>> for TryCastError<Src, Dst>

fn from(value: CastError<Src, Dst>) -> Self

Converts to this type from the input type.

impl<Src, Dst: ?Sized + Unaligned> From<ConvertError<AlignmentError<Src, Dst>, SizeError<Src, Dst>, Infallible>> for SizeError<Src, Dst>

fn from(err: CastError<Src, Dst>) -> SizeError<Src, Dst>

Infallibly extracts the SizeError from this CastError since Dst is unaligned.

Since Dst: Unaligned, it is impossible to encounter an alignment error, and so the only error that can be encountered at runtime is a SizeError. This method permits extracting that SizeError infallibly.

Examples

use zerocopy::*;

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)]
#[repr(C)]
struct UdpHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)]
#[repr(C, packed)]
struct UdpPacket {
    header: UdpHeader,
    body: [u8],
}

impl UdpPacket {
    pub fn parse(bytes: &[u8]) -> Result<&UdpPacket, SizeError<&[u8], UdpPacket>> {
        // Since `UdpPacket: Unaligned`, we can map the `CastError` to a `SizeError`.
        UdpPacket::ref_from_bytes(bytes).map_err(Into::into)
    }
}

impl<Src, Dst: ?Sized, A, V> From<SizeError<Src, Dst>> for ConvertError<A, SizeError<Src, Dst>, V>

fn from(err: SizeError<Src, Dst>) -> Self

Converts to this type from the input type.

impl<Src, Dst: ?Sized + TryFromBytes, A, S> From<ValidityError<Src, Dst>> for ConvertError<A, S, ValidityError<Src, Dst>>

fn from(err: ValidityError<Src, Dst>) -> Self

Converts to this type from the input type.

impl<A: PartialEq, S: PartialEq, V: PartialEq> PartialEq for ConvertError<A, S, V>

fn eq(&self, other: &ConvertError<A, S, V>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A: Eq, S: Eq, V: Eq> Eq for ConvertError<A, S, V>

impl<A, S, V> StructuralPartialEq for ConvertError<A, S, V>