Trait zerovec::ule::VarULE[−][src]

pub unsafe trait VarULE: 'static {
    type Error: Display;
    fn validate_byte_slice(_bytes: &[u8]) -> Result<(), Self::Error>;

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

    fn parse_byte_slice(bytes: &[u8]) -> Result<&Self, Self::Error> { ... }

    fn as_byte_slice(&self) -> &[u8]ⓘ
Notable traits for &'_ mut [u8]
impl<'_> Write for &'_ mut [u8]impl<'_> Read for &'_ [u8]
 { ... }

    fn to_boxed(&self) -> Box<Self> { ... }
}
Expand description

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

This trait is mostly for unsized types like str and [T]. It can be implemented on sized types; however, it is much more preferable to use ULE for that purpose.

If deserialization with VarZeroVec is desired is recommended to implement Deserialize for Box<T> (serde does not do this automatically for unsized T).

Safety

Safety checklist for VarULE:

  1. The type must not include any uninitialized or padding bytes.
  2. The impl of ULE::validate_byte_slice() must return an error if the given byte slice would not represent a valid slice of this type.
  3. The impl of ULE::validate_byte_slice() must return an error if the given byte slice cannot be used in its entirety.
  4. All other methods must be left with their default impl, or else implemented according to their respective safety guidelines.
  5. Acknowledge the following note about the equality invariant.

Equality invariant

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

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_byte_slice() 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.

Associated Types

The error that occurs if a byte array is not valid for this ULE.

Required methods

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 &Self, then Ok should be returned; otherwise, Self::Error should be returned.

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_byte_slice() with success.

Safety
Callers

Callers of this method must take care to ensure that bytes was previously passed through Self::validate_byte_slice() 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.

Safety checklist:

  1. This method must return the same result as Self::parse_byte_slice().
  2. This method must return a slice to the same region of memory as the argument.

Provided methods

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_byte_slice().

The default implementation executes Self::validate_byte_slice() followed by Self::from_byte_slice_unchecked.

Note: The following equality should hold: size_of_val(result) == size_of_val(bytes), where result is the successful return value of the method. This means that the return value spans the entire byte slice.

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.

Allocate on the heap as a Box<T>

Implementations on Foreign Types

Invariant: must be safe to call when called on a slice that previously succeeded with parse_byte_slice

Implementors