Vector - multiple declarations
Struct Vector
Vector
s 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
Name | Description |
---|---|
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
Name | Type | Description |
---|---|---|
allocator [get]
|
CopyTypeQualifiers!(This,AllocatorType) | Returns copy of allocator. |
begin [get]
|
inout(Vector | |
capacity [get]
|
size_t | Returns the size of the storage space currently allocated for the Vector .
|
cbegin [get]
|
const(Vector | |
cend [get]
|
const(Vector | |
elements [get]
|
inout(Vector | Return slice of all elements (same as opSlice() ).
|
empty [get]
|
bool | Returns whether the vector is empty (i.e. whether its length is 0). |
end [get]
|
inout(Vector | |
full [get]
|
bool | Returns whether the vector is full (i.e. whether its length is equal to maximalCapacity). |
length [get]
|
size_t | Returns the length of the vector, in terms of number of elements. |
ptr [get]
|
inout(Vector | Return pointer to the first element. |
small [get]
|
bool | Return true if vector is small (capacity == minimalCapacity)
|
Methods
Name | Description |
---|---|
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 ).
|
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
Name | Description |
---|---|
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);