Struct abi_stable::sabi_types::rsmallbox::RSmallBox

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

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::{reexports::SelfOps, sabi_types::RSmallBox, std_types::RString, 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),
)))]
#[non_exhaustive]
pub enum SomeEnum<T> {
    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::Foo => true,
            SomeEnum::Bar => true,
            SomeEnum::Baz(rsbox) => RSmallBox::is_inline(rsbox),
            _ => true,
        }
    }

    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::{reexports::SelfOps, sabi_types::RSmallBox, 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, Inline> AsMutPtr for RSmallBox<T, Inline>

fn as_mut_ptr(&mut self) -> *mut T

Gets a mutable raw pointer to the value that this points to.

fn as_rmut(&mut self) -> RMut<'_, Self::PtrTarget>

Converts this pointer to an RRef.

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

fn as_ptr(&self) -> *const T

Gets a const raw pointer to the value that this points to.

fn as_rref(&self) -> RRef<'_, Self::PtrTarget>

Converts this pointer to an RRef.

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.

unsafe fn transmute_element_(self) -> Self::TransmutedPtr

Transmutes the element type of this pointer..

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> 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> Default for RSmallBox<T, Inline>

where T: Default, Inline: InlineStorage,

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.

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<'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> 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> Drop for RSmallBox<T, Inline>

fn drop(&mut self)

Executes the destructor for this type.

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

Converts to this type from the input type.

impl<T, Inline> From<RSmallBox<T, Inline>> for RBox<T>

where Inline: InlineStorage,

Converts a RSmallBox into an RBox,currently this allocates.

fn from(this: RSmallBox<T, Inline>) -> RBox<T>

Converts to this type from the input type.

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

type Kind = PK_SmartPointer

The kind of the pointer.

type PtrTarget = T

What this pointer points to.

const KIND: PointerKind = <Self::Kind as PointerKindVariant>::VALUE

The value-level version of the Kind associated type.

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

where T: __StableAbi, Inline: __GetStaticEquivalent_,

type StaticEquivalent = _static_RSmallBox<<T as GetStaticEquivalent_>::StaticEquivalent, <Inline as GetStaticEquivalent_>::StaticEquivalent>

The 'static equivalent of Self

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

Feeds a slice of this type into the given Hasher.

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

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<T, Inline> OwnedPointer for RSmallBox<T, Inline>

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

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>, func: F) -> R

where F: FnOnce(MovePtr<'_, Self::PtrTarget>) -> R,

Runs a callback with the contents of this pointer, and then deallocates it.

fn in_move_ptr<F, R>(self, func: F) -> R

where F: FnOnce(MovePtr<'_, Self::PtrTarget>) -> R,

Runs a callback with the contents of this pointer, and then deallocates it.

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

where T: PartialEq, Inline: PartialEq,

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

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

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.

const LAYOUT: &'static TypeLayout = _

The layout of the type provided by implementors.

const ABI_CONSTS: AbiConsts = _

const-equivalents of the associated types.

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

where T: Eq, Inline: Eq,

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

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