Enum MaybeValidRef 

pub enum MaybeValidRef<'a, V: Validated + ?Sized, P: ?Sized> {
    Valid(&'a V),
    Invalid(&'a P, V::InvalidReason),
}

The outcome of borrowing a value as a validated view of type V.

Returned by AsValidated::as_validated. Both variants carry a reference into the caller’s original value — the Valid variant as &V, the Invalid variant as &P (the precursor). The Invalid variant additionally carries the diagnostic reason.

Why the precursor is repeated in Invalid

On the invalid path, the caller could reach the precursor through their existing &self binding; including it in the Invalid variant is structurally redundant. It is retained anyway because:

• The type then honestly describes both outcomes as “a reference into the caller’s value, plus (on the invalid path) a reason.” Readers do not have to infer the precursor’s availability from context.

• The shape mirrors MaybeValidOwned, where the precursor must be returned structurally because consumption would otherwise lose it. Generic code and documentation can describe both enums in parallel.

• The cost is a pointer-sized move, not a clone or allocation.

Why both variants matter

MaybeValidRef is deliberately not a Result. The Invalid variant is not an error to handle and discard: it is a structured peer of Valid, describing the state of data the caller may wish to continue working with (rendering a partial view, producing a repair, emitting a diagnostic that references the caller’s own bytes).

Examples

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(),
        );
    }
}

Construction

MaybeValidRef values are produced by AsValidated implementations. Direct construction is public and unrestricted: V’s own invariants are enforced by V, not by this enum.

Variants

Valid(&'a V)

The borrowed value satisfies V’s predicate.

Invalid(&'a P, V::InvalidReason)

The borrowed value does not satisfy V’s predicate.

Holds a reference to the original precursor (aliasing the caller’s value) and the diagnostic reason.

Implementations

impl<'a, V: Validated + ?Sized, P: ?Sized> MaybeValidRef<'a, V, P>

pub fn is_valid(&self) -> bool

Returns true if this is the Valid variant.

pub fn is_invalid(&self) -> bool

Returns true if this is the Invalid variant.

pub fn valid(self) -> Option<&'a V>

Returns the validated reference, or None if invalid.

pub fn invalid_precursor(self) -> Option<&'a P>

Returns the precursor reference on the invalid path, or None if valid.

pub fn invalid_reason(self) -> Option<V::InvalidReason>

Returns the invalid reason, or None if valid.

Discards the precursor reference; use invalid_parts to retain both.

pub fn invalid_parts(self) -> Option<(&'a P, V::InvalidReason)>

Returns the precursor reference and reason on the invalid path, or None if valid.

pub fn as_ref(&self) -> MaybeValidRef<'_, V, P>

where V::InvalidReason: Clone,

Returns a MaybeValidRef that borrows from this one, with the same variant structure.

Useful when a caller holds a MaybeValidRef by value but needs to inspect it without consuming it. The returned value borrows the precursor/validated references from self and clones the InvalidReason on the invalid path.

pub fn into_result(self) -> Result<&'a V, (&'a P, V::InvalidReason)>

Converts into a Result, discarding the peer framing and bundling the precursor reference into the error.

Useful when integrating with code written against Result and ?, at the cost of the explicit-match ergonomics MaybeValidRef encourages.

pub fn into_result_reason_only(self) -> Result<&'a V, V::InvalidReason>

Converts into a Result that carries only the reason on the error path, discarding the precursor reference.

Prefer into_result when the precursor is still useful to the caller; this method is a convenience for call sites that only need the diagnostic.

impl<'a, V, P> MaybeValidRef<'a, V, P>

where V: Validated + ToOwned + ?Sized, V::Owned: Validated<InvalidReason = V::InvalidReason>, P: ToOwned + ?Sized,

pub fn into_owned(self) -> MaybeValidOwned<V::Owned, P::Owned>

Produces an owned version of this outcome by cloning the borrowed V (or P) into its owned form.