Trait AsValidated 

pub trait AsValidated<V: Validated + ?Sized> {
    // Required method
    fn as_validated(&self) -> MaybeValidRef<'_, V, Self>;
}

Borrows Self as a validated view of type V, if self satisfies V’s predicate.

AsValidated<V> expresses that a reference to Self can be reinterpreted as a reference to V whenever self’s contents satisfy the validation predicate declared by V: Validated. The conversion is a borrow: the returned &V aliases memory owned by self, and no allocation occurs on either the valid or invalid path.

This is the fallible analog of AsRef, restricted to structural refinements — cases where V shares a representation with Self and differs only in which values are permitted. For non-structural fallible conversions (parsing a string into a binary value, for example), use TryFrom or FromStr.

Contract

Implementers of AsValidated<V> promise:

1. Structural conversion. On the valid path, the returned &V must alias memory within self. No new storage is allocated, and no owned intermediate value is constructed.

2. Cost bounded by validation. The method performs at most the work inherent to deciding whether self satisfies V’s predicate. It does not do additional work that could be deferred or cached elsewhere.

3. Diagnostic-only reason. The InvalidReason returned on the invalid path does not carry a copy of self’s contents. The precursor is returned as a reference alongside the reason, aliasing the same &self the caller passed in.

4. Deterministic classification. Whether a given self produces Valid or Invalid depends only on self’s observable state. Repeated calls with the same state produce the same classification.

These are logical contracts, not compiler-enforced ones. Violating them does not cause undefined behavior but breaks the guarantees that generic code written against AsValidated relies on.

Examples

Borrowing &[u8] as &str when the bytes are valid UTF-8:

let bytes: &[u8] = b"hello";
let validated: MaybeValidRef<'_, str, [u8]> = bytes.as_validated();
match validated {
    MaybeValidRef::Valid(s) => {
        assert_eq!(s, "hello");
    }
    MaybeValidRef::Invalid(bytes, reason) => {
        eprintln!(
            "invalid at byte {} of {} total",
            reason.valid_up_to(),
            bytes.len(),
        );
    }
}

The &str returned in the valid branch aliases the original byte slice. No allocation occurred, and the bytes remain accessible through both the bytes binding and the Invalid branch’s first component.

Relationship to IntoValidated

AsValidated and IntoValidated are peers: the first borrows, the second consumes. A type that can be validated by borrow can typically also be validated by ownership. Both route through the same Validated target type and share its InvalidReason.

Paired borrowed/owned validated types — such as str / String or CStr / CString — should share an InvalidReason so that MaybeValidRef::into_owned (when the alloc feature is enabled) can convert between them without requiring a reason-type conversion.

Required Methods

fn as_validated(&self) -> MaybeValidRef<'_, V, Self>

Borrows self as a validated V, if valid.

Returns MaybeValidRef::Valid(&v) when self satisfies V’s predicate, with v aliasing memory in self. Returns MaybeValidRef::Invalid(&self, reason) otherwise, with the precursor reference and the diagnostic reason.

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.

Implementations on Foreign Types

impl AsValidated<str> for [u8]

fn as_validated(&self) -> MaybeValidRef<'_, str, Self>

impl AsValidated<CStr> for [u8]

fn as_validated(&self) -> MaybeValidRef<'_, CStr, Self>

impl AsValidated<NonZero<i8>> for i8

fn as_validated(&self) -> MaybeValidRef<'_, NonZeroI8, i8>

impl AsValidated<NonZero<i16>> for i16

fn as_validated(&self) -> MaybeValidRef<'_, NonZeroI16, i16>

impl AsValidated<NonZero<i32>> for i32

fn as_validated(&self) -> MaybeValidRef<'_, NonZeroI32, i32>

impl AsValidated<NonZero<i64>> for i64

fn as_validated(&self) -> MaybeValidRef<'_, NonZeroI64, i64>

impl AsValidated<NonZero<i128>> for i128

fn as_validated(&self) -> MaybeValidRef<'_, NonZeroI128, i128>

impl AsValidated<NonZero<isize>> for isize

fn as_validated(&self) -> MaybeValidRef<'_, NonZeroIsize, isize>

impl AsValidated<NonZero<u8>> for u8

fn as_validated(&self) -> MaybeValidRef<'_, NonZeroU8, u8>

impl AsValidated<NonZero<u16>> for u16

fn as_validated(&self) -> MaybeValidRef<'_, NonZeroU16, u16>

impl AsValidated<NonZero<u32>> for u32

fn as_validated(&self) -> MaybeValidRef<'_, NonZeroU32, u32>

impl AsValidated<NonZero<u64>> for u64

fn as_validated(&self) -> MaybeValidRef<'_, NonZeroU64, u64>

impl AsValidated<NonZero<u128>> for u128

fn as_validated(&self) -> MaybeValidRef<'_, NonZeroU128, u128>

impl AsValidated<NonZero<usize>> for usize

fn as_validated(&self) -> MaybeValidRef<'_, NonZeroUsize, usize>

Implementors