Vector<T> structv0.1.0

pub struct Vector<T> {
    // private fields
}

Move-only: it owns its elements and storage, prohibits copying, and destroys both with ~Vector.

Type parameters

Constructors

Vector

pub func Vector(allocator: Allocator) -> Vector<T>

An empty vector that has not allocated anything. allocator is borrowed for the call and kept. Costs nothing: a vector that is never pushed to never allocates, which is what makes one cheap to have and to return. Cannot fail. Runs in constant time.

Returns: an empty collection that has taken no storage yet

Source

Associated functions

WithCapacity

pub func WithCapacity(
    allocator: Allocator,
    capacity: uint
) -> Vector<T> ! CollectionError

An empty vector with room for capacity elements already taken. allocator is borrowed for the call and kept. The vector starts empty — capacity is not length.

Returns: an empty vector with room for that many elements already taken

Source

FromSlice

pub func FromSlice(
    allocator: Allocator,
    items: T[..]
) -> Vector<T> ! CollectionError

A vector holding a copy of every element of items, in order. allocator is borrowed for the call and kept; items is borrowed and read. Copies its elements, so a move-only element type is built with Push instead.

Returns: a vector holding a copy of those elements

Source

Methods

Clone

pub func Clone(self: &Vector<T>) -> Vector<T> ! CollectionError

An independent vector holding a copy of every element of this one. self is borrowed and left alone. The copy takes exactly the room it needs rather than matching this one's capacity, since the spare holds nothing worth reproducing.

Returns: an independent copy

Source

Length

pub func Length(self: &Vector<T>) -> uint

How many elements the vector holds. self is borrowed.

Returns: how many elements it holds

Source

Capacity

pub func Capacity(self: &Vector<T>) -> uint

How many elements the storage could hold without growing. self is borrowed. Never below the length, and never reduced except by ShrinkToFit.

Returns: how many elements fit before the next growth

Source

IsEmpty

pub func IsEmpty(self: &Vector<T>) -> bool

Whether the vector holds no elements. self is borrowed. A vector with capacity and no elements is empty: capacity is not length.

Returns: whether it holds nothing

Source

Reserve

pub func Reserve(
    self: &var Vector<T>,
    additional: uint
) -> ! CollectionError

Makes room for additional more elements on top of those already present. self is borrowed mutably; the length does not change. Capacity only grows here; ShrinkToFit is what hands it back. A failure leaves the vector exactly as it was. Reports CapacityOverflow when the current length plus additional cannot be represented, which is what turns a Reserve(uint::Max) on a non-empty vector into a reported error rather than a silently tiny capacity.

Returns: nothing when the operation succeeded, or why it did not

Source

ShrinkToFit

pub func ShrinkToFit(self: &var Vector<T>) -> ! CollectionError

Releases the capacity past the length. self is borrowed mutably. A vector with nothing in it gives up its storage entirely and becomes as cheap as a new one. A failure leaves the vector usable at its current capacity, since failing to hand memory back is never a reason to stop working.

Returns: nothing when the operation succeeded, or why it did not

Source

Clear

pub func Clear(self: &var Vector<T>)

Destroys every element, keeping the storage. self is borrowed mutably. The vector is empty afterwards and can be refilled without allocating again. Runs in time proportional to the length.

Source

Truncate

pub func Truncate(self: &var Vector<T>, length: uint)

Destroys the elements past length, keeping the storage. self is borrowed mutably. A length at or past the current one changes nothing, so this never grows. This is the other half of the Rux/Algorithms seam: Unique, RemoveWhere, RemoveValue and Partition compact survivors toward the front and report the surviving length without resizing anything, and this is how a vector is told about it. Runs in time proportional to how many elements go.

Source

Push

pub func Push(
    self: &var Vector<T>,
    value: T
) -> ! CollectionError

Appends one element, growing the storage when it is full. self is borrowed mutably; value is read by value and moved into the vector. A failure leaves the vector exactly as it was and the value with the caller. Amortized constant time: the doubling is what spreads the cost of growing across the appends that caused it.

Returns: nothing when the operation succeeded, or why it did not

Source

PushSlice

pub func PushSlice(
    self: &var Vector<T>,
    items: T[..]
) -> ! CollectionError

Appends a copy of every element of items, in order. self is borrowed mutably; items is borrowed and read. Room for all of them is taken first, so this either appends every element or none of them.

Returns: nothing when the operation succeeded, or why it did not

Source

TryPop

pub func TryPop(self: &var Vector<T>, value: *var T) -> bool

