Struct abi_stable::nonexhaustive_enum::NonExhaustive

#[repr(C)]
pub struct NonExhaustive<E, S, I> { /* fields omitted */ }

A generic type for all ffi-safe non-exhaustive enums.

This type allows adding variants to enums it wraps in ABI compatible versions of a library.

Generic parameters

E

This is the enum that this was constructed from, and can be unwrapped back into if it’s one of the valid variants in this context.

S

The storage type,used to store the enum opaquely.

This has to be at least the size and alignment of the wrapped enum.

This is necessary because:

• The compiler assumes that an enum cannot be a variant outside the ones it sees.

• To give some flexibility to grow the enum in semver compatible versions of a library.

I

The interface of the enum(it implements InterfaceType), determining which traits are required when constructing NonExhaustive<> and which are available afterwards.

Example

Say that we define an error type for a library.

Version 1.0.

use abi_stable::{
    nonexhaustive_enum::{NonExhaustive, NonExhaustiveFor},
    sabi_trait,
    std_types::RString,
    StableAbi,
};

#[repr(u8)]
#[derive(StableAbi, Debug, Clone, PartialEq)]
#[sabi(kind(WithNonExhaustive(
    size = "[usize;8]",
    traits(Debug, Clone, PartialEq),
)))]
pub enum Error {
    #[doc(hidden)]
    __NonExhaustive,
    CouldNotFindItem {
        name: RString,
    },
    OutOfStock {
        id: usize,
        name: RString,
    },
}

fn returns_could_not_find_item(name: RString) -> NonExhaustiveFor<Error> {
    let e = Error::CouldNotFindItem { name };
    NonExhaustive::new(e)
}

fn returns_out_of_stock(id: usize, name: RString) -> NonExhaustiveFor<Error> {
    let e = Error::OutOfStock { id, name };
    NonExhaustive::new(e)
}

Then in 1.1 we add another error variant,returned only by new library functions.

use abi_stable::{
    nonexhaustive_enum::{NonExhaustive, NonExhaustiveFor},
    sabi_trait,
    std_types::RString,
    StableAbi,
};

#[repr(u8)]
#[derive(StableAbi, Debug, Clone, PartialEq)]
#[sabi(kind(WithNonExhaustive(
    size = "[usize;8]",
    traits(Debug, Clone, PartialEq),
)))]
pub enum Error {
    #[doc(hidden)]
    __NonExhaustive,
    CouldNotFindItem {
        name: RString,
    },
    OutOfStock {
        id: usize,
        name: RString,
    },
    InvalidItemId {
        id: usize,
    },
}

fn returns_invalid_item_id() -> NonExhaustiveFor<Error> {
    NonExhaustive::new(Error::InvalidItemId { id: 100 })
}

If a library user attempted to unwrap Error::InvalidItemId (using NonExhaustive::as_enum/as_enum_mut/into_enum) with the 1.0 version of Error they would get an Err(..) back.

Implementations

impl<E, S, I> NonExhaustive<E, S, I>

pub fn new(value: E) -> Self where
    E: GetVTable<S, I, DefaultStorage = S, DefaultInterface = I>, 

Constructs a NonExhaustive<> from value using its default interface and storage.

Panic

This panics if the storage has an alignment or size smaller than that of E.

pub fn with_interface(value: E) -> Self where
    E: GetVTable<S, I, DefaultStorage = S>, 

Constructs a NonExhaustive<> from value using its default storage and a custom interface.

Panic

This panics if the storage has an alignment or size smaller than that of E.

pub fn with_storage(value: E) -> Self where
    E: GetVTable<S, I, DefaultInterface = I>, 

Constructs a NonExhaustive<> from value using its default interface and a custom storage.

Panic

This panics if the storage has an alignment or size smaller than that of E.

pub fn with_storage_and_interface(value: E) -> Self where
    E: GetVTable<S, I>, 

Constructs a NonExhaustive<> from value using both a custom interface and storage.

Panic

This panics if the storage has an alignment or size smaller than that of E.

