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
| Name | Description |
|---|---|
T | the element type |
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.
| Name | Type | Description |
|---|---|---|
allocator | Allocator | where the storage comes from |
Returns: an empty collection that has taken no storage yet
Associated functions
WithCapacity
pub func WithCapacity(
allocator: Allocator,
capacity: uint
) -> Vector<T>
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. Terminates
the program when the storage cannot be had.
| Name | Type | Description |
|---|---|---|
allocator | Allocator | where the storage comes from |
capacity | uint | how many elements to make room for |
Returns: an empty vector with room for that many elements already taken
FromSlice
pub func FromSlice(
allocator: Allocator,
items: T[..]
) -> Vector<T>
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. Terminates the program when the storage cannot be had.
| Name | Type | Description |
|---|---|---|
allocator | Allocator | where the storage comes from |
items | T[..] | the elements to take |
Returns: a vector holding a copy of those elements
Methods
Clone
pub func Clone(&self) -> Vector<T>
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.
Elements are copied with =, so the element type must be plain data that Core::Copyable describes; an
owning element type is rejected while compiling, at the copy. Terminates the program when the storage cannot
be had; TryClone reports that instead.
Returns: an independent copy
TryClone
pub func TryClone(&self) -> Vector<T> throws AllocError
An independent vector holding a copy of every element of this one, or why the storage could not be had.
self is borrowed and left alone, whether or not the copy is made. Copies exactly as Clone does.
Returns: an independent copy, or throws the allocator's refusal
Length
pub func Length(&self) -> uint
How many elements the vector holds.
self is borrowed.
Returns: how many elements it holds
Capacity
pub func Capacity(&self) -> 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
IsEmpty
pub func IsEmpty(&self) -> 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
Reserve
pub func Reserve(&var self, additional: uint)
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. Terminates the program when the storage cannot be had, including when the current length plus
additional cannot be represented; TryReserve reports both instead.
| Name | Type | Description |
|---|---|---|
additional | uint | how many more elements to make room for |
TryReserve
pub func TryReserve(
&var self,
additional: uint
) throws AllocError
Makes room for additional more elements on top of those already present, or throws why it could not.
self is borrowed mutably; the length does not change. A failure leaves the vector exactly as it was.
Throws Unsupported when the current length plus additional cannot be represented, which is what turns a
TryReserve(uint::Max) on a non-empty vector into a reported error rather than a silently tiny capacity, and
otherwise whatever the allocator refused with.
| Name | Type | Description |
|---|---|---|
additional | uint | how many more elements to make room for |
Returns: nothing, or throws the allocator's refusal
ShrinkToFit
pub func ShrinkToFit(&var self)
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. Terminates the program when the allocator refuses to move the elements into the smaller block.
Clear
pub func Clear(&var self)
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.
Truncate
pub func Truncate(&var self, 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.
| Name | Type | Description |
|---|---|---|
length | uint | how many elements |
Push
pub func Push(&var self, value: T)
Appends one element, growing the storage when it is full.
self is borrowed mutably; value is read by value and moved into the vector. Terminates the program when
the storage cannot grow; TryPush reports that instead.
Amortized constant time: the doubling is what spreads the cost of growing across the appends that caused it.
| Name | Type | Description |
|---|---|---|
value | T | the value to act on |
TryPush
pub func TryPush(&var self, value: T) throws AllocError
Appends one element, growing the storage when it is full, or throws why the storage could not grow.
self is borrowed mutably; value is read by value and moved into the vector. A failure leaves the vector
exactly as it was, and value is then destroyed here.
Amortized constant time, as Push is.
| Name | Type | Description |
|---|---|---|
value | T | the value to act on |
Returns: nothing, or throws the allocator's refusal
PushSlice
pub func PushSlice(&var self, items: T[..])
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 terminates the program before appending any.
| Name | Type | Description |
|---|---|---|
items | T[..] | the elements to take |
Pop
pub func Pop(&var self) -> T?
Takes the last element out of the vector.
self is borrowed mutably; the element is moved out rather than copied, so this is how an element that owns
something leaves a vector without being destroyed. Reports none and changes nothing when the vector is empty.
The storage is kept, so a vector emptied this way costs nothing to refill.
Returns: the removed element, or none when the vector is empty
Get
pub func Get(&self, index: uint) -> T?
The element at index, or none when there is no such index.
self is borrowed; the element is returned by copy.
| Name | Type | Description |
|---|---|---|
index | uint | which one, counting from zero |
Returns: a copy of the element, or none when the index is out of range
At
pub func At(&self, index: uint) -> &T?
The element at index, borrowed where it sits, or none when there is no such index.
self stays borrowed while the reference is in use, so the vector cannot grow, shrink, or be destroyed under
it.
| Name | Type | Description |
|---|---|---|
index | uint | which one, counting from zero |
Returns: a reference to the element, or none when the index is out of range
AtMutable
pub func AtMutable(&var self, index: uint) -> &var T?
The element at index, borrowed to be written where it sits, or none when there is no such index.
self stays borrowed exclusively while the reference is in use.
| Name | Type | Description |
|---|---|---|
index | uint | which one, counting from zero |
Returns: a writable reference to the element, or none when the index is out of range
Set
pub func Set(
&var self,
index: uint,
value: T
) throws CollectionError
Replaces the element at index with value, destroying the element that was there.
self is borrowed mutably; value is moved in. The old element is destroyed once the new one is in place,
so an element that owns something is released rather than leaked; Replace hands it back instead. Reports
IndexOutOfRange and changes nothing when there is no such index, and value is then destroyed here.
| Name | Type | Description |
|---|---|---|
index | uint | which one, counting from zero |
value | T | the element to store |
Returns: nothing when the element was written, or IndexOutOfRange
Replace
pub func Replace(
&var self,
index: uint,
value: T
) -> T throws CollectionError
Replaces the element at index with value and hands back the element that was there.
self is borrowed mutably; value is moved in and the old element is moved out to the caller rather than
destroyed. Reports IndexOutOfRange and changes nothing when there is no such index, and value is then
destroyed here.
| Name | Type | Description |
|---|---|---|
index | uint | which one, counting from zero |
value | T | the element to store |
Returns: the element that was at index, or IndexOutOfRange
AsSlice
pub func AsSlice(&self) -> 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
AsMutableSlice
pub func AsMutableSlice(&var self) -> 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
Iterate
pub func Iterate(&self) -> 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
References
pub func References(&self) -> ReferenceIterator<T>
An iterator over pointers to the elements.
self is borrowed and must outlive the iterator.
Returns: a cursor yielding the elements' addresses
MutableReferences
pub func MutableReferences(&var self) -> 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
Insert
pub func Insert(
&var self,
index: uint,
value: T
) throws 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.
Terminates the program when the storage cannot grow.
Runs in time proportional to how many elements follow the insertion point.
| Name | Type | Description |
|---|---|---|
index | uint | which one, counting from zero |
value | T | the value to act on |
Returns: nothing when the element was inserted, or IndexOutOfRange
RemoveAt
pub func RemoveAt(&var self, 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.
| Name | Type | Description |
|---|---|---|
index | uint | which one, counting from zero |
Returns: the element removed, or none when the index is out of range
SwapRemoveAt
pub func SwapRemoveAt(&var self, 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.
| Name | Type | Description |
|---|---|---|
index | uint | which one, counting from zero |
Returns: the element removed, or none when the index is out of range
First
pub func First(&self) -> &T?
The first element, borrowed where it sits, or none for an empty vector.
self stays borrowed while the reference is in use.
Returns: a reference to the first element, or none when empty
Last
pub func Last(&self) -> &T?
The last element, borrowed where it sits, or none for an empty vector.
self stays borrowed while the reference is in use.
Returns: a reference to the last element, or none when empty
Slice
pub func Slice(&self, 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.
| Name | Type | Description |
|---|---|---|
start | uint | the first element, inclusive |
count | uint | how many elements |
Returns: that run of elements, borrowed; empty when the range is out of bounds
MutableSliceOf
pub func MutableSliceOf(
&var self,
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.
| Name | Type | Description |
|---|---|---|
start | uint | the first element, inclusive |
count | uint | how many elements |
Returns: that run borrowed for writing; empty when the range is out of bounds
IntoIterator
pub func IntoIterator(self) -> 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
ToArray
pub func ToArray(&self) -> Array<T>
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. Terminates the
program when the storage cannot be had.
Returns: an array holding a copy of the elements
IntoArray
pub func IntoArray(self) -> Array<T>
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 trim the allocator refuses terminates the program, as ShrinkToFit does; it is close
to impossible, since it asks for less than the block already holds.
Returns: an array taking the vector's storage rather than copying it
Destructor
func ~Vector(&var self)
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.
Related
WriteVectorDebug<T>
pub func WriteVectorDebug<T: Debug>(
writer: &var TextWriter,
value: &Vector<T>,
spec: FormatSpec
) throws 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.
Type parameters
| Name | Description |
|---|---|
T: Debug | the element type, which must know how to show itself |
Parameters
| Name | Type | Description |
|---|---|---|
writer | &var TextWriter | the destination |
value | &Vector<T> | the vector to show, borrowed for the call |
spec | FormatSpec | what to show each element under |
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.
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.
Type parameters
| Name | Description |
|---|---|
T | the element type |
Implements Iterator
VectorIntoIterator<T> conforms to Iterator.
Next
pub func Next(&var self) -> 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
Destructor
~VectorIntoIterator
func ~VectorIntoIterator(&var self)
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.