Struct abi_stable::nonexhaustive_enum::NonExhaustive

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

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.

Examples

Error type

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),
)))]
#[non_exhaustive]
pub enum Error {
    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),
)))]
#[non_exhaustive]
pub enum Error {
    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.

Static enums

This example demonstrates putting a nonexhaustive enum in a static.

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

static AA: NonExhaustiveFor<Foo> = NonExhaustive::new(Foo::A);

static BB: NonExhaustiveFor<Foo> = NonExhaustive::new(Foo::B(2));

let cc = NonExhaustive::new(Foo::C {name: "hello".into()});

assert_eq!(AA, Foo::A);
assert_eq!(BB, Foo::B(2));
assert_eq!(cc, Foo::C {name: RString::from("hello")});


#[repr(u8)]
#[derive(StableAbi, Debug, PartialEq, Eq)]
#[sabi(kind(WithNonExhaustive(
    size = 64,
    traits(Debug, PartialEq, Eq)
)))]
pub enum Foo {
    A,
    B(i8),
    C { name: RString },
}

Implementations

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

pub const fn new(value: E) -> Self

where E: GetVTable<S, I> + GetEnumInfo<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 const fn with_interface(value: E) -> Self

where E: GetVTable<S, I> + GetEnumInfo<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 const fn with_storage(value: E) -> Self

where E: GetVTable<S, I> + GetEnumInfo<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 const 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.

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 const fn get_discriminant(&self) -> E::Discriminant

Gets the value of the discriminant of the enum.

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

pub const 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 const 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> + 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>

where E: GetEnumInfo,

pub fn serialize_into_proxy(&self) -> Result<I::Proxy, RBoxError>

where I: InterfaceType<Serialize = Implemented<Serialize>> + SerializeEnum<E>,

It serializes a NonExhaustive<_> into a proxy.

pub fn deserialize_from_proxy<'borr>(proxy: I::Proxy) -> Result<Self, RBoxError>

where I: InterfaceType<Deserialize = Implemented<Deserialize>> + DeserializeEnum<'borr, Self>, I::Proxy: 'borr,

Deserializes a NonExhaustive<_> from a proxy.

Trait Implementations

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

where I: InterfaceType<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: InterfaceType<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 + InterfaceType<Deserialize = Implemented<Deserialize>> + DeserializeEnum<'de, Self>, <I as DeserializeEnum<'de, Self>>::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: InterfaceType<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: InterfaceType<Debug = Implemented<Debug>, Display = Implemented<Display>, Error = Implemented<Error>>,

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

Returns the lower-level source of this error, if any.

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

fn provide<'a>(&'a self, request: &mut Request<'a>)

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

Provides type-based access to context intended for error reports.

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

where E: __GetStaticEquivalent_ + NonExhaustiveMarker<S>, S: __GetStaticEquivalent_, I: __GetStaticEquivalent_ + InterfaceType, NonExhaustiveVtable_Ref<E, S, I>: StableAbi,

type StaticEquivalent = _static_NonExhaustive<<E as GetStaticEquivalent_>::StaticEquivalent, <S as GetStaticEquivalent_>::StaticEquivalent, <I as GetStaticEquivalent_>::StaticEquivalent>

The 'static equivalent of Self

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

where I: InterfaceType<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, Self: Sized,

Feeds a slice of this type into the given Hasher.

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

where E: GetEnumInfo,

type Discriminant = <E as GetEnumInfo>::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 as GetEnumInfo>::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> NonExhaustiveSharedOps for NonExhaustive<E, S, I>

where E: GetEnumInfo,

type Discriminant = <E as GetEnumInfo>::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: InterfaceType<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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

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

where E: GetEnumInfo + PartialEq, I: InterfaceType<PartialEq = Implemented<PartialEq>>,

fn eq(&self, other: &E) -> 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<E, S, I1, I2> PartialEq<NonExhaustive<E, S, I2>> for NonExhaustive<E, S, I1>

where I1: InterfaceType<PartialEq = Implemented<PartialEq>>,

fn eq(&self, other: &NonExhaustive<E, S, I2>) -> 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<E, S, I> PartialOrd<E> for NonExhaustive<E, S, I>

where E: GetEnumInfo + PartialOrd, I: InterfaceType<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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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: InterfaceType<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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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: InterfaceType<Serialize = Implemented<Serialize>> + SerializeEnum<E>, 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_ + NonExhaustiveMarker<S>, S: __GetStaticEquivalent_, I: __GetStaticEquivalent_ + InterfaceType, NonExhaustiveVtable_Ref<E, S, I>: StableAbi, <E as NonExhaustiveMarker<S>>::Marker: __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: InterfaceType<Eq = Implemented<Eq>>,