Struct abi_stable::prefix_type::PrefixRef

#[repr(transparent)]pub struct PrefixRef<P> { /* fields omitted */ }

A reference to a prefix type.

This is the type that all *_Ref pointer types generated by StableAbi wrap.

Example

use abi_stable::{
    StableAbi,
    staticref,
    prefix_type::{PrefixRef, PrefixTypeTrait, WithMetadata},
};
 
fn main(){
    // `Module_Ref`'s constructor can also be called at compile-time
    asserts(Module_Ref(PREFIX_A));
    asserts(Module_Ref(PREFIX_B));
}
 
fn asserts(module: Module_Ref){
    assert_eq!(module.first(), 5);
    assert_eq!(module.second(), 8);
    
    // If this Module_Ref had come from a previous version of the library without a
    // `third` field it would return `None`.
    assert_eq!(module.third(), Some(13));
}

 
 
#[repr(C)]
#[derive(StableAbi)]
#[sabi(kind(Prefix(prefix_ref = "Module_Ref", prefix_fields = "Module_Prefix")))]
struct Module{
    first: usize,
    // The `#[sabi(last_prefix_field)]` attribute here means that this is 
    // the last field in this struct that was defined in the 
    // first compatible version of the library,
    // requiring new fields to always be added after it.
    // Moving this attribute is a breaking change, it can only be done in a 
    // major version bump..
    #[sabi(last_prefix_field)]
    second: usize,
    third: usize,
}
 
const MOD_VAL: Module = Module{
    first: 5,
    second: 8,
    third: 13,
};
 
/////////////////////////////////////////
// First way to construct a PrefixRef 
// This is a way that PrefixRef can be constructed in statics
 
const PREFIX_A: PrefixRef<Module_Prefix> = {
    WithMetadata::new(PrefixTypeTrait::METADATA, MOD_VAL)
        .static_as_prefix()
};
 
/////////////////////////////////////////
// Second way to construct a PrefixRef
// This is a way that PrefixRef can be constructed in associated constants,
 
// This macro declares a `StaticRef` pointing to the assigned `WithMetadata`.
staticref!(const MOD_WM: WithMetadata<Module> = {
    WithMetadata::new(PrefixTypeTrait::METADATA, MOD_VAL)
});

const PREFIX_B: PrefixRef<Module_Prefix> = MOD_WM.as_prefix();

 
/////////////////////////////////////////
 
 

Implementations

impl<P> PrefixRef<P>

pub const unsafe fn from_raw<T>(ptr: *const WithMetadata_<T, P>) -> Self

Constructs a PrefixRef from a raw pointer.

Safety

The pointer must be a non-dangling pointer to a valid, initialized instance of T, and live for the rest of the program's lifetime (if called at compile-time it means live for the entire program).

T must implement PrefixTypeTrait<Fields = P>, this is automatically true if this is called with &WithMetadata::new(PrefixTypeTrait::METADATA, <value>).

Example

use abi_stable::{
    for_examples::{Module, Module_Prefix, Module_Ref},
    prefix_type::{PrefixRef, PrefixTypeTrait, WithMetadata},
    std_types::*,
    rstr,
};
 
const MOD_WM: *const WithMetadata<Module> = {
    &WithMetadata::new(PrefixTypeTrait::METADATA, Module{
        first: RSome(3),
        second: rstr!("hello"),
        third: 8,
    })
};

const PREFIX: PrefixRef<Module_Prefix> = unsafe{ PrefixRef::from_raw(MOD_WM) };
 
const MODULE: Module_Ref = Module_Ref(PREFIX);
 
 
assert_eq!(MODULE.first(), RSome(3));
 
assert_eq!(MODULE.second().as_str(), "hello");
 
// The accessor returns an `Option` because the field comes after the prefix,
// and returning an Option is the default for those.
assert_eq!(MODULE.third(), Some(8)); 
 

pub const fn from_staticref<T>(ptr: StaticRef<WithMetadata_<T, P>>) -> Self

Constructs a PrefixRef from a StaticRef.

Example

use abi_stable::{
    for_examples::{Module, Module_Prefix, Module_Ref},
    prefix_type::{PrefixRef, PrefixTypeTrait, WithMetadata},
    std_types::*,
    rstr, staticref,
};
 
// This macro invocation declares a `StaticRef<WithMetadata<Module>>` constant
staticref!(const MOD_WM: WithMetadata<Module> = {
    WithMetadata::new(PrefixTypeTrait::METADATA, Module{
        first: RNone,
        second: rstr!("world"),
        third: 13,
    })
});

const PREFIX: PrefixRef<Module_Prefix> = PrefixRef::from_staticref(MOD_WM);
 
const MODULE: Module_Ref = Module_Ref(PREFIX);
 
 
assert_eq!(MODULE.first(), RNone);
 
assert_eq!(MODULE.second().as_str(), "world");
 
// The accessor returns an `Option` because the field comes after the prefix,
// and returning an Option is the default for those.
assert_eq!(MODULE.third(), Some(13)); 
 

