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::{
    StableAbi,
    nonexhaustive_enum::{NonExhaustiveFor,NonExhaustive},
    std_types::RString,
    sabi_trait,
};

#[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::{
    StableAbi,
    nonexhaustive_enum::{NonExhaustiveFor,NonExhaustive},
    std_types::RString,
    sabi_trait,
};

#[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>>

Unwraps 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::{Foo,new_a,new_b,new_c},
};

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::{Foo,new_a,new_b,new_c},
};

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::{Foo,new_a,new_b,new_c},
};

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>>, 

pub fn clone(&self) -> Self

Returns a copy of the value.

pub 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>>, 

pub 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.

pub 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>>, 

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

Formats the value using the given formatter.

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

pub fn drop(&mut self)

Executes the destructor for this type.

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

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

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

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

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

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

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

pub fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

pub 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>>, 

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

Feeds this value into the given Hasher.

pub 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.

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

Gets the discriminant of the wrapped enum.

pub 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.

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

Gets the discriminant of the wrapped enum.

pub 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.

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

Gets the discriminant of the wrapped enum.

pub 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, 

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

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

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

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>>, 

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

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

#[must_use]pub 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>>, 

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

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

#[must_use]pub 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>, 

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

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

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

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

#[must_use]pub fn le(&self, other: &Rhs) -> bool

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

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

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

#[must_use]pub 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>>, 

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

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

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

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

#[must_use]pub fn le(&self, other: &Rhs) -> bool

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

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

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

#[must_use]pub 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.

pub 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.

pub const LAYOUT: &'static TypeLayout

The layout of the type provided by implementors.

pub const ABI_CONSTS: AbiConsts

const-equivalents of the associated types.