Trait SliceSpec

pub trait SliceSpec {
    type Custom: ?Sized;
    type Inner: ?Sized;
    type Error;

    // Required methods
    fn validate(s: &Self::Inner) -> Result<(), Self::Error>;
    fn as_inner(s: &Self::Custom) -> &Self::Inner;
    fn as_inner_mut(s: &mut Self::Custom) -> &mut Self::Inner;
    unsafe fn from_inner_unchecked(s: &Self::Inner) -> &Self::Custom;
    unsafe fn from_inner_unchecked_mut(s: &mut Self::Inner) -> &mut Self::Custom;
}

A trait to provide types and features for a custom slice type.

Safety

To avoid undefined behavior, users are responsible to let implementations satisfy all conditions below:

• Self::validate() always returns the same result for the same input.
• Self::Inner is the only non-zero type field of Self::Custom.
• Self::Custom has attribute #[repr(transparent)] or #[repr(C)].

If any of the condition is not met, use of methods may cause undefined behavior.

Examples

/// ASCII string slice.
// `#[repr(transparent)]` or `#[repr(C)]` is required.
// Without it, generated codes would be unsound.
#[repr(transparent)]
#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct AsciiStr(str);

/// ASCII string validation error.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct AsciiError {
    /// Byte position of the first invalid byte.
    valid_up_to: usize,
}

enum AsciiStrSpec {}

impl validated_slice::SliceSpec for AsciiStrSpec {
    type Custom = AsciiStr;
    type Inner = str;
    type Error = AsciiError;

    fn validate(s: &Self::Inner) -> Result<(), Self::Error> {
        match s.as_bytes().iter().position(|b| !b.is_ascii()) {
            Some(pos) => Err(AsciiError { valid_up_to: pos }),
            None => Ok(()),
        }
    }

    validated_slice::impl_slice_spec_methods! {
        field=0;
        methods=[
            as_inner,
            as_inner_mut,
            from_inner_unchecked,
            from_inner_unchecked_mut,
        ];
    }
}

Required Associated Types

type Custom: ?Sized

Custom borrowed slice type.

type Inner: ?Sized

Borrowed inner slice type of Self::Custom.

type Error

Validation error type.

Required Methods

fn validate(s: &Self::Inner) -> Result<(), Self::Error>

Validates the inner slice to check if the value is valid as the custom slice type value.

Returns Ok(()) if the value is valid (and safely convertible to Self::Custom. Returns Err(_) if the validation failed.

fn as_inner(s: &Self::Custom) -> &Self::Inner

Converts a reference to the custom slice into a reference to the inner slice type.

fn as_inner_mut(s: &mut Self::Custom) -> &mut Self::Inner

Converts a mutable reference to the custom slice into a mutable reference to the inner slice type.

unsafe fn from_inner_unchecked(s: &Self::Inner) -> &Self::Custom

Creates a reference to the custom slice type without any validation.

Safety

This is safe only when all of the conditions below are met:

• Self::validate(s) returns Ok(()).
• Self::Inner is the only non-zero type field of Self::Custom.
• Self::Custom has attribute #[repr(transparent)] or #[repr(C)].

If any of the condition is not met, this function may cause undefined behavior.

unsafe fn from_inner_unchecked_mut(s: &mut Self::Inner) -> &mut Self::Custom

Creates a mutable reference to the custom slice type without any validation.

Safety

Safety condition is same as from_inner_unchecked.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors