Struct varlen::vbox::VBox

pub struct VBox<T: VarLen>(_);

Equivalent of Box<T> for variable-length types.

Examples

Heap-allocated Str:

use varlen::prelude::*;
let s = VBox::new(Str::copy("hello"));
assert_eq!("hello", &s[..]);

Implementations

impl<T: VarLen> VBox<T>

pub fn new(init: impl Initializer<T>) -> Self

Allocates memory which is right-sized for this particular instance.

Examples

use varlen::prelude::*;
let s = VBox::new(Str::copy("hello"));
assert_eq!("hello", &s[..]);

pub fn as_mut(&mut self) -> Pin<&mut T>

Mutable access to the field.

Examples

use varlen::prelude::*;
let mut s = VBox::new(Str::copy("Hello"));
assert_eq!("Hello", &s[..]);
s.as_mut().mut_slice().make_ascii_uppercase();
assert_eq!("HELLO", &s[..]);
s.as_mut().mut_slice().make_ascii_lowercase();
assert_eq!("hello", &s[..]);

pub unsafe fn into_raw(self) -> *mut T

Converts this to a raw pointer representation.

Safety

Because T is a variable-length type, there are additional safety obligations above and beyond the usual treatment of NonNull<T>. In particular, the caller responsible for ensuring that whenever a &T is produced, the header-specified layout matches the layout of the tail. This prohibits code patterns such as overwriting the header in a way that changes the layout.

Example

Safe roundtripping through a raw pointer:

use varlen::prelude::*;

let b = VBox::new(Str::copy("hello"));
let b = unsafe {
    let p = b.into_raw();
    VBox::from_raw(p)
};
assert_eq!(&b[..], "hello");

pub unsafe fn from_raw(raw: *mut T) -> Self

Constructs a VBox<T> from a NonNull<T> pointer.

Safety

The layout of T’s tail, which is the variable-sized part not included in std::mem::size_of::<T>(), must be consistent with the layout specified by T’s header. For example, this can have been produced by a crate::Initializer<T> call or similar, on a buffer sufficiently sized for the initializer’s layout.

Example

Safe roundtripping through a raw pointer:

use varlen::prelude::*;

let b = VBox::new(Str::copy("hello"));
let b = unsafe {
    let p = b.into_raw();
    VBox::from_raw(p)
};
assert_eq!("hello", &b[..]);

Trait Implementations

impl<T: for<'a> VClone<'a>> Clone for VBox<T>

Cloning a VBox<T> uses T::vclone().

Examples

use varlen::prelude::*;
let str: VBox<Str> = VBox::new(Str::copy("hello"));
let str2 = str.clone();
assert_eq!(&str2[..], "hello");

See also

It is often better to use T::vclone() or vcopy() instead, which will create a lazy initializer that directly clones or copies into the destination.

use varlen::prelude::*;
let str: VBox<Str> = VBox::new(Str::copy("hello"));
let seq: Seq<Str> = seq![
    // Best. Calls memcpy straight into the sequence storage
    str.vcopy(),   
    // Ok. Does field-by-field copy into the sequence storage.
    str.vclone(),  
    // Worst. Allocates a temporary VBox<Str>, copies field-by-field to there,
    // then coies field-by-field to the sequence storage, then deallocates the
    // temporary.
    str.clone(),   
];
let mut iter = seq.iter();
assert_eq!(&iter.next().unwrap()[..], "hello");
assert_eq!(&iter.next().unwrap()[..], "hello");
assert_eq!(&iter.next().unwrap()[..], "hello");
assert!(iter.next().is_none());

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: VarLen> Deref for VBox<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: VarLen> Drop for VBox<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: VarLen> Initializer<T> for VBox<T>

VBox<T> is an initializer for T.

Examples

Pushing a VBox<T> onto a crate::seq::Seq<T>:

use varlen::prelude::*;

let mut seq: Seq<Str> = Seq::new();
let b = VBox::new(Str::copy("hello"));
seq.push(b);

unsafe fn initialize(self, dst: NonNull<T>, layout: T::Layout)

Populates the destination pointer.

fn calculate_layout_cautious(&self) -> Option<T::Layout>

Calculates the layout of the object, returning None if any of the calculated sizes or offsets would overflow usize.