#include <blockarray.h>
Detailed Description
template<typename T, Int BLOCK_SIZE_EXPONENT = BLOCKARRAY_DEFAULT_SIZE_EXPONENT, BLOCKARRAYFLAGS MEMFLAGS = BLOCKARRAYFLAGS::NONE, typename ALLOCATOR = DefaultAllocator>
class maxon::BlockArray< T, BLOCK_SIZE_EXPONENT, MEMFLAGS, ALLOCATOR >
Block array template. The array consists of multiple blocks containing 2^BLOCK_SIZE_EXPONENT elements. Therefore the memory address of the elements will not change if the array grows and no memory is copied. Nonetheless objects have to be copied/moved when you call Insert() or Erase(), but the amount of memory is limited to the size of a block which makes it much faster than a BaseArray for these purposes.
Please note that in a C++11 range based for loop you may not call a non-const method that modifies the range (e.g. Erase) - it does not work because the loop does not expect the range to change. Use the Iterable::EraseIterator in that case.
Performance characteristics: Random access to array elements is constant or at least amortized constant (when elements have been removed inbetween): O(1). Append or Pop (erase the last) an element is amortized constant: O(1) Insert or Erase an element can be amortized constant (unless block size and array size mismatch) : O(1)
- Note
- : Do not rely on the characteristics to pick the right type of collection. Always profile to check real life performance!
- Template Parameters
-
T Type of the array elements. BLOCK_SIZE_EXPONENT Size of an array block: 2^BLOCK_SIZE_EXPONENT. MEMFLAGS Use BLOCKARRAYFLAGS::NONE unless you know the object can be moved and/or copied. ALLOCATOR Class for memory allocation.
- Note
- Note that the array element class has special requirements regarding copy and move constructors .
- See also
- $ref arrays
Classes | |
| class | ArrayOfBlocks |
| struct | ForwardAllocator |
| class | IteratorTemplate |
Public Types | |
| using | AllocatorType = ALLOCATOR |
| using | Iterator = IteratorTemplate< false > |
| using | ConstIterator = IteratorTemplate< true > |
 Public Types inherited from Collection< BlockArray< T, BLOCK_SIZE_EXPONENT, MEMFLAGS, ALLOCATOR >, T, ALLOCATOR > | |
