Struct abi_stable::sabi_types::rsmallbox::RSmallBox

#[repr(C)]
pub struct RSmallBox<T, Inline> { /* fields omitted */ }

A box type which stores small values inline as an optimization.

Inline storage

Inline is the storage space on the stack (as in inline with the RSmallBox struct) where small values get stored,instead of storing them on the heap.

It has to have an alignment greater than or equal to the value being stored, otherwise storing the value on the heap.

To ensure that the inline storage has enough alignemnt you can use one of the AlignTo* types from the (reexported) alignment submodule, or from abi_stable::inline_storage::alignment.

Examples

In a nonexhaustive enum

Using an RSmallBox to store a generic type in a nonexhaustive enum.

use abi_stable::{
    sabi_types::RSmallBox,
    std_types::RString,
    reexports::SelfOps,
    StableAbi,
};

#[repr(u8)]
#[derive(StableAbi,Debug,Clone,PartialEq)]
#[sabi(kind(WithNonExhaustive(
    // Determines the maximum size of this enum in semver compatible versions.
    // This is 7 usize large because:
    //    - The enum discriminant occupies 1 usize(because the enum is usize aligned).
    //    - RSmallBox<T,[usize;4]>: is 6 usize large
    size="[usize;7]",
    // Determines the traits that are required when wrapping this enum in NonExhaustive,
    // and are then available with it.
    traits(Debug,Clone,PartialEq),
)))]
pub enum SomeEnum<T>{
    #[doc(hidden)]
    __NonExhaustive,
    Foo,
    Bar,
    // This variant was added in a newer (compatible) version of the library.
    Baz(RSmallBox<T,[usize;4]>)
}

impl<T> SomeEnum<T>{
    pub fn is_inline(&self)->bool{
        match self {
            SomeEnum::__NonExhaustive=>true,
            SomeEnum::Foo=>true,
            SomeEnum::Bar=>true,
            SomeEnum::Baz(rsbox)=>RSmallBox::is_inline(rsbox),
        }
    }

    pub fn is_heap_allocated(&self)->bool{
        !self.is_inline()
    }

}


#[repr(C)]
#[derive(StableAbi,Debug,Clone,PartialEq)]
pub struct FullName{
    pub name:RString,
    pub surname:RString,
}


let rstring="Oh boy!"
    .piped(RString::from)
    .piped(RSmallBox::new)
    .piped(SomeEnum::Baz);

let full_name=
    FullName{ name:"R__e".into(), surname:"L_____e".into() }
        .piped(RSmallBox::new)
        .piped(SomeEnum::Baz);


assert!( rstring.is_inline() );
assert!( full_name.is_heap_allocated() );

Trying out different Inline type parameters

This example demonstrates how changing the Inline type parameter can change whether an RString is stored inline or on the heap.

use abi_stable::{
    inline_storage::alignment::AlignToUsize,
    sabi_types::RSmallBox,
    std_types::RString,
    StableAbi,
};

use std::mem;

type JustRightInlineBox<T>=
    RSmallBox<T,AlignToUsize<[u8; mem::size_of::<usize>()*4 ]>>;

let string=RString::from("What is that supposed to mean?");

let small=RSmallBox::<_,[usize;3]>::new(string.clone());
let medium=RSmallBox::<_,[usize;4]>::new(string.clone());
let large=RSmallBox::<_,[usize;16]>::new(string.clone());
let not_enough_alignment=RSmallBox::<_,[u8;64]>::new(string.clone());
let just_right=JustRightInlineBox::new(string.clone());


assert!( RSmallBox::is_heap_allocated(&small) );
assert!( RSmallBox::is_inline(&medium) );
assert!( RSmallBox::is_inline(&large) );
assert!( RSmallBox::is_heap_allocated(&not_enough_alignment) );
assert!( RSmallBox::is_inline(&just_right) );

Methods

impl<T, Inline> RSmallBox<T, Inline>

pub fn new(value: T) -> RSmallBox<T, Inline> where
    Inline: InlineStorage, 

Constructs this RSmallBox from a value.

Example

use abi_stable::{
    sabi_types::RSmallBox,
    std_types::RString,
};
 