pub fn check_alignment() -> bool

Checks that the alignment of E is correct,returning true if it is.

pub fn check_size() -> bool

Checks that the size of E is correct,returning true if it is.

pub fn assert_fits_within_storage()

Asserts that E fits within S,with the correct alignment and size.

impl<E, S, I> NonExhaustive<E, S, I> where
    E: GetEnumInfo, 

pub fn as_enum(&self) -> Result<&E, UnwrapEnumError<&Self>>

wraps a reference to this NonExhaustive<> into a reference to the original enum.

Errors

This returns an error if the wrapped enum is of a variant that is not valid in this context.

Example

This shows how some NonExhaustive<enum> can be unwrapped, and others cannot.
That enum comes from a newer version of the library than this knows.

use abi_stable::nonexhaustive_enum::doc_enums::example_2::{
    new_a, new_b, new_c, Foo,
};

assert_eq!(new_a().as_enum().ok(), Some(&Foo::A));
assert_eq!(new_b(10).as_enum().ok(), Some(&Foo::B(10)));
assert_eq!(new_b(77).as_enum().ok(), Some(&Foo::B(77)));
assert_eq!(new_c().as_enum().ok(), None);

pub fn as_enum_mut(&mut self) -> Result<&mut E, UnwrapEnumError<&mut Self>> where
    E: GetVTable<S, I>, 

Unwraps a mutable reference to this NonExhaustive<> into a mutable reference to the original enum.

Errors

This returns an error if the wrapped enum is of a variant that is not valid in this context.

Example

This shows how some NonExhaustive<enum> can be unwrapped, and others cannot.
That enum comes from a newer version of the library than this knows.

use abi_stable::nonexhaustive_enum::doc_enums::example_1::{
    new_a, new_b, new_c, Foo,
};

assert_eq!(new_a().as_enum_mut().ok(), Some(&mut Foo::A));
assert_eq!(new_b(10).as_enum_mut().ok(), None);
assert_eq!(new_b(77).as_enum_mut().ok(), None);
assert_eq!(new_c().as_enum_mut().ok(), None);

pub fn into_enum(self) -> Result<E, UnwrapEnumError<Self>>

Unwraps this NonExhaustive<> into the original enum.

Errors

This returns an error if the wrapped enum is of a variant that is not valid in this context.

Example

This shows how some NonExhaustive<enum> can be unwrapped, and others cannot.
That enum comes from a newer version of the library than this knows.

use abi_stable::nonexhaustive_enum::doc_enums::example_2::{
    new_a, new_b, new_c, Foo,
};

assert_eq!(new_a().into_enum().ok(), Some(Foo::A));
assert_eq!(new_b(10).into_enum().ok(), Some(Foo::B(10)));
assert_eq!(new_b(77).into_enum().ok(), Some(Foo::B(77)));
assert_eq!(new_c().into_enum().ok(), None);

pub fn is_valid_discriminant(&self) -> bool

Returns whether the discriminant of this enum is valid in this context.

The only way for it to be invalid is if the dynamic library is a newer version than this knows.

pub fn get_discriminant(&self) -> E::Discriminant

Gets the value of the discriminant of the enum.

impl<E, S, I> NonExhaustive<E, S, I>

pub unsafe fn transmute_enum<F>(self) -> NonExhaustive<F, S, I>

Transmute this NonExhaustive<E,S,I> into NonExhaustive<F,S,I>, changing the type of the enum it wraps.

Safety

This has the same safety requirements that std::mem::transmute has.

Panics

This panics if the storage has an alignment or size smaller than that of F.

pub unsafe fn transmute_enum_ref<F>(&self) -> &NonExhaustive<F, S, I>

Transmute this &NonExhaustive<E,S,I> into &NonExhaustive<F,S,I>, changing the type of the enum it wraps.

Safety

This has the same safety requirements that std::mem::transmute has.

Panics

This panics if the storage has an alignment or size smaller than that of F.

pub unsafe fn transmute_enum_mut<F>(&mut self) -> &mut NonExhaustive<F, S, I>