Takes the last element out of the vector. self is borrowed mutably; value receives the element, which is moved out rather than copied, so this is how an element that owns something leaves a vector without being destroyed. Reports false and writes nothing when the vector is empty. The storage is kept, so a vector emptied this way costs nothing to refill.

Returns: whether there was an element to remove

Source

Get

pub func Get(self: &Vector<T>, index: uint) -> T?

The element at index, or none when there is no such index. self is borrowed; the element is returned by copy.

Returns: a copy of the element, or none when the index is out of range

Source

Reference

pub func Reference(self: &Vector<T>, index: uint) -> (*T)?

A pointer to the element at index, or none when there is no such index. self is borrowed; the pointer borrows the element where it sits. The pointer is valid until the vector grows, shrinks, or is destroyed.

Returns: the address of the element, or none when the index is out of range

Source

Set

pub func Set(
    self: &var Vector<T>,
    index: uint,
    value: T
) -> ! CollectionError

Replaces the element at index with value. self is borrowed mutably. Reports IndexOutOfRange and changes nothing when there is no such index. The old element is overwritten rather than destroyed. For an element that owns something, take it out first.

Returns: nothing when the element was written, or IndexOutOfRange

Source

AsSlice

pub func AsSlice(self: &Vector<T>) -> T[..]

The initialized elements as a borrowed read-only view. self is borrowed. Never the spare capacity, which holds nothing. The view is valid until the vector grows, shrinks, or is destroyed.

Returns: the elements, borrowed

Source

AsMutableSlice

pub func AsMutableSlice(self: &var Vector<T>) -> var T[..]

The initialized elements as a borrowed writable view. self is borrowed mutably. Never the spare capacity. The view is valid until the vector grows, shrinks, or is destroyed.

Returns: the elements, borrowed for writing

Source

Iterate

pub func Iterate(self: &Vector<T>) -> ValueIterator<T>

An iterator over the elements, by copy. self is borrowed and must outlive the iterator. This is the method a for loop finds. The vector must not grow or shrink while the iterator is alive.

Returns: a cursor yielding copies of the elements

Source

References

pub func References(self: &Vector<T>) -> ReferenceIterator<T>

An iterator over pointers to the elements. self is borrowed and must outlive the iterator.

Returns: a cursor yielding the elements' addresses

Source

MutableReferences

pub func MutableReferences(self: &var Vector<T>) -> MutableReferenceIterator<T>

An iterator over writable pointers to initialized elements, without copying them. The vector's storage must outlive the iterator and every yielded pointer. Do not grow, shrink, destroy, or move the vector while any of them is in use, and coordinate aliases that access the same elements.

Returns: a cursor yielding writable element addresses

Source

Insert

pub func Insert(
    self: &var Vector<T>,
    index: uint,
    value: T
) -> ! CollectionError

Inserts value at index, moving everything from there on one place along. self is borrowed mutably; value is moved in. An index equal to the length appends, which is what makes the rejection above it a boundary rather than a blanket refusal; anything past that reports IndexOutOfRange and changes nothing. Runs in time proportional to how many elements follow the insertion point.

Returns: nothing when the operation succeeded, or why it did not

Source

RemoveAt

pub func RemoveAt(self: &var Vector<T>, index: uint) -> T?

Takes the element at index out, moving everything after it one place back. self is borrowed mutably. The element is moved out and handed to the caller rather than destroyed, so an element that owns something leaves intact. Reports none and changes nothing when there is no such index. Order is preserved, which is what separates this from SwapRemoveAt. Runs in time proportional to how many elements follow the one removed.

Returns: the element removed, or none when the index is out of range

Source

SwapRemoveAt

pub func SwapRemoveAt(
    self: &var Vector<T>,
    index: uint
) -> T?

Takes the element at index out and moves the last one into its place. self is borrowed mutably. The element is moved out and handed to the caller. Reports none and changes nothing when there is no such index. Order is not preserved — whatever was last now sits where the removed element was — and that is the whole point: this is constant time where RemoveAt is linear, and for a sequence nobody is reading in order the difference is free.

Returns: the element removed, or none when the index is out of range

Source

First

pub func First(self: &Vector<T>) -> (*T)?

A pointer to the first element, or none for an empty vector. self is borrowed; the pointer borrows the element where it sits.

Returns: the address of the first element, or none when empty

Source

Last

pub func Last(self: &Vector<T>) -> (*T)?

A pointer to the last element, or none for an empty vector. self is borrowed; the pointer borrows the element where it sits.

Returns: the address of the last element, or none when empty

Source

Slice

pub func Slice(
    self: &Vector<T>,
    start: uint,
    count: uint
) -> T[..]