let xbox=RSmallBox::<_,[usize;4]>::new(RString::from("one"));
 

pub fn as_mut_ptr(this: &mut Self) -> *mut T

Gets a raw pointer into the underlying data.

Example

use abi_stable::{
    sabi_types::RSmallBox,
    std_types::RString,
};
 
let mut play=RSmallBox::<_,[usize;4]>::new(RString::from("station"));
 
let play_addr=&mut play as *mut RSmallBox<_,_> as usize;
let heap_addr=RSmallBox::as_mut_ptr(&mut play) as usize;
 
assert_eq!(play_addr,heap_addr);

pub fn as_ptr(this: &Self) -> *const T

Gets a raw pointer into the underlying data.

Example

use abi_stable::{
    sabi_types::RSmallBox,
    reexports::SelfOps,
    std_types::RVec,
};
 
let mut generations=vec![1,2,3,4,5,6,7,8]
    .piped(RVec::from)
    .piped(RSmallBox::<_,[usize;2]>::new);
 
let generations_addr=&mut generations as *mut RSmallBox<_,_> as usize;
let heap_addr=RSmallBox::as_ptr(&mut generations) as usize;
 
assert_ne!(generations_addr,heap_addr);

pub fn from_move_ptr(from_ptr: MovePtr<T>) -> Self where
    Inline: InlineStorage, 

Constructs this RSmallBox from a MovePtr.

Example

use abi_stable::{
    pointer_trait::OwnedPointer,
    sabi_types::RSmallBox,
    std_types::RBox,
};
 
let rbox=RBox::new(1000_u64);
let rsbox:RSmallBox<u64,[u64;1]>=
    rbox.in_move_ptr(|x| RSmallBox::<u64,[u64;1]>::from_move_ptr(x) );
 
assert_eq!( *rsbox, 1000_u64 );

pub fn move_<Inline2>(this: Self) -> RSmallBox<T, Inline2> where
    Inline2: InlineStorage, 

Converts this RSmallBox into another one with a differnet inline size.

Example

use abi_stable::sabi_types::RSmallBox;
 
let old=RSmallBox::<u64,[u8;4]>::new(599_u64);
assert!( ! RSmallBox::is_inline(&old) );

let new=RSmallBox::move_::<[u64;1]>(old);
assert!( RSmallBox::is_inline(&new) );
assert_eq!(*new,599_u64);

pub fn is_inline(this: &Self) -> bool

Queries whether the value is stored inline.

Example

use abi_stable::{
    sabi_types::RSmallBox,
    std_types::RString,
};
 
let heap=RSmallBox::<u64,[u8;4]>::new(599_u64);
assert!( ! RSmallBox::is_inline(&heap) );

let inline=RSmallBox::<RString,[usize;4]>::new("hello".into());
assert!( RSmallBox::is_inline(&inline) );

pub fn is_heap_allocated(this: &Self) -> bool

Queries whether the value is stored on the heap.

Example

use abi_stable::{
    sabi_types::RSmallBox,
    std_types::RHashMap,
};
 
let heap=RSmallBox::<_,[u8;4]>::new(String::new());
assert!( RSmallBox::is_heap_allocated(&heap) );

let inline=RSmallBox::<_,[usize;3]>::new(RHashMap::<u8,()>::new());
assert!( ! RSmallBox::is_heap_allocated(&inline) );

pub fn into_inner(this: Self) -> T

Unwraps this pointer into its owned value.

Example

use abi_stable::sabi_types::RSmallBox;
 
let rbox=RSmallBox::<_,[usize;3]>::new(vec![0,1,2]);
assert_eq!( RSmallBox::into_inner(rbox), vec![0,1,2] );

Trait Implementations

impl<T, Inline> GetStaticEquivalent_ for RSmallBox<T, Inline> where
    T: __StableAbi,
    Inline: __GetStaticEquivalent_, 

type StaticEquivalent = _static_RSmallBox<__GetStaticEquivalent<T>, __GetStaticEquivalent<Inline>>

impl<T, Inline> SharedStableAbi for RSmallBox<T, Inline> where
    T: __StableAbi,
    Inline: __GetStaticEquivalent_, 

