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

The Inline type parameter 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) );

Implementations

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=&generations as *const RSmallBox<_,_> as usize;
let heap_addr=RSmallBox::as_ptr(&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, 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> Clone for RSmallBox<T, Inline> where
    T: Clone,
    Inline: InlineStorage, 

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<T, Inline> Debug for RSmallBox<T, Inline> where
    T: Debug,
    Inline: Debug, 

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

Formats the value using the given formatter.

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

pub fn default() -> Self

Returns the "default value" for a type.

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

type Target = T

The resulting type after dereferencing.

pub fn deref(&self) -> &T

Dereferences the value.

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

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

Mutably dereferences the value.

impl<'de, T, Inline> Deserialize<'de> for RSmallBox<T, Inline> where
    Inline: InlineStorage,
    T: Deserialize<'de>, 

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

Deserialize this value from the given Serde deserializer.

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

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

Formats the value using the given formatter.

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

pub fn drop(&mut self)

Executes the destructor for this type.

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

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

Converts an RBox into an RSmallBox,currently this allocates.

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

Performs the conversion.

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

type Kind = PK_SmartPointer

The kind of the pointer.

pub const KIND: PointerKind

The kind of the pointer.

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

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

impl<T, Inline> Hash for RSmallBox<T, Inline> where
    T: Hash,
    Inline: 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<T, Inline> Into<RBox<T>> for RSmallBox<T, Inline> where
    Inline: InlineStorage, 

Converts a RSmallBox into an RBox,currently this allocates.

pub fn into(self) -> RBox<T>

Performs the conversion.

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

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

Restrict a value to a certain interval.

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

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

Gets a move pointer to the contents of this pointer.

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

Deallocates the pointer without dropping its owned contents.

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

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

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

pub fn eq(&self, other: &Self) -> 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<T, Inline> PartialOrd<RSmallBox<T, Inline>> for RSmallBox<T, Inline> where
    T: PartialOrd,
    Inline: PartialOrd, 

pub fn partial_cmp(&self, other: &Self) -> 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<T: Send, Inline> Send for RSmallBox<T, Inline>

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

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

Serialize this value into the given Serde serializer.

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

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.

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