Transmute this &mut NonExhaustive<E,S,I> into &mut NonExhaustive<F,S,I>, changing the type of the enum it wraps.

Safety

This has the same safety requirements that std::mem::transmute has.

Panics

This panics if the storage has an alignment or size smaller than that of F.

pub unsafe fn transmute_enum_ptr<P, F>(this: P) -> P::TransmutedPtr where
    P: Deref<Target = Self>,
    P: CanTransmuteElement<NonExhaustive<F, S, I>>, 

Transmute this pointer to a NonExhaustive<E,S,I> into a pointer (of the same kind) to a NonExhaustive<F,S,I>, changing the type of the enum it wraps.

Safety

This has the same safety requirements that abi_stable::pointer_traits::TransmuteElement::transmute_element has.

Panics

This panics if the storage has an alignment or size smaller than that of F.

impl<E, S, I> NonExhaustive<E, S, I>

pub fn serialize_into_proxy(&self) -> Result<I::Proxy, RBoxError> where
    I: InterfaceBound<Serialize = Implemented<Serialize>>,
    I: SerializeEnum<NonExhaustive<E, S, I>>, 

It serializes a NonExhaustive<_> into a proxy.

pub fn deserialize_from_proxy<'borr>(proxy: I::Proxy) -> Result<Self, RBoxError> where
    I: InterfaceBound<Deserialize = Implemented<Deserialize>>,
    I: DeserializeEnum<'borr, NonExhaustive<E, S, I>>,
    I::Proxy: 'borr,
    E: GetEnumInfo, 

Deserializes a NonExhaustive<_> from a proxy.

Trait Implementations

impl<E, S, I> Clone for NonExhaustive<E, S, I> where
    I: InterfaceBound<Clone = Implemented<Clone>>, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<E, S, I> Debug for NonExhaustive<E, S, I> where
    I: InterfaceBound<Debug = Implemented<Debug>>, 

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

Formats the value using the given formatter.

impl<'de, E, S, I> Deserialize<'de> for NonExhaustive<E, S, I> where
    E: 'de + GetVTable<S, I>,
    S: 'de,
    I: 'de + InterfaceBound<Deserialize = Implemented<Deserialize>>,
    I: DeserializeEnum<'de, NonExhaustive<E, S, I>>,
    <I as DeserializeEnum<'de, NonExhaustive<E, S, I>>>::Proxy: Deserialize<'de>, 

First it Deserializes a string,then it deserializes into a NonExhaustive<_>,by using <I as DeserializeEnum>::deserialize_enum.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<E, S, I> Display for NonExhaustive<E, S, I> where
    I: InterfaceBound<Display = Implemented<Display>>, 

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

Formats the value using the given formatter.

impl<E, S, I> Drop for NonExhaustive<E, S, I>

fn drop(&mut self)

Executes the destructor for this type.

impl<E, S, I> Error for NonExhaustive<E, S, I> where
    I: InterfaceBound<Debug = Implemented<Debug>, Display = Implemented<Display>, Error = Implemented<Error>>, 