pub const fn from_ref<T>(ptr: &'static WithMetadata_<T, P>) -> Self

Constructs a PrefixRef from a static reference.

Example

use abi_stable::{
    for_examples::{Module, Module_Prefix, Module_Ref},
    prefix_type::{PrefixRef, PrefixTypeTrait, WithMetadata},
    std_types::*,
    rstr,
};
 
const MOD_WM: &WithMetadata<Module> = {
    &WithMetadata::new(PrefixTypeTrait::METADATA, Module{
        first: RNone,
        second: rstr!("foo"),
        third: 21,
    })
};

const PREFIX: PrefixRef<Module_Prefix> = PrefixRef::from_ref(MOD_WM);
 
const MODULE: Module_Ref = Module_Ref(PREFIX);
 
 
assert_eq!(MODULE.first(), RNone);
 
assert_eq!(MODULE.second().as_str(), "foo");
 
// The accessor returns an `Option` because the field comes after the prefix,
// and returning an Option is the default for those.
assert_eq!(MODULE.third(), Some(21)); 
 

pub fn metadata(self) -> PrefixMetadata<P, P>

Gets the metadata about the prefix type, including available fields.

Example

use abi_stable::{
    for_examples::{Module, Module_Prefix},
    prefix_type::{PrefixRef, PrefixTypeTrait, WithMetadata},
    std_types::*,
};
 
const MOD_WM: &WithMetadata<Module> = {
    &WithMetadata::new(PrefixTypeTrait::METADATA, Module{
        first: RNone,
        second: RStr::empty(),
        third: 0,
    })
};

const PREFIX: PrefixRef<Module_Prefix> = PrefixRef::from_ref(MOD_WM);
 
let accessibility = PREFIX.metadata().field_accessibility();
 
assert!( accessibility.is_accessible(0) ); // The `first` field
assert!( accessibility.is_accessible(1) ); // The `second` field
assert!( accessibility.is_accessible(2) ); // The `third` field
assert!( !accessibility.is_accessible(3) ); // There's no field after `third`
 

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

Gets a reference to the pointed-to prefix.

Example

use abi_stable::{
    for_examples::{Module, Module_Prefix},
    prefix_type::{PrefixRef, PrefixTypeTrait, WithMetadata},
    std_types::*,
    rstr,
};
 
const MOD_WM: &WithMetadata<Module> = {
    &WithMetadata::new(PrefixTypeTrait::METADATA, Module{
        first: RNone,
        second: rstr!("foo"),
        third: 21,
    })
};

const PREFIX_REF: PrefixRef<Module_Prefix> = PrefixRef::from_ref(MOD_WM);
 
let prefix: &Module_Prefix = PREFIX_REF.prefix();
 
assert_eq!(prefix.first, RNone);
 
assert_eq!(prefix.second.as_str(), "foo");
 
// The `third` field is not in the prefix, so it can't be accessed here.
// prefix.third;
 

pub fn to_raw_ptr(self) -> *const WithMetadata_<P, P>

Converts this PrefixRef into a raw pointer.

pub const fn const_to_raw_ptr(self) -> *const WithMetadata_<P, P>

A const-callable version of to_raw_ptr, use to_raw_ptr in non-const code instead of this.

to_raw_ptr exists for efficiency-in-debug-build reasons.

pub const unsafe fn cast<U>(self) -> PrefixRef<U>

Casts the pointed-to prefix to another type.

Safety

This function is intended for casting the PrefixRef<P> to PrefixRef<U>, and then cast back to PrefixRef<P> to use it again.

The prefix in the returned PrefixRef<U> must only be accessed when this PrefixRef was originally cosntructed with a ẀithMetadata_<_, U>. access includes calling prefix, and reading the value field in the WithMetadata that this points to.

Trait Implementations

impl<P> Clone for PrefixRef<P>

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<P> Copy for PrefixRef<P>

impl<P> Debug for PrefixRef<P>

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

Formats the value using the given formatter.

impl<P> GetStaticEquivalent_ for PrefixRef<P> where
    P: GetStaticEquivalent_, 

type StaticEquivalent = PrefixRef<GetStaticEquivalent<P>>

impl<P> ImmutableRef for PrefixRef<P>

type Target = WithMetadata_<P, P>

The referent of the pointer, what it points to.

pub const TARGET: ImmutableRefTarget<Self, Self::Target>

A marker type that can be used as a proof that the T type parameter of ImmutableRefTarget<T, U> implements ImmutableRef<Target = U>.

pub fn to_nonnull(self) -> NonNull<Self::Target>

Converts this pointer to a NonNull.

pub unsafe fn from_nonnull(from: NonNull<Self::Target>) -> Self

Constructs this pointer from a NonNull.

pub fn to_raw_ptr(self) -> *const Self::Target

Converts this pointer to a raw pointer.

pub unsafe fn from_raw_ptr(from: *const Self::Target) -> Option<Self>

Constructs this pointer from a raw pointer.

impl<P> PrefixRefTrait for PrefixRef<P>

type PrefixFields = P

A struct that contains all the fields of some other struct up to the field annotated with #[sabi(last_prefix_field)] inclusive.

pub const PREFIX_FIELDS: PointsToPrefixFields<Self, Self::PrefixFields>

A type used to prove that the This type parameter in PointsToPrefixFields<This, PF> implements PrefixRefTrait<PrefixFields = PF>.

pub fn from_prefix_ref(this: PrefixRef<Self::PrefixFields>) -> Self

Converts a PrefixRef to Self

pub fn to_prefix_ref(self) -> PrefixRef<Self::PrefixFields>

Converts Self to a PrefixRef

impl<'a, P: 'a> Send for PrefixRef<P> where
    &'a WithMetadata_<P, P>: Send, 

impl<P> StableAbi for PrefixRef<P> where
    P: PrefixStableAbi, 

type IsNonZeroType = True

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.

impl<'a, P: 'a> Sync for PrefixRef<P> where
    &'a WithMetadata_<P, P>: Sync,