A borrowed read-only view of count elements starting at start. self is borrowed. A start at or past the length gives an empty view, and a count running past the end is clamped, so the result never covers storage the vector does not hold. The view is valid until the vector grows, shrinks, or is destroyed.

Returns: that run of elements, borrowed; empty when the range is out of bounds

Source

MutableSliceOf

pub func MutableSliceOf(
    self: &var Vector<T>,
    start: uint,
    count: uint
) -> var T[..]

A borrowed writable view of count elements starting at start. self is borrowed mutably. Clamped exactly as Slice is. The view is valid until the vector grows, shrinks, or is destroyed.

Returns: that run borrowed for writing; empty when the range is out of bounds

Source

IntoIterator

pub func IntoIterator(self: Vector<T>) -> VectorIntoIterator<T>

Takes the vector apart into an iterator over its elements. Consumes the vector: it is moved into the iterator, and the storage goes with it, so nothing is copied and nothing is reallocated. Each element comes out by value, which is how one that owns something leaves. Whatever is not taken is destroyed when the iterator's life ends. Cannot fail. Runs in constant time and allocates nothing.

Returns: a cursor that consumes the vector as it goes

Source

ToArray

pub func ToArray(self: &Vector<T>) -> Array<T> ! CollectionError

Copies the elements into a fixed-length array. self is borrowed and keeps its own storage, so both are released independently. Copies its elements, so this is for element types where copying means what it says — IntoArray is what moves them.

Returns: an array holding a copy of the elements

Source

IntoArray

pub func IntoArray(self: Vector<T>) -> Array<T> ! CollectionError

Hands the storage itself to a fixed-length array, copying nothing. Consumes the vector. The spare capacity is trimmed first, and the trim has to succeed: an array releases its block with the layout of its length, so a block still carrying spare capacity would be given back under a layout it was not taken with. A failed trim is a failed transfer, and the vector is gone either way — it was consumed by the call — so its elements are destroyed and an empty array comes back. That costs the elements, which is why it is reported rather than silent; a shrink refused by an allocator is close to impossible, since it asks for less than it already holds.

Returns: an array taking the vector's storage rather than copying it

Source

Destructor

func ~Vector(self: &var Vector<T>)

Destroys every element and releases the storage. Runs when the vector's life ends. The spare capacity past the length holds nothing and is not touched; the elements go first and the block second, since an element destroyed after its storage was released would be read from freed memory.

Source

Related

WriteVectorDebug<T>

pub func WriteVectorDebug<T: Debug>(
    writer: &var TextWriter,
    value: &Vector<T>,
    spec: FormatSpec
) -> ! FormatError

Writes a borrowed vector as [first, second, third]. An empty vector is [], and its capacity is not shown: the spare room past the length holds nothing, so it is not part of what the vector is. The vector and every element are borrowed, so this may be called on a vector of a move-only element type and the vector still holds all of them afterwards. spec is handed to each element unchanged and means whatever that element type makes of it. The brackets and commas are punctuation and are never padded. Reports whatever the writer or an element's implementation reported, stopping at the first refusal.

Source

Type parameters

Parameters

Returns: success when the whole rendering was accepted

MinimumVectorCapacity

pub const MinimumVectorCapacity: uint = 4;

The capacity a vector takes when it first has to allocate. Four elements rather than one: the first few appends are the common case, and three reallocations to reach four elements is three more than the work is worth.

Source

VectorIntoIterator<T>

pub struct VectorIntoIterator<T> {
    // private fields
}

An iterator that takes a vector apart, yielding each element by value. Move-only: it owns the storage the vector owned, prohibits copying, and destroys it with ~VectorIntoIterator. This is how a vector of elements that own something is emptied into somewhere else — each element is moved out rather than copied, and whatever is left when the iterator's life ends is destroyed with it.

Source

Type parameters

Implements Iterator

VectorIntoIterator<T> conforms to Iterator.

Next

pub func Next(self: &var VectorIntoIterator<T>) -> T?

The next element, moved out, or none once every element has been yielded. self is borrowed mutably and advanced. The element is moved rather than copied, so it is the caller's to keep or destroy; an exhausted iterator keeps reporting none. Cannot fail. Runs in constant time and allocates nothing.

Returns: the next element, or none at the end

Source

Destructor

~VectorIntoIterator

func ~VectorIntoIterator(self: &var VectorIntoIterator<T>)

Destroys whatever was not yielded and releases the storage. Runs when the iterator's life ends. Everything already yielded belongs to whoever took it and is not touched here, which is what makes stopping part-way through safe.

Source