fn source(&self) -> Option<&(dyn Error + 'static)>

The lower-level source of this error, if any.

fn backtrace(&self) -> Option<&Backtrace>

🔬 This is a nightly-only experimental API. (backtrace)

Returns a stack backtrace, if available, of where this error occurred.

fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎 Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

impl<E, S, I> GetStaticEquivalent_ for NonExhaustive<E, S, I> where
    E: __GetStaticEquivalent_,
    S: __GetStaticEquivalent_,
    I: __GetStaticEquivalent_,
    NonExhaustiveVtable_Ref<E, S, I>: StableAbi,
    E: GetNonExhaustive<S>,
    I: InterfaceBound, 

type StaticEquivalent = _static_NonExhaustive<__GetStaticEquivalent<E>, __GetStaticEquivalent<S>, __GetStaticEquivalent<I>>

impl<E, S, I> Hash for NonExhaustive<E, S, I> where
    I: InterfaceBound<Hash = Implemented<Hash>>, 

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl<E, S, I> NonExhaustiveSharedOps for NonExhaustive<E, S, I> where
    E: GetEnumInfo, 

type Discriminant = E::Discriminant

The type of the discriminant of the wrapped enum.

fn get_discriminant_(&self) -> E::Discriminant

Gets the discriminant of the wrapped enum.

fn enum_info_(&self) -> &'static EnumInfo

Gets miscelaneous information about the wrapped enum

impl<'a, E, S, I> NonExhaustiveSharedOps for &'a NonExhaustive<E, S, I> where
    E: GetEnumInfo, 

type Discriminant = E::Discriminant

The type of the discriminant of the wrapped enum.

fn get_discriminant_(&self) -> E::Discriminant

Gets the discriminant of the wrapped enum.

fn enum_info_(&self) -> &'static EnumInfo

Gets miscelaneous information about the wrapped enum

impl<'a, E, S, I> NonExhaustiveSharedOps for &'a mut NonExhaustive<E, S, I> where
    E: GetEnumInfo, 

type Discriminant = E::Discriminant

The type of the discriminant of the wrapped enum.

fn get_discriminant_(&self) -> E::Discriminant

Gets the discriminant of the wrapped enum.

fn enum_info_(&self) -> &'static EnumInfo

Gets miscelaneous information about the wrapped enum

impl<E, S, I> Ord for NonExhaustive<E, S, I> where
    I: InterfaceBound<Ord = Implemented<Ord>>,
    Self: PartialOrd + Eq, 

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<E, S, I> PartialEq<E> for NonExhaustive<E, S, I> where
    E: GetEnumInfo + PartialEq,
    I: InterfaceBound<PartialEq = Implemented<PartialEq>>, 

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<E, S, I1, I2> PartialEq<NonExhaustive<E, S, I2>> for NonExhaustive<E, S, I1> where
    I1: InterfaceBound<PartialEq = Implemented<PartialEq>>, 

fn eq(&self, other: &NonExhaustive<E, S, I2>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<E, S, I> PartialOrd<E> for NonExhaustive<E, S, I> where
    E: GetEnumInfo + PartialOrd,
    I: InterfaceBound<PartialOrd = Implemented<PartialOrd>>,
    Self: PartialEq<E>, 

fn partial_cmp(&self, other: &E) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<E, S, I1, I2> PartialOrd<NonExhaustive<E, S, I2>> for NonExhaustive<E, S, I1> where
    I1: InterfaceBound<PartialOrd = Implemented<PartialOrd>>,
    Self: PartialEq<NonExhaustive<E, S, I2>>, 

fn partial_cmp(&self, other: &NonExhaustive<E, S, I2>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<E, S, I> Serialize for NonExhaustive<E, S, I> where
    I: InterfaceBound<Serialize = Implemented<Serialize>>,
    I: SerializeEnum<NonExhaustive<E, S, I>>,
    I::Proxy: Serialize, 

First it serializes a NonExhaustive<_> into a proxy,then it serializes that proxy.

fn serialize<Z>(&self, serializer: Z) -> Result<Z::Ok, Z::Error> where
    Z: Serializer, 

Serialize this value into the given Serde serializer.

impl<E, S, I> StableAbi for NonExhaustive<E, S, I> where
    E: __GetStaticEquivalent_,
    S: __GetStaticEquivalent_,
    I: __GetStaticEquivalent_,
    NonExhaustiveVtable_Ref<E, S, I>: StableAbi,
    E: GetNonExhaustive<S>,
    I: InterfaceBound,
    <E as GetNonExhaustive<S>>::NonExhaustive: __StableAbi, 

type IsNonZeroType = False

Whether this type has a single invalid bit-pattern.

const LAYOUT: &'static TypeLayout

The layout of the type provided by implementors.

const ABI_CONSTS: AbiConsts

const-equivalents of the associated types.

impl<E, S, I> Eq for NonExhaustive<E, S, I> where
    Self: PartialEq,
    I: InterfaceBound<Eq = Implemented<Eq>>,