Vectors#

The compiler-checked Vec module contract is the sole authority for exact public declarations. This chapter defines the longer invariants of contiguous owning storage without repeating those signatures.

Vec<T> owns an initialized sequence and exposes readonly and readwrite observation through its coercions to [T]. Slice lookup, comparison, indexing, and ordering are implemented once by slice; Vec does not provide forwarding algorithms for that surface.

retain preserves relative order. Rejected elements are dropped exactly once, retained elements move at most once, and the initialized prefix advances only after each successful compaction step. truncate drops every removed suffix element exactly once. Ownership transfer operations do not copy move-only elements.

Insertion and removal preserve dense source order for move-only elements. Their implementation may use one transient uninitialized slot, but no fallible call or externally observable edge crosses that state. Recoverable insertion validates bounds and completes capacity growth before shifting; failed growth leaves pointer, length, capacity, contents, and storage origin unchanged.

Slice extension first reserves the complete additional element count and only then copies the source prefix. Recoverable capacity failure therefore leaves the vector unchanged. Once reservation succeeds, each copied element enters already-owned spare storage without another allocation.

The Vec<u8> specialization appends canonical unsigned and ZigZag-signed LEB128 values. It asks std/bytes for the complete width, reserves that many bytes, encodes into uncommitted storage, and publishes the new length only after the codec returns that exact width. Recoverable allocation failure leaves the vector unchanged; the specialization does not own a second encoding algorithm.

Zero-sized element types use logical length and capacity without allocating backing bytes. Reservation, insertion, removal, iteration, and destruction still perform their normal ownership effects once per logical element.

empty defers allocator selection until first growth. with_capacity, including a zero-capacity request, records the allocator selected by construction so later growth cannot silently move to a different allocation context. Recoverable constructors and mutations use TryAllocator; ordinary growth follows the aborting policy defined by Allocation and Failure.