type IsNonZeroType = False

Whether this type has a single invalid bit-pattern.

type Kind = __ValueKind

The kind of abi stability of this type,there are 2:

const S_LAYOUT: &'static TypeLayout

The layout of the type provided by implementors.

const S_ABI_CONSTS: AbiConsts

impl<T, Inline> GetPointerKind for RSmallBox<T, Inline>

type Kind = PK_SmartPointer

const KIND: PointerKind

impl<T, O, Inline> CanTransmuteElement<O> for RSmallBox<T, Inline>

type TransmutedPtr = RSmallBox<O, Inline>

The type of the pointer after it's element type has been changed.

impl<T, Inline> OwnedPointer for RSmallBox<T, Inline>

unsafe fn get_move_ptr(this: &mut ManuallyDrop<Self>) -> MovePtr<Self::Target>

Gets a move pointer to the contents of this pointer.

unsafe fn drop_allocation(this: &mut ManuallyDrop<Self>)

Deallocates the pointer without dropping its owned contents.

fn with_move_ptr<F, R>(this: ManuallyDrop<Self>, f: F) -> R where
    F: FnOnce(MovePtr<Self::Target>) -> R,
    Self::Target: Sized, 

fn in_move_ptr<F, R>(self, f: F) -> R where
    F: FnOnce(MovePtr<Self::Target>) -> R,
    Self::Target: Sized, 

impl<T: Send, Inline> Send for RSmallBox<T, Inline>

impl<T: Sync, Inline> Sync for RSmallBox<T, Inline>

impl<T, Inline> Drop for RSmallBox<T, Inline>

fn drop(&mut self)

Executes the destructor for this type.

impl<T, Inline> Into<RBox<T>> for RSmallBox<T, Inline> where
    Inline: InlineStorage, 

Converts a RSmallBox into an RBox,currently this allocates.

fn into(self) -> RBox<T>

Performs the conversion.

impl<T, Inline> From<RBox<T>> for RSmallBox<T, Inline> where
    Inline: InlineStorage, 

Converts an RBox into an RSmallBox,currently this allocates.

fn from(this: RBox<T>) -> Self

Performs the conversion.

impl<T, Inline> Clone for RSmallBox<T, Inline> where
    T: Clone,
    Inline: InlineStorage, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, Inline> Default for RSmallBox<T, Inline> where
    T: Default,
    Inline: InlineStorage, 

fn default() -> Self

Returns the "default value" for a type.

impl<T, Inline> Eq for RSmallBox<T, Inline> where
    T: Eq,
    Inline: Eq, 

impl<T, Inline> Ord for RSmallBox<T, Inline> where
    T: Ord,
    Inline: Ord, 

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

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

Restrict a value to a certain interval.

impl<T, Inline> PartialEq<RSmallBox<T, Inline>> for RSmallBox<T, Inline> where
    T: PartialEq,
    Inline: PartialEq, 

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

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

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

This method tests for !=.

impl<T, Inline> PartialOrd<RSmallBox<T, Inline>> for RSmallBox<T, Inline> where
    T: PartialOrd,
    Inline: PartialOrd, 

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

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

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

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

#[must_use] 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] fn gt(&self, other: &Rhs) -> bool

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

#[must_use] 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<T, Inline> Display for RSmallBox<T, Inline> where
    T: Display, 

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

Formats the value using the given formatter.

impl<T, Inline> Debug for RSmallBox<T, Inline> where
    T: Debug,
    Inline: Debug, 

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

Formats the value using the given formatter.

impl<T, Inline> Deref for RSmallBox<T, Inline>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T, Inline> DerefMut for RSmallBox<T, Inline>

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<T, Inline> Hash for RSmallBox<T, Inline> where
    T: Hash,
    Inline: 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<'de, T, Inline> Deserialize<'de> for RSmallBox<T, Inline> where
    Inline: InlineStorage,
    T: Deserialize<'de>, 

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

Deserialize this value from the given Serde deserializer.

impl<T, Inline> Serialize for RSmallBox<T, Inline> where
    T: Serialize, 

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

Serialize this value into the given Serde serializer.