| using | Super = BaseCollection< BlockArray< T, BLOCK_SIZE_EXPONENT, MEMFLAGS, ALLOCATOR >, ALLOCATOR > |
| using | ValueType = T |
| Public Types inherited from BaseCollection< BlockArray< T, BLOCK_SIZE_EXPONENT, MEMFLAGS, ALLOCATOR >, ALLOCATOR > | |
| using | IsCollection = std::true_type |
Static Public Attributes | |
| static const Int | BLOCK_SIZE |
| Static Public Attributes inherited from ArrayBase0< BlockArray< T, BLOCK_SIZE_EXPONENT, MEMFLAGS, ALLOCATOR >, T, ALLOCATOR, DefaultCompare > | |
| static const COLLECTION_KIND | KIND |
Private Types | |
| using | ArrayBlock = BaseArray< T,(Int) MEMFLAGS &(Int) BLOCKARRAYFLAGS::GROW_SLOWLY ? BASEARRAY_DEFAULT_CHUNK_SIZE :(Int) 1<< BLOCK_SIZE_EXPONENT,(BASEARRAYFLAGS)((Int) MEMFLAGS &~(Int) BLOCKARRAYFLAGS::NOINSERTERASE), ForwardAllocator > |
| using | Super = ArrayBase< BlockArray< T, BLOCK_SIZE_EXPONENT, MEMFLAGS, ALLOCATOR >, T, ALLOCATOR, DefaultCompare > |
Private Member Functions | |
| MAXON_DISALLOW_COPY_AND_ASSIGN (BlockArray) | |
| Int | Insert (Int blockIdx, Int localIdx, const Block< const T > &values) |
| Int | Erase (Int blockIdx, Int localIdx, Int eraseCnt) |
| void | Move (ArrayBlock *dstBlock, Int dstLocalIdx, ArrayBlock *srcBlock, Int srcLocalIdx, Int moveCnt) |
| Int | ResolveToLocalIndex (Int &idx) const |
| ArrayBlock * | GetBlockAndIndex (Int &idx) |
| const ArrayBlock * | GetBlockAndIndex (Int &idx) const |
Private Attributes | |
| ArrayOfBlocks | _blocks |
Additional Inherited Members | |
| Static Public Member Functions inherited from Collection< BlockArray< T, BLOCK_SIZE_EXPONENT, MEMFLAGS, ALLOCATOR >, T, ALLOCATOR > | |
| static const T & | GetMapKey (const T &key) |
Member Typedef Documentation
◆ ArrayBlock
|
private |
◆ Super
|
private |
◆ AllocatorType
| using AllocatorType = ALLOCATOR |
◆ Iterator
| using Iterator = IteratorTemplate<false> |
◆ ConstIterator
| using ConstIterator = IteratorTemplate<true> |
Constructor & Destructor Documentation
◆ BlockArray() [1/3]
| BlockArray | ( | ) |
◆ BlockArray() [2/3]
|
explicit |
this constructor has to be used if an array should use a custom allocator with member variables
◆ ~BlockArray()
| ~BlockArray | ( | ) |
◆ BlockArray() [3/3]
| BlockArray | ( | BlockArray< T, BLOCK_SIZE_EXPONENT, MEMFLAGS, ALLOCATOR > && | src | ) |
move constructor
Member Function Documentation
◆ MAXON_DISALLOW_COPY_AND_ASSIGN()
|
private |
◆ MAXON_OPERATOR_MOVE_ASSIGNMENT()
| MAXON_OPERATOR_MOVE_ASSIGNMENT | ( | BlockArray< T, BLOCK_SIZE_EXPONENT, MEMFLAGS, ALLOCATOR > | ) |
move assignment operator
◆ Reset()
| void Reset | ( | void | ) |
Deletes all elements (calls destructors and frees memory).
◆ Flush()
| void Flush | ( | void | ) |
Deletes all elements (calls destructors and frees memory), but doesn't free the memory of the array which contains the blocks. The memory used by the blocks themselves is freed nevertheless.
◆ GetCount()
| Int GetCount | ( | void | ) | const |
Gets the number of array elements.
- Returns
- Number of array elements.
◆ GetCapacityCount()
| Int GetCapacityCount | ( | ) | const |
Gets the number of elements for which memory has been allocated (for a BlockArray this is equal to GetCount() plus the number of free elements in the last block)
- Returns
- Number of array elements for which memory has been allocated.
◆ operator[]() [1/2]
| const T& operator[] | ( | Int | idx | ) | const |
Array (subscript) operator for const objects.
- Parameters
-
[in] idx Element index (if it's out of bounds you will get an error in debug code only, otherwise it will crash).
- Returns
- Array element.
◆ operator[]() [2/2]
| T& operator[] | ( | Int | idx | ) |
Array (subscript) operator for non-const objects.
- Parameters
-
[in] idx Element index (if it's out of bounds you will get an error in debug code only, otherwise it will crash).
- Returns
- Array element.
◆ Append() [1/5]
| ResultRef<T> Append | ( | ) |
Adds a new element at the end of the array.
- Returns
- Element reference or OutOfMemoryError if the allocation failed.
◆ Append() [2/5]
| ResultRef<T> Append | ( | const T & | x | ) |
Adds a new element at the end of the array and initializes it with a copy of x.
- Parameters
-
[in] x Value to be copied.
- Returns
- Element reference or OutOfMemoryError if the allocation failed.
◆ Append() [3/5]
| ResultRef<T> Append | ( | T && | x | ) |
Adds a new element at the end of the array and moves the content of x to it.
- Parameters
-
[in] x Value to be moved.
- Returns
- Element reference or OutOfMemoryError if the allocation failed.
◆ Append() [4/5]
Appends new elements at the end of the array.
- Parameters
-
[in] values Block with values to be copied. If the block points to nullptr, only its count is used, and you have to call the constructor of the new elements manually.
- Returns
- Element pointer or OutOfMemoryError if the allocation failed.
◆ Append() [5/5]
| ResultPtr<T> Append | ( | const std::initializer_list< T > & | values | ) |
Appends new elements at the end of the array.
- Parameters
-
[in] values Initializer list with values to be copied.
- Returns
- Element pointer or OutOfMemoryError if the allocation failed.
◆ Insert() [1/11]
Inserts a new default element at index position.
- Parameters
-
[in] position Insert index (the array size will increase and the existing elements are moved).
- Returns
- Element reference or OutOfMemoryError if the allocation failed (or position is out of boundaries).
◆ Insert() [2/11]
| ResultMemT<Iterator> Insert | ( | const Iterator & | position | ) |
Inserts a new default element at iterator position.
- Parameters
-
[in] position Insert position.
- Returns
- Iterator for the new element or OutOfMemoryError if the allocation failed (or position is out of boundaries).
◆ Insert() [3/11]
Inserts a new element at index position and initializes it with a copy of x.
- Parameters
-
[in] position Insert index (the array size will increase and the existing elements are moved). [in] x Value to be copied.
- Returns
- Element reference or OutOfMemoryError if the allocation failed (or position is out of boundaries).
◆ Insert() [4/11]
| ResultMemT<Iterator> Insert | ( | const Iterator & | position, |
| const T & | x | ||
| ) |
Inserts a new element at iterator position and initializes it with a copy of x.
- Parameters
-
[in] position Insert position. [in] x Value to be copied.
- Returns
- Iterator for the new element or OutOfMemoryError if the allocation failed (or position is out of boundaries).
◆ Insert() [5/11]
Inserts a new element at index position and moves the content of x to it.
- Parameters
-
[in] position Insert index (the array size will increase and the existing elements are moved). [in] x Value to be moved.
- Returns
- Element reference or OutOfMemoryError if the allocation failed (or position is out of boundaries).
◆ Insert() [6/11]
| ResultMemT<Iterator> Insert | ( | const Iterator & | position, |
| T && | x | ||
| ) |
Inserts a new element at iterator position and moves the content of x to it.
- Parameters
-
[in] position Insert position. [in] x Value to be moved.
- Returns
- Iterator for the new element or OutOfMemoryError if the allocation failed (or position is out of boundaries).
◆ Insert() [7/11]
Inserts new elements at index position (all elements from position on are moved by the the count of values).
- Parameters
-
[in] position Insert index (the array size will increase and the existing elements are moved). [in] values Block with values to be copied. If the block points to nullptr, only its count is used, and you have to call the constructor of the new elements manually.
- Returns
- Element pointer or OutOfMemoryError if the allocation failed (or position is out of boundaries).
◆ Insert() [8/11]
Inserts new elements at index position (all elements from position on are moved by the the count of values).
- Parameters
-
[in] position Insert index (the array size will increase and the existing elements are moved). [in] values Initializer list with values to be copied.
- Returns
- Element pointer or OutOfMemoryError if the allocation failed (or position is out of boundaries).
◆ Insert() [9/11]
| ResultMemT<Iterator> Insert | ( | const Iterator & | position, |
| const Block< const T > & | values | ||
| ) |
Inserts new elements at iterator position (all elements from position on are moved by the the count of values).
- Parameters
-
[in] position Insert position. [in] values Block with values to be copied. If the block points to nullptr, only its count is used, and you have to call the constructor of the new elements manually.
- Returns
- Iterator for the new element or OutOfMemoryError if the allocation failed (or position is out of boundaries).
◆ Insert() [10/11]
| ResultMemT<Iterator> Insert | ( | Iterator | position, |
| const std::initializer_list< T > & | values | ||
| ) |
Inserts new elements at iterator position (all elements from position on are moved by the the count of values).
- Parameters
-
[in] position Insert position. [in] values Initializer list with values to be copied.
- Returns
- Iterator for the new element or OutOfMemoryError if the allocation failed (or position is out of boundaries).
◆ Erase() [1/3]
Erases (removes and deletes) elements.
- Parameters
-
[in] position Erase index (Erase() will fail if out of bounds and return nullptr). [in] eraseCnt Number of elements to be erased. If eraseCnt is invalid (higher than allowed or negative) a nullptr will be returned.
- Returns
- Pointer to the element that is now at position. If position equals the number of elements after Erase() a valid pointer is returned but you are not allowed to access it. OutOfMemoryError is only returned on failure (position was out of bounds).
◆ Erase() [2/3]
Erases (removes and deletes) elements.
- Parameters
-
[in] position Erase position. [in] eraseCnt Number of elements to be erased. If eraseCnt is invalid (higher than allowed or negative) an invalid iterator will be returned.
- Returns
- Iterator for the element that is now at position (its operator Bool() will return false if something failed).
- Note
- To erase an element within a ranged based for loop, you can't use this function directly as you don't have access to the iterator. But you can use
Iterable::EraseIteratoras in
◆ SwapErase() [1/2]
Erases elements within the array and moves elements from the end to the erased gap. This is generally faster than Erase because at most eraseCnt elements have to be moved, but it changes the order of elements.
- Parameters
-
[in] position Erase index (SwapErase() will fail if out of bounds and return nullptr). [in] eraseCnt Number of elements to be erased. If eraseCnt is invalid (higher than allowed or negative) false will be returned.
- Returns
- False if position was out of bounds.
◆ SwapErase() [2/2]
Erases elements within the array and moves elements from the end to the erased gap. This is generally faster than Erase() because at most eraseCnt elements have to be moved, but it changes the order of elements.
- Parameters
-
[in] position Erase position. [in] eraseCnt Number of elements to be erased. If eraseCnt is invalid (higher than allowed or negative) an invalid iterator will be returned.
- Returns
- Iterator for the element that is now at position (its operator Bool() will return false if something failed).
◆ GetBlock() [1/4]
Determines a contiguous block of array elements which contains the element at position. The returned blocks are guaranteed to form a partition of the array, i.e., no two blocks overlap, and they cover the whole array.
- Parameters
-
[in] position Element index. [out] block Block which contains the element at position.
- Returns
- Start index of the block. The requested element can be found within the block at
position- start index.
◆ GetBlock() [2/4]
Determines a contiguous block of array elements which contains the element at position. The returned blocks are guaranteed to form a partition of the array, i.e., no two blocks overlap, and they cover the whole array.
- Parameters
-
[in] position Element index. [out] block Block which contains the element at position.
- Returns
- Start index of the block. The requested element can be found within the block at
position- start index.
◆ GetBlock() [3/4]
| MAXON_ATTRIBUTE_FORCE_INLINE ConstIterator GetBlock | ( | const ConstIterator & | position, |
| Block< const T, STRIDED > & | block | ||
| ) | const |
Determines a contiguous block of array elements which contains the element at position. For a BaseArray, this yields the whole array as a block.
- Parameters
-
[in] position Element position. [out] block Block which contains the element at position.
- Returns
- Start iterator of the block. The requested element can be found within the block at index
position- start iterator.
◆ GetBlock() [4/4]
| MAXON_ATTRIBUTE_FORCE_INLINE Iterator GetBlock | ( | const Iterator & | position, |
| Block< T, STRIDED > & | block | ||
| ) |
Determines a contiguous block of array elements which contains the element at position. For a BaseArray, this yields the whole array as a block.
- Parameters
-
[in] position Element position. [out] block Block which contains the element at position.
- Returns
- Start iterator of the block. The requested element can be found within the block at index
position- start iterator.
◆ SetCapacityHint()
| ResultMem SetCapacityHint | ( | Int | requestedCapacity, |
| COLLECTION_RESIZE_FLAGS | resizeFlags = COLLECTION_RESIZE_FLAGS::ON_GROW_RESERVE_CAPACITY |
||
| ) |
Prepares the internal buffer(s) to hold at least the given number of elements with as few further memory allocations as possible.
- Note
- This is just a hint. It does not guarantee that the collection will be able to store the number of indicated elements.
- Parameters
-
[in] requestedCapacity The desired internal capacity. [in] resizeFlags If ON_GROW_FIT_TO_SIZE is set, the collection will use only as much memory as needed to hold the data.
- Returns
- False if allocation failed.
◆ Resize()
| ResultMem Resize | ( | Int | newCnt, |
| COLLECTION_RESIZE_FLAGS | resizeFlags = COLLECTION_RESIZE_FLAGS::DEFAULT |
||
| ) |
Resizes the array to contain newCnt elements. If newCnt is smaller than GetCount() all extra elements are being deleted. If it is greater the array is expanded and the default constructor is called for new elements.
- Parameters
-
[in] newCnt New array size. [in] resizeFlags See COLLECTION_RESIZE_FLAGS (flags other than ON_GROW_UNINITIALIZED/POD_UNINITIALIZED result in default behaviour).
- Returns
- False if allocation failed.
◆ Pop()
| Bool Pop | ( | T * | dst = nullptr | ) |
Deletes the last element.
- Parameters
-
[out] dst Nullptr or pointer to return value.
- Returns
- True if there was at least one element.
◆ GetIndex()
| Int GetIndex | ( | const T & | x | ) | const |
Gets the index of an element. The element must be part of the array, otherwise (e.g. if x is a copy of an array element) InvalidArrayIndex will be returned. This is slower than for a BaseArray because it has to iterate over the block.
- Returns
- Index of element or InvalidIndex (not element of this).
◆ CopyFromImpl()
| Result<void> CopyFromImpl | ( | BASEARRAY && | src, |
| COLLECTION_RESIZE_FLAGS | resizeFlags, | ||
| OverloadRank4 | |||
| ) |
◆ Swap()
Swaps elements a and b (equivalent to global Swap(array[a], array[b]).
- Parameters
-
[in] a Position of element to be swapped. [in] b Position of element to be swapped.
◆ GetMemorySize()
| Int GetMemorySize | ( | void | ) | const |
Calculates the memory usage for this array. The array element class must have a public member GetMemorySize that returns an element's size.
- Returns
- Memory size in bytes.
◆ Begin() [1/2]
| ConstIterator Begin | ( | ) | const |
◆ Begin() [2/2]
| Iterator Begin | ( | ) |
◆ End() [1/2]
| ConstIterator End | ( | ) | const |
◆ End() [2/2]
| Iterator End | ( | ) |
◆ Disconnect()
| BaseArray<ArrayBlock, BASEARRAY_DEFAULT_CHUNK_SIZE, BASEARRAYFLAGS::NONE, ForwardAllocator> Disconnect | ( | ) |
Disconnects the array's memory buffers and returns its content as an array of blocks. Afterwards the array is in the same state as directly after its construction.
- Returns
- Array of blocks.
- Note
- The memory needs to be freed with the allocator that the array is using.
◆ GetAllocator()
| ALLOCATOR& GetAllocator | ( | ) |
Returns the allocator as reference. Typically this is used by the arrays and other base classes when multiple of them are "stiched" together as one big object all shall use one main allocator.
- Returns
- Allocator reference.
◆ Insert() [11/11]
- Returns
- 0 on success or the number of elements not being inserted.
◆ Erase() [3/3]
◆ Move()
|
private |
◆ ResolveToLocalIndex()
Returns the block index and local index within that block for a global array index.
- Parameters
-
[in,out] idx On input the global index, on return the local index within the block (must be < GetCount()).
- Returns
- Block index.
◆ GetBlockAndIndex() [1/2]
|
private |
Returns the block and local index within that block for a global array index.
- Parameters
-
[in,out] idx On input the global index, on return the local index within the block (must be < GetCount()).
- Returns
- Block pointer.
◆ GetBlockAndIndex() [2/2]
|
private |
Member Data Documentation
◆ BLOCK_SIZE
|
static |
◆ _blocks
|
private |