Trait ULE

unsafe trait ULE
where
    Self: Sized + Copy + 'static

Fixed-width, byte-aligned data that can be cast to and from a little-endian byte slice.

If you need to implement this trait, consider using #[make_ule] or #[derive(ULE)] instead.

Types that are not fixed-width can implement VarULE instead.

"ULE" stands for "Unaligned little-endian"

Safety

Safety checklist for ULE:

  1. The type must not include any uninitialized or padding bytes.
  2. The type must have an alignment of 1 byte, or it is a ZST that is safe to construct.
  3. The impl of [ULE::validate_bytes()] must return an error if the given byte slice would not represent a valid slice of this type.
  4. The impl of [ULE::validate_bytes()] must return an error if the given byte slice cannot be used in its entirety (if its length is not a multiple of size_of::<Self>()).
  5. All other methods must be left with their default impl, or else implemented according to their respective safety guidelines.
  6. Acknowledge the following note about the equality invariant.

If the ULE type is a struct only containing other ULE types (or other types which satisfy invariants 1 and 2, like [u8; N]), invariants 1 and 2 can be achieved via #[repr(C, packed)] or #[repr(transparent)].

Equality invariant

A non-safety invariant is that if Self implements PartialEq, the it must be logically equivalent to byte equality on [Self::slice_as_bytes()].

It may be necessary to introduce a "canonical form" of the ULE if logical equality does not equal byte equality. In such a case, [Self::validate_bytes()] should return an error for any values that are not in canonical form. For example, the decimal strings "1.23e4" and "12.3e3" are logically equal, but not byte-for-byte equal, so we could define a canonical form where only a single digit is allowed before ..

Failure to follow this invariant will cause surprising behavior in PartialEq, which may result in unpredictable operations on ZeroVec, VarZeroVec, and ZeroMap.

Required Methods

fn validate_bytes(bytes: &[u8]) -> Result<(), UleError>

Validates a byte slice, &[u8].

If Self is not well-defined for all possible bit values, the bytes should be validated. If the bytes can be transmuted, in their entirety, to a valid slice of Self, then Ok should be returned; otherwise, Err should be returned.

Provided Methods

fn parse_bytes_to_slice(bytes: &[u8]) -> Result<&[Self], UleError>

Parses a byte slice, &[u8], and return it as &[Self] with the same lifetime.

If Self is not well-defined for all possible bit values, the bytes should be validated, and an error should be returned in the same cases as [Self::validate_bytes()].

The default implementation executes [Self::validate_bytes()] followed by Self::slice_from_bytes_unchecked.

Note: The following equality should hold: bytes.len() % size_of::<Self>() == 0. This means that the returned slice can span the entire byte slice.

unsafe fn slice_from_bytes_unchecked(bytes: &[u8]) -> &[Self]

Takes a byte slice, &[u8], and return it as &[Self] with the same lifetime, assuming that this byte slice has previously been run through [Self::parse_bytes_to_slice()] with success.

The default implementation performs a pointer cast to the same region of memory.

Safety

Callers

Callers of this method must take care to ensure that bytes was previously passed through [Self::validate_bytes()] with success (and was not changed since then).

Implementors

Implementations of this method may call unsafe functions to cast the pointer to the correct type, assuming the "Callers" invariant above.

Keep in mind that &[Self] and &[u8] may have different lengths.

Safety checklist:

  1. This method must return the same result as [Self::parse_bytes_to_slice()].
  2. This method must return a slice to the same region of memory as the argument.
fn slice_as_bytes(slice: &[Self]) -> &[u8]

Given &[Self], returns a &[u8] with the same lifetime.

The default implementation performs a pointer cast to the same region of memory.

Safety

Implementations of this method should call potentially unsafe functions to cast the pointer to the correct type.

Keep in mind that &[Self] and &[u8] may have different lengths.

Implementors