Vector - multiple declarations

Struct Vector

Vectors are sequence containers representing arrays that can change in size.

struct Vector(_Type, ulong N = 0, _Allocator, bool _supportGC = shouldAddGCRange!_Type) ;

Just like arrays, vectors use contiguous storage locations for their elements, which means that their elements can also be accessed using offsets on regular pointers to its elements, and just as efficiently as in arrays. But unlike arrays, their size can change dynamically, with their storage being handled automatically by the container.

Instead, vector containers may allocate some extra storage to accommodate for possible growth, and thus the container may have an actual capacity greater than the storage strictly needed to contain its elements (i.e., its size). Libraries can implement different strategies for growth to balance between memory usage and reallocations, but in any case, reallocations should only happen at logarithmically growing intervals of size so that the insertion of individual elements at the end of the vector can be provided with amortized constant time complexity (see push_back).

Therefore, compared to arrays, vectors consume more memory in exchange for the ability to manage storage and grow dynamically in an efficient way.

Vector can have preallocated (stack) space for N elements.

Template parameters:

_Type = element type.

N Number of preallocated space for elements.

_Allocator Type of the allocator object used to define the storage allocation model. By default DefaultAllocator is used.

@safe:

Inserting element to Vector pointer is @safe if constructor of element is @safe (assumption is that constructor doesn't leak this pointer).

Vector assume that deallocation with custom allocator is @safe if allocation is @safe even if method deallcoate is @system.

Methods returning reference/pointer/slice (front(), back(), ptr(), elements(), opSlice(), ...) to vector elements are all @system because increasing capacity of vector can realocate all elements to new memory location and invalidate external references to old location.

scope and -dip1000:

Vector assume that managed object have global lifetime (scope can be ignored).

Functions for inserting elements to vector have non scope parameters (global lifetime).

Constructors

NameDescription
this (a) Constructs a empty Vector with allocator a.
this (nil) Constructs a empty Vector
this (rhs) Constructs a Vector object from other vector.
this (rhs, ) Forward constructor.
this (range) Constructs a Vector object from range of elements.

Properties

NameTypeDescription
allocator[get] CopyTypeQualifiers!(This,AllocatorType)Returns copy of allocator.
begin[get] inout(Vector.ElementType)*
capacity[get] size_tReturns the size of the storage space currently allocated for the Vector.
cbegin[get] const(Vector.ElementType)*
cend[get] const(Vector.ElementType)*
elements[get] inout(Vector.ElementType)[]Return slice of all elements (same as opSlice()).
empty[get] boolReturns whether the vector is empty (i.e. whether its length is 0).
end[get] inout(Vector.ElementType)*
full[get] boolReturns whether the vector is full (i.e. whether its length is equal to maximalCapacity).
length[get] size_tReturns the length of the vector, in terms of number of elements.
ptr[get] inout(Vector.ElementType)*Return pointer to the first element.
small[get] boolReturn true if vector is small (capacity == minimalCapacity)

Methods

NameDescription
append (range) Extends the Vector by appending additional elements at the end of vector.
at (pos) Returns reference to element at specified location pos.
atCopy (pos) Returns a copy to the element at position pos.
back () Returns a reference to the last element in the vector.
backCopy () Returns a copy of the first element in the vector.
build (args) Static function which return Vector construct from arguments args.
clear () Erases the contents of the Vector, which becomes an empty vector (with a length of 0 elements).
contains (elm) Same as operator in
downsize (n) Downsizes the vector to a length of n elements.
emplace (pos, args) Inserts a new element into the container directly before pos or ptr.
emplaceBack (args) Appends a new element to the end of the container. The element is constructed through emplace.
erase (pos) Removes specified element from the vector.
front () Returns a reference to the first element in the vector.
frontCopy () Returns a copy of the first element in the vector.
heapSwap (rhs) Swaps the contents of this and rhs only if both are heap allocated.
insert (pos, range) Inserts additional elements into the Vector right before the element indicated by pos or ptr.
moveBack () Move of the last element in the vector and return it.
moveFront () Move of the first element in the vector and return it.
opAssign (rhs) Assigns a new value rhs to the vector, replacing its current contents.
opBinaryRight (elm) Operator in
opCmp (rhs) Compares the contents of a vector with another vector or range.
opDollar () Returns the length of the vector, in terms of number of elements.
opEquals (nil) Compares the contents of a vector with another vector, range or null.
opIndex () Return slice of all elements (same as Vector.elements).
opIndex (pos) Returns reference to element at specified location pos.
opIndexAssign (val, index) Assign value val to element at position index.
opIndexOpAssign (val, index) Assign op value val to element at position index.
opSlice (begin, end) Returns a slice [begin .. end]. If the requested slice extends past the end of the vector, the returned slice is invalid.
owns (p) Returns true if memory referenced by p is owned by vector.
ownsElement (p) Returns true if element referenced by p is owned by vector. Similar to owns but check if p has right alignment.
pop (pos, def) Move the element at position pos out of vector, effectively reducing its length by 1.
popBack () Move the last element of the vector, effectively reducing its length by 1.
proxySwap (rhs) Swaps the contents of this and rhs.
release () Erases and deallocate the contents of the Vector, which becomes an empty vector (with a length of 0 elements).
replace (pos, len, val, count) Replaces the portion of the vector that begins at element pos and spans len characters (or the part of the vector in the slice slice) by new contents.
reserve (n) Requests that the vector capacity be adapted to a planned change in size to a length of up to n elements.
resize (n, args) Resizes the vector to a length of n elements.
shrinkToFit (reallocate) Requests the Vector to reduce its capacity to fit its length.
upsize (n, args) Upsize the vector to a length of n elements.

Aliases

NameDescription
AllocatorType Type of the allocator object used to define the storage allocation model. By default DefaultAllocator is used.
allowHeap Allow heap (false only if Allcoator is void)
ElementReferenceType Type of reference to elements.
ElementType Type of elements.
hasStatelessAllocator True if allocator doesn't have state.
maximalCapacity Maximal capacity of vector, in terms of number of elements.
minimalCapacity Minimal capacity of vector, in terms of number of elements.
opOpAssign Operator ~= and += is same as append
put Alias to append.
supportGC

Alias Vector

Alias to Vector with different order of template parameters

alias Vector(_Type, _Allocator, bool _supportGC = shouldAddGCRange!_Type) = Vector!(_Type,0,_Allocator,_supportGC);

Example

import std.range : only;
import std.algorithm : map, equal;

static struct Foo{
    int i;
    string str;
}

Vector!(Foo, 4) vec;

assert(vec.empty);
assert(vec.capacity == 4);
assert(typeof(vec).minimalCapacity == 4);

vec.append(Foo(1, "A"));
assert(vec.length == 1);

vec.append(only(Foo(2, "B"), Foo(3, "C")));
assert(vec.length == 3);

vec.emplaceBack(4, "D");
assert(vec.length == 4);
assert(vec.capacity == 4);

vec.insert(1, Foo(5, "E"));
assert(vec.length == 5);
assert(vec.capacity > 4);
assert(equal(vec[].map!(e => e.str), only("A", "E", "B", "C", "D")));

vec.erase(vec[1 .. $-1]);   //same as vec.erase(1, 3);
assert(vec == only(Foo(1, "A"), Foo(4, "D")));


vec = Vector!(Foo, 2).build(Foo(-1, "X"), Foo(-2, "Y"));
assert(equal(vec[].map!(e => e.str), only("X", "Y")));


vec.clear();
assert(vec.length == 0);
assert(vec.capacity > 4);

vec.release();
assert(vec.length == 0);
assert(vec.capacity == typeof(vec).minimalCapacity);