Enum Variance 

#[repr(u8)]
pub enum Variance {
    Covariant = 0,
    Contravariant = 1,
    Invariant = 2,
}

Variance of a type with respect to its type/lifetime parameters.

See:

• Rust Reference: Subtyping and Variance
• Rust Reference: Variance of built-in types
• The Rustonomicon: Subtyping and Variance

Variants

Covariant = 0

Type is covariant: can safely shrink lifetimes ('static → 'a).

A type F<T> is covariant if F<Sub> is a subtype of F<Super> when Sub is a subtype of Super. This means the type “preserves” the subtyping relationship.

Examples: &'a T, *const T, Box<T>, Vec<T>, [T; N]

See Rust Reference: Covariance

Contravariant = 1

Type is contravariant: can safely grow lifetimes ('a → 'static).

A type F<T> is contravariant if F<Super> is a subtype of F<Sub> when Sub is a subtype of Super. This means the type “reverses” the subtyping relationship.

Examples: fn(T) is contravariant in T

See Rust Reference: Contravariance

Invariant = 2

Type is invariant: no lifetime or type parameter changes allowed.

A type F<T> is invariant if neither F<Sub> nor F<Super> is a subtype of the other, regardless of the relationship between Sub and Super.

Examples: &'a mut T (invariant in T), Cell<T>, UnsafeCell<T>, *mut T

See Rust Reference: Invariance

Implementations

impl Variance

pub const COVARIANT: fn(&'static Shape) -> Variance = {types::variance::covariant as fn(&'static types::shape::Shape) -> types::variance::Variance}

Function that returns Variance::Covariant.

Use this for types that are covariant over their type/lifetime parameter, such as &'a T, *const T, Box<T>, Vec<T>, [T; N].

Also use for types with no lifetime parameters (like i32, String), since they impose no constraints on lifetimes.

See Rust Reference: Variance of built-in types

pub const CONTRAVARIANT: fn(&'static Shape) -> Variance = {types::variance::contravariant as fn(&'static types::shape::Shape) -> types::variance::Variance}

Function that returns Variance::Contravariant.

Use this for types that are contravariant over their type/lifetime parameter, such as fn(T) (contravariant in T).

See Rust Reference: Variance of built-in types

pub const INVARIANT: fn(&'static Shape) -> Variance = {types::variance::invariant as fn(&'static types::shape::Shape) -> types::variance::Variance}

Function that returns Variance::Invariant.

Use this for types that are invariant over their type/lifetime parameter, such as &'a mut T (invariant in T), *mut T, Cell<T>, UnsafeCell<T>.

This is the safe default when variance is unknown.

See Rust Reference: Variance of built-in types

pub const fn combine(self, other: Variance) -> Variance

Combine two variances (used when a type contains multiple lifetime-carrying fields).

The rules follow Rust’s variance composition:

• Same variance: keep it
• Mixed covariant/contravariant: becomes invariant
• Invariant dominates everything

pub const fn flip(self) -> Variance

Flip variance (used when type appears in contravariant position, like fn args).

• Covariant ↔ Contravariant
• Invariant stays Invariant

pub const fn can_shrink(self) -> bool

Returns true if lifetimes can be safely shrunk ('static → 'a).

pub const fn can_grow(self) -> bool

Returns true if lifetimes can be safely grown ('a → 'static).

Trait Implementations

impl Clone for Variance

fn clone(&self) -> Variance

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Variance

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Variance

fn default() -> Variance

Returns the “default value” for a type.

impl Hash for Variance

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Variance

fn eq(&self, other: &Variance) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Variance

impl Eq for Variance

impl StructuralPartialEq for Variance