raw_buffer
import std::collections::raw_buffer; · source
Types
RawBuffer<T, A>
type struct RawBuffer<T, A = GlobalAlloc> where A: Allocator {
ptr: T*;
capacity: u64;
alloc: A;
static new() -> RawBuffer<T>;
static new_in(alloc: A) -> RawBuffer<T, A>;
ptr(&this) -> T*;
into_raw(mut this) -> T*;
capacity(&this) -> u64;
reserve(mut &this, used: u64, additional: u64, min_capacity: u64) -> Result<(), AllocError>;
reserve_exact(mut &this, used: u64, additional: u64) -> Result<(), AllocError>;
shrink_to(mut &this, target: u64) -> void;
resize(mut &this, new_capacity: u64) -> Result<(), AllocError>;
}The untyped backing store: a pointer, a capacity, and an allocator, with no notion of how many slots are in use. String keeps its own length beside one of these and passes it in as used when growing. reserve doubles past min_capacity; reserve_exact allocates exactly what is asked. into_raw hands the allocation to the caller and forgets it.
Array deliberately does not use it — RawBuffer puts capacity before length, and Array's layout has to match the [T] fat pointer.
Properties
| Property | Type |
|---|---|
ptr | T* |
capacity | u64 |
alloc | A |
Constructors
static new() -> RawBuffer<T>;
static new() -> RawBuffer<T>;Empty buffer backed by GlobalAlloc. No heap storage until the first reserve call.
static new_in(alloc: A) -> RawBuffer<T, A>;
static new_in(alloc: A) -> RawBuffer<T, A>;Empty buffer with a caller-supplied allocator. Ownership of alloc transfers to the buffer.
Methods
ptr(&this) -> T*;
into_raw(mut this) -> T*;
into_raw(mut this) -> T*;Consume the buffer and return its raw pointer, suppressing the deallocating Drop. The caller owns the storage afterward (it is leaked unless later reclaimed). Mirrors Box::into_raw.
capacity(&this) -> u64;
reserve(mut &this, used: u64, additional: u64, min_capacity: u64) -> Result<(), AllocError>;
reserve(mut &this, used: u64, additional: u64, min_capacity: u64) -> Result<(), AllocError>;Ensure at least additional more slots past used fit. Over-allocates along the doubling curve, seeded by min_capacity when the buffer is small (so empty-to-nonempty transitions don't start at a single slot).
reserve_exact(mut &this, used: u64, additional: u64) -> Result<(), AllocError>;
reserve_exact(mut &this, used: u64, additional: u64) -> Result<(), AllocError>;Allocate exactly enough for used + additional. No over- allocation. Useful when the caller already knows the final size (e.g., Array::with_capacity).
shrink_to(mut &this, target: u64) -> void;
shrink_to(mut &this, target: u64) -> void;Shrink capacity to target, which must be at least used. If shrinking fails, the buffer keeps its current capacity; losing capacity is fine, but losing data is not.
resize(mut &this, new_capacity: u64) -> Result<(), AllocError>;
resize(mut &this, new_capacity: u64) -> Result<(), AllocError>;Reallocate to new_capacity. Assumes new_capacity is the value the caller wants; bounds against used are the caller's problem. A method (not a free function) so the monomorphizer specializes it alongside the rest of RawBuffer<T, A>'s body, mirroring Array::resize_storage.
Trait implementations
implement<T, A> trait Drop for struct RawBuffer<T, A> where A: Allocator
Frees the allocation. Elements are never dropped — the buffer does not know which slots are live — so the owner must drop them first.
type struct Name { ... }
type enum Name { ... }
type trait Name { ... }
type union Name { ... }Begins a type declaration; the keyword that follows says which kind. On its own, type Name = Existing; declares an alias.
type struct Name {
field: Type;
method(&this) -> Ret { ... }
}A value type with named fields and optional methods. Structs live on the stack and are passed by value. Fields are public by default and may carry = default values; methods take their receiver as &this, mut &this, or this.
type struct RawBuffer<T, A = GlobalAlloc> where A: Allocator {
ptr: T*;
capacity: u64;
alloc: A;
}RawBuffer: the allocator-backed storage half of a growable container.
type parameter Ttype parameter Awhere A: Allocator
type struct GlobalAlloc {}Zero-sized handle to the process-wide allocator. Construct with GlobalAlloc::new(); all instances dispatch through the same underlying backend.
where T: Ord + Clone, U: HashConstrains generic parameters to types that implement the listed traits, which is what makes those traits' methods callable on T. Bounds on one parameter join with +; parameters separate with ,. A where on a single method narrows the type's parameter for that method only.
type trait Allocator {
allocate(mut &this, layout: Layout) -> Result<NonNull<u8>, AllocError>;
deallocate(mut &this, ptr: NonNull<u8>, layout: Layout) -> void;
reallocate(mut &this, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout) -> Result<NonNull<u8>, AllocError>;
}Allocator: the trait every heap strategy implements.
std::alloc::allocatorRawBuffer.ptr: T*type parameter TRawBuffer.capacity: u64RawBuffer.alloc: Astatic name(param: Type) -> Ret { ... }A method that belongs to the type rather than an instance, called as Type::name(..). For structs, static new(..) returning a struct literal is the idiomatic constructor.
static RawBuffer::new() -> RawBuffer<T>Empty buffer backed by GlobalAlloc. No heap storage until the first reserve call.
type struct RawBuffer<T, A = GlobalAlloc> where A: Allocator {
ptr: T*;
capacity: u64;
alloc: A;
}RawBuffer: the allocator-backed storage half of a growable container.
std::collections::raw_bufferstatic RawBuffer::new_in(alloc: A) -> RawBuffer<T, A>Empty buffer with a caller-supplied allocator. Ownership of alloc transfers to the buffer.
(parameter) alloc: A&this
mut &this
thisThe receiver of a method. Its first parameter declares how the method takes it: &this borrows read-only, mut &this borrows exclusively, and this / mut this move the value in and consume it. In the body, this.field reaches the members.
RawBuffer::into_raw(mut this) -> T*Consume the buffer and return its raw pointer, suppressing the deallocating Drop. The caller owns the storage afterward (it is leaked unless later reclaimed). Mirrors Box::into_raw.
mut thisA by-value receiver the body may also reassign. The receiver is moved into the method and consumed; the caller's value may not be used afterwards.
language referenceRawBuffer::reserve(mut &this, used: u64, additional: u64, min_capacity: u64) -> Result<(), AllocError>Ensure at least additional more slots past used fit. Over-allocates along the doubling curve, seeded by min_capacity when the buffer is small (so empty-to-nonempty transitions don't start at a single slot).
mut &this
mut &TypeAn exclusive, mutating borrow. As a receiver, mut &this lets the method modify the fields - and callers can see that from the signature alone. As a parameter type, mut &T lets the callee mutate through the reference while the caller keeps ownership.
(parameter) used: u64(parameter) additional: u64(parameter) min_capacity: u64primitive ()The unit type: a value that carries no information, and the empty tuple. Distinct from void, which is the absence of a value - Result<(), E> succeeds with nothing to return. 0 bytes.
type struct AllocError {
kind: AllocErrorKind;
layout: Layout;
}RawBuffer::reserve_exact(mut &this, used: u64, additional: u64) -> Result<(), AllocError>Allocate exactly enough for used + additional. No over- allocation. Useful when the caller already knows the final size (e.g., Array::with_capacity).
RawBuffer::shrink_to(mut &this, target: u64) -> voidShrink capacity to target, which must be at least used. If shrinking fails, the buffer keeps its current capacity; losing capacity is fine, but losing data is not.
(parameter) target: u64RawBuffer::resize(mut &this, new_capacity: u64) -> Result<(), AllocError>Reallocate to new_capacity. Assumes new_capacity is the value the caller wants; bounds against used are the caller's problem. A method (not a free function) so the monomorphizer specializes it alongside the rest of RawBuffer<T, A>'s body, mirroring Array::resize_storage.
(parameter) new_capacity: u64import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).
namespace std::collections::raw_buffer;RawBuffer: the allocator-backed storage half of a growable container.
module pagetype struct String<A = GlobalAlloc> {
buffer: RawBuffer<u8, A>;
length: u64;
}String: owned, heap-allocated, length-typed UTF-8.
std::collections::stringRawBuffer::reserve(mut &this, used: u64, additional: u64, min_capacity: u64) -> Result<(), AllocError>Ensure at least additional more slots past used fit. Over-allocates along the doubling curve, seeded by min_capacity when the buffer is small (so empty-to-nonempty transitions don't start at a single slot).
RawBuffer::reserve_exact(mut &this, used: u64, additional: u64) -> Result<(), AllocError>Allocate exactly enough for used + additional. No over- allocation. Useful when the caller already knows the final size (e.g., Array::with_capacity).
RawBuffer::into_raw(mut this) -> T*Consume the buffer and return its raw pointer, suppressing the deallocating Drop. The caller owns the storage afterward (it is leaked unless later reclaimed). Mirrors Box::into_raw.
type struct Array<T, A = GlobalAlloc> where A: Allocator {
ptr: T*;
length: i64;
capacity: i64;
alloc: A;
}Array<T, A>: growable, heap-backed, contiguous sequence.
std::collections::arrayRawBuffer.ptr: T*RawBuffer.capacity: u64RawBuffer.alloc: Astatic RawBuffer::new() -> RawBuffer<T>Empty buffer backed by GlobalAlloc. No heap storage until the first reserve call.
static RawBuffer::new_in(alloc: A) -> RawBuffer<T, A>Empty buffer with a caller-supplied allocator. Ownership of alloc transfers to the buffer.
type struct Box<T, A = GlobalAlloc> where A: Allocator {
ptr: T*;
alloc: A;
}Box<T, A>: single-owner heap allocation.
std::alloc::boxBox::into_raw(mut this) -> T*Give up ownership and return the raw pointer. The caller becomes responsible for freeing the memory (typically via Box::from_raw); dropping this box afterwards would double-free.
static Array::with_capacity(capacity: u64) -> Array<T, GlobalAlloc>Preallocate room for capacity elements. Panics on allocation failure; use try_with_capacity_in to recover.
RawBuffer::shrink_to(mut &this, target: u64) -> voidShrink capacity to target, which must be at least used. If shrinking fails, the buffer keeps its current capacity; losing capacity is fine, but losing data is not.
RawBuffer::resize(mut &this, new_capacity: u64) -> Result<(), AllocError>Reallocate to new_capacity. Assumes new_capacity is the value the caller wants; bounds against used are the caller's problem. A method (not a free function) so the monomorphizer specializes it alongside the rest of RawBuffer<T, A>'s body, mirroring Array::resize_storage.
Array::resize_storage(mut &this, new_capacity: i64) -> Result<(), AllocError>implement struct Name { ... }
implement trait Trait for Type { ... }
implement u64 { ... }Adds methods to a type outside its declaration. implement struct T (or enum, or a bare primitive) opens an inherent block; implement trait Tr for T supplies a trait's methods for one type. Resolution is at compile time - no dynamic dispatch.
type trait Name : Base {
method(&this, other: &This) -> Ret;
}Names a set of methods a type may implement. Inside the body This is the implementing type; methods may carry default bodies, and a trait may require a base trait (type trait Ord : Eq). Generic code asks for a trait with where T: Name.
implement trait Trait for Type { ... }Names the type a trait implementation is for. The block that follows supplies the bodies the trait requires.
language reference