omni::vector

template<class T> class vector

Implementation of an ABI-safe vector container.

It is intended to be a drop-in replacement for std::vector.

Unlike std::vector<>, the Allocator is not a template parameter and will always use Carbonite allocation functions, such as carb::allocate(), carb::deallocate(), etc.

See std::vector for further documentation.

Note

ABI-safety is only as strong as the contained type T. If the contained type is not also ABI-safe, then guarantees are voided. Also note that iterator, const_iterator, reverse_iterator and const_reverse_iterator are not guaranteed to be ABI-safe.

Note

If exceptions are disabled, CARB_FATAL_UNLESS will be triggered instead of throwing.

Note

If exceptions are enabled, most functions provide a strong exception guarantee. If any exception is thrown, the function it is thrown from has no effect. See documentation for individual functions for specifics.

Public Types

using value_type = T : Alias for the vector’s contained type.

using allocator_type = typename ::carb::Allocator<T>: A reference to the allocator used by this class.

using size_type = std::size_t: Alias for size_t.

using difference_type = std::ptrdiff_t: Alias for ptrdiff_t.

using reference = value_type&: Reference to contained type.

using const_reference = const value_type&: Const reference to contained type.

using pointer = typename std::allocator_traits<allocator_type>::pointer: Pointer to contained type.

using const_pointer = typename std::allocator_traits<allocator_type>::const_pointer: Const pointer to contained type.

using iterator = detail::PointerIterator<pointer, vector>: Iterator type. Not guaranteed to be ABI-safe.

using const_iterator = detail::PointerIterator<const_pointer, vector>: Const iterator type. Not guaranteed to be ABI-safe.

using reverse_iterator = std::reverse_iterator<iterator>: Reverse iterator type. Not guaranteed to be ABI-safe.

using const_reverse_iterator = std::reverse_iterator<const_iterator>: Const reverse iterator type. Not guaranteed to be ABI-safe.

Public Functions

constexpr vector() noexcept: Default constructor.

inline explicit constexpr vector(const allocator_type&) noexcept: Allocator copy constructor.

constexpr vector(size_type count, const T &value, const allocator_type &alloc = allocator_type())

Constructs a vector with count copies elements of value value.

Throws

std::length_error – if count > max_size().

Parameters

count – The number of elements to construct.
value – The value to copy for all constructed elements.
alloc – Optional allocator to copy.

constexpr vector(size_type count, const allocator_type &alloc = allocator_type())

Constructs a vector with count default-inserted instances of T. No copies of values are made.

Throws

std::length_error – if count > max_size().

Parameters

count – The number of elements to default-insert.
alloc – Optional allocator to copy.

template<class InputIt> inline constexpr vector(InputIt first, InputIt last, const allocator_type& = allocator_type())

Constructs the container with the contents [first, last).

Note

This overload participates in overload resolution only if InputIt satisfies LegacyInputIterator to avoid ambiguity with other constructors.

Parameters

first – Iterator of the first element to copy into the vector.
last – Iterator of the last element (first element not copied into the vector).
alloc – Optional allocator to copy.

constexpr vector(const vector &other)

Copy constructor.

Parameters: other – Vector to copy elements from.

inline constexpr vector(const vector &other, const allocator_type&)

Copy constructor with allocator.

Parameters

other – Vector to copy elements from.
alloc – Allocator to copy.

constexpr vector(vector &&other) noexcept

Move constructor.

Post-condition: other is guaranteed to be empty().

Parameters: other – Vector to move elements from.

inline constexpr vector(vector &&other, const allocator_type&) noexcept

Move constructor with allocator.

Post-condition: other is guaranteed to be empty().

Parameters

other – Vector to move elements from.
alloc – Allocator to copy.

constexpr vector(std::initializer_list<T> init, const allocator_type &alloc = allocator_type())

Constructs the container with the contents of the given initializer list.

Parameters

init – std::initializer_list that is copied into the newly constructed vector.
alloc – Optional allocator to copy.

constexpr ~vector(): Destructor.

constexpr vector &operator=(const vector &other)

Copy-assign operator. Replaces the contents of *this with a copy of the contents of other.

Parameters: other – Another container to use as a data source.
Returns: *this

constexpr vector &operator=(vector &&other) noexcept

Move-assign operator. Replaces the contents of *this with those of other using move semantics. Other is in a valid but unspecified state afterwards.

Parameters: other – Another container to use as a data source.
Returns: *this

constexpr vector &operator=(std::initializer_list<T> init)

Replaces the contents with those in a given initializer_list.

Parameters: init – std::initializer_list to use as a data source.
Returns: *this

constexpr void assign(size_type count, const T &value)

Assigns values to the container.

Replaces the contents of the container with count copies of value. All iterators, pointers and references to the elements of the container are invalidated. The past-the-end iterator is also invalidated.

Throws

std::length_error – if count > max_size().

Parameters

count – The new size of the container.
value – The value to initialize elements of the container with.

template<class InputIt> inline constexpr void assign(InputIt first, InputIt last)

Assigns values to the container.

Replaces the contents of the container with copies of those in the range [first, last). The behavior is undefined if either argument is an iterator into *this. This overload participates in overload resolution only if InputIt satisfies LegacyInputIterator. All iterators, pointers and references to the elements of the container are invalidated. The past-the-end iterator is also invalidated.

Parameters

first – The beginning of the range to copy elements from.
last – The end of the range to copy elements from (note that this element is not copied).

constexpr void assign(std::initializer_list<T> init)

Assigns values to the container.

Replaces the contents of the container with the elements from the initializer list init. All iterators, pointers and references to the elements of the container are invalidated. The past-the-end iterator is also invalidated.

Parameters: init – Initializer list to copy the values from.

constexpr allocator_type get_allocator() const noexcept

Returns the allocator associated with the container.

Returns: The allocator associated with the container.

constexpr reference at(size_type pos)

Access specified element with bounds checking.

Returns a reference to the element at specified location pos, with bounds checking. If pos is not within the range of the container, an exception of type std::out_of_range is thrown.

Throws: std::out_of_range – if pos >= size().
Parameters: pos – Position of the element to return.
Returns: Reference to the requested element.

constexpr const_reference at(size_type pos) const

Access specified element with bounds checking.

Returns a reference to the element at specified location pos, with bounds checking. If pos is not within the range of the container, an exception of type std::out_of_range is thrown.

Throws: std::out_of_range – if pos >= size().
Parameters: pos – Position of the element to return.
Returns: Reference to the requested element.

constexpr reference operator[](size_type pos)

Access specified element.

Returns a reference to the element at specified location pos. No bounds checking is performed. Unlike std::map::operator[] this operator never inserts a new element into the container. Accessing a non-existent element through this operator is undefined behavior.

Parameters: pos – Position of the element to return.
Returns: Reference to the requested element.

constexpr const_reference operator[](size_type pos) const

Access specified element.

Returns a reference to the element at specified location pos. No bounds checking is performed. Unlike std::map::operator[] this operator never inserts a new element into the container. Accessing a non-existent element through this operator is undefined behavior.

Parameters: pos – Position of the element to return.
Returns: Reference to the requested element.

constexpr reference front()

Access the first element.

Calling front() on an empty container causes undefined behavior.

Returns: Reference to the first element.

constexpr const_reference front() const

Access the first element.

Calling front() on an empty container causes undefined behavior.

Returns: Reference to the first element.

constexpr reference back()

Access the last element.

Calling back() on an empty container causes undefined behavior.

constexpr const_reference back() const

Access the last element.

Calling back() on an empty container causes undefined behavior.

constexpr pointer data() noexcept

Direct access to the underlying data.

Returns pointer to the underlying array serving as element storage. The pointer is such that range [data(), data() + size()) is always a valid range, even if the container is empty (data() is not dereferenceable in that case).

Returns: pointer to the underlying element storage. For non-empty containers, the returned pointer compares equal to the address of the first element.

constexpr const_pointer data() const noexcept

Direct access to the underlying data.

Returns pointer to the underlying array serving as element storage. The pointer is such that range [data(), data() + size()) is always a valid range, even if the container is empty (data() is not dereferenceable in that case).

Returns: pointer to the underlying element storage. For non-empty containers, the returned pointer compares equal to the address of the first element.

inline constexpr iterator begin() noexcept

Returns an iterator to the beginning.

Returns: an iterator to the first element.

inline constexpr const_iterator begin() const noexcept

Returns an iterator to the beginning.

Returns: an iterator to the first element.

inline constexpr const_iterator cbegin() const noexcept

Returns an iterator to the beginning.

Returns: an iterator to the first element.

inline constexpr iterator end() noexcept

Returns an iterator to the end.

Returns: an interator to the element following the last element.

inline constexpr const_iterator end() const noexcept

Returns an iterator to the end.

Returns: an interator to the element following the last element.

inline constexpr const_iterator cend() const noexcept

Returns an iterator to the end.

Returns: an interator to the element following the last element.

inline constexpr reverse_iterator rbegin() noexcept

Returns a reverse iterator to the beginning.

Returns: a reverse iterator to the first element.

inline constexpr const_reverse_iterator rbegin() const noexcept

Returns a reverse iterator to the beginning.

Returns: a reverse iterator to the first element.

inline constexpr const_reverse_iterator crbegin() const noexcept

Returns a reverse iterator to the beginning.

Returns: a reverse iterator to the first element.

inline constexpr reverse_iterator rend() noexcept

Returns a reverse iterator to the end.

Returns: a reverse iterator to the element following the last element.

inline constexpr const_reverse_iterator rend() const noexcept

Returns a reverse iterator to the end.

Returns: a reverse iterator to the element following the last element.

inline constexpr const_reverse_iterator crend() const noexcept

Returns a reverse iterator to the end.

Returns: a reverse iterator to the element following the last element.

constexpr bool empty() const noexcept

Checks whether the container is empty.

Returns: true if the container is empty; false otherwise.

constexpr size_type size() const noexcept

Returns the number of elements.

Returns: The number of elements in the container.

constexpr size_type max_size() const noexcept

Returns the maximum possible number of elements.

Returns the maximum number of elements the container is able to hold due to system or library implementation limitations, i.e. std::distance(begin(), end()) for the largest container.

Returns: The maximum possible number of elements.

constexpr void reserve(size_type new_cap)

Reserves storage.

Increases the capacity of the vector (the total number of elements that the vector can hold without requiring reallocation) to a value that’s greater or equal to new_cap. If new_cap is greater than the current capacity(), new storage is allocated, otherwise this function does nothing.

reserve() does not change the size() of the vector.

If new_cap is greater than capacity(), all iterators (including the end() iterator), and all pointers and references to the elements are invalidated. Otherwise no iterators, pointers or references are invalidated.

After a call to reserve() insertions will not trigger reallocation unless the insertion would make the size of the vector greater than the value of capacity().

If an exception is thrown, this function has no effect (strong exception guarantee). If T’s move constructor is not noexcept and T is not CopyInsertable into *this, vector will use the throwing move constructor. If it throws, the guarantee is waived and the effects are unspecified.

Note

This function requires that T meet the requirements of MoveInsertable into *this.

Throws: std::length_error – if new_cap > max_size().
Parameters: new_cap – New capacity of the vector, in number of elements.

constexpr size_type capacity() const noexcept

Returns the number of elements that can be held in currently allocated storage.

Returns: Capacity of the currently allocated storage.

constexpr void shrink_to_fit()

Reduces memory usage by freeing unused memory.

Requests the removal of unused capacity. It is a non-binding request to reduce capacity() to size(). For std::vector<>, it depends on the implementation whether the request is fulfilled. This implementation will always reallocate if size() != capacity(). If reallocation occurs, all iterators (including the end() iterator) and all pointers and references to elements are invalidated. If no reallocation occurs, no iterators, pointers or references are invalidated.

Note

T must meet te requirements of MoveInsertable into *this.

Note

If an exception is thrown other than by the move constructor of a non-*CopyInsertable* T, there are no effects.

constexpr void clear() noexcept

Clears the contents.

Erases all elements from the container. After this call size() returns zero. Invalidates any references, pointers or iterators referring to contained elements. Any past-the-end iterators are also invalidated.

Leaves the capacity() of the vector unchanged.

constexpr iterator insert(const_iterator pos, const T &value)

Inserts elements.

Inserts value before pos. If after the operation the new size() is greater than old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all pointers and references to elements are invalidated. Otherwise, only the iterators, pointers and references before the insertion point remain valid.

This function has no effect (strong exception guarantee) if exceptions are thrown other than by the copy or move constructors of T, or the copy-assign or move-assign operators of T. If an exception is thrown when inserting a single element at the end, and T is CopyInsertable or std::is_nothrow_move_constructible_v<T> is true, this function has no effect (strong exception guarantee). Otherwise, if an exception is thrown by the move constructor of a non-*CopyInsertable* T, the effects are unspecified.

Note

T must meet the requirements of CopyAssignable and CopyInsertable.

Throws

std::length_error – if the new size() would exceed max_size().

Parameters

pos – Iterator before which the content will be inserted (may be the end() iterator).
value – Element value to insert.

Returns

Iterator pointing to the inserted value.

constexpr iterator insert(const_iterator pos, T &&value)

Inserts elements.

Inserts value before pos. If after the operation the new size() is greater than old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all pointers and references to elements are invalidated. Otherwise, only the iterators, pointers and references before the insertion point remain valid.

This function has no effect (strong exception guarantee) if exceptions are thrown other than by the copy or move constructors of T, or the copy-assign or move-assign operators of T. If an exception is thrown when inserting a single element at the end, and T is CopyInsertable or std::is_nothrow_move_constructible_v<T> is true, this function has no effect (strong exception guarantee). Otherwise, if an exception is thrown by the move constructor of a non-*CopyInsertable* T, the effects are unspecified.

Note

T must meet the requirements of MoveAssignable and MoveInsertable.

Throws

std::length_error – if the new size() would exceed max_size().

Parameters

pos – Iterator before which the content will be inserted (may be the end() iterator).
value – Element value to insert.

Returns

Iterator pointing to the inserted value.

constexpr iterator insert(const_iterator pos, size_type count, const T &value)

Inserts elements.

Inserts count copies of value before pos. If after the operation the new size() is greater than old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all pointers and references to elements are invalidated. Otherwise, only the iterators, pointers and references before the insertion point remain valid.

This function has no effect (strong exception guarantee) if exceptions are thrown other than by the copy or move constructors of T, or the copy-assign or move-assign operators of T. If an exception is thrown when inserting a single element at the end, and T is CopyInsertable or std::is_nothrow_move_constructible_v<T> is true, this function has no effect (strong exception guarantee). Otherwise, if an exception is thrown by the move constructor of a non-*CopyInsertable* T, the effects are unspecified.

Note

T must meet the requirements of CopyAssignable and CopyInsertable.

Throws

std::length_error – if the new size() would exceed max_size().

Parameters

pos – Iterator before which the content will be inserted (may be the end() iterator).
count – Number of elements to insert.
value – Element value to insert.

Returns

Iterator pointing to the first element inserted, or pos if count is zero.

template<class Iter> inline constexpr iterator insert(const_iterator pos, Iter first, Iter last)

Inserts elements.

Inserts elements from range [first, last) before pos. If after the operation the new size() is greater than old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all pointers and references to elements are invalidated. Otherwise, only the iterators, pointers and references before the insertion point remain valid.

This function has no effect (strong exception guarantee) if exceptions are thrown other than by the copy or move constructors of T, the copy-assign or move-assign operators of T, or any Iter operation. If an exception is thrown when inserting a single element at the end, and T is CopyInsertable or std::is_nothrow_move_constructible_v<T> is true, this function has no effect (strong exception guarantee). Otherwise, if an exception is thrown by the move constructor of a non-*CopyInsertable* T, the effects are unspecified.

Note

T must meet the requirements of EmplaceConstructible, Swappable, MoveAssignable, MoveConstructible and MoveInsertable.

Note

This overload participates in overload resolution only if Iter qualifies as LegacyInputIterator to avoid ambiguity with other overloads.

Throws

std::length_error – if the new size() would exceed max_size().

Parameters

pos – Iterator before which the content will be inserted (may be the end() iterator).
first – First iterator in a range of elements to insert, cannot be iterators into *this.
last – Last iterator in a range of elements to insert, cannot be iterators into *this (this iterator terminates the range and is not inserted).

Returns

Iterator pointing to the first element inserted, or pos if first is equal to last.

constexpr iterator insert(const_iterator pos, std::initializer_list<T> init)

Inserts elements.

Inserts elements from initializer list init before pos. If after the operation the new size() is greater than old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all pointers and references to elements are invalidated. Otherwise, only the iterators, pointers and references before the insertion point remain valid.

This function has no effect (strong exception guarantee) if exceptions are thrown other than by the copy or move constructors of T, or the copy-assign or move-assign operators of T. If an exception is thrown when inserting a single element at the end, and T is CopyInsertable or std::is_nothrow_move_constructible_v<T> is true, this function has no effect (strong exception guarantee). Otherwise, if an exception is thrown by the move constructor of a non-*CopyInsertable* T, the effects are unspecified.

Note

T must meet the requirements of EmplaceConstructible, Swappable, MoveAssignable, MoveConstructible and MoveInsertable.

Throws

std::length_error – if the new size() would exceed max_size().

Parameters

pos – Iterator before which the content will be inserted (may be the end() iterator).
init – Initializer list to insert the values from.

Returns

Iterator pointing to the first element inserted, or pos if init is empty.

template<class ...Args> constexpr iterator emplace(const_iterator pos, Args&&... args)

Constructs element in place.

Inserts a new element into the container directly before pos.

The element is constructed using placement new. If the required location has been occupied by an existing element, the inserted element is constructed at another location first and the move-assigned into the required position.

The arguments args... are forwarded to the constructed with std::forward<Args>(args).... args... may directly or indirectly refer to a value in the container.

If after the operation the new size() is greater than old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all pointers and references to the elements are invalidated. Otherwise, only the iterators, pointers and references before the insertion point remain valid.

Note

T must meet the requirements of MoveAssignable, MoveInsertable, and EmplaceConstructible.

Note

If an exception is thrown other than by the copy constructor, move constructor, copy-assign operator, or move-assign operator of value_type, or if an exception is thrown while emplace() is used to insert a single element at the end and the value_type is either CopyInsertable or nothrow-move-constructible, there are no effects (strong exception guarantee). Otherwise, the effects are unspecified.

Throws

std::length_error – if the new size() would exceed max_size().

Parameters

pos – Iterator before which the new element will be constructed.
args – Arguments to forward to the constructor of the element.

Returns

Iterator pointing to the emplaced element.

constexpr iterator erase(const_iterator pos)

Erases the specified elements.

Removes the element at pos. Iterators (including the end() iterator) and pointers and references to the elements at or after the point of the erasure are invalidated. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which is valid but not dereferenceable) cannot be used as a value for pos.

Note

T must meet the requirements of MoveAssignable.

Note

Does not throw unless an exception is thrown by the assignment operator of T.

Parameters: pos – Iterator to the element to remove.
Returns: Iterator following the element removed. If pos refers to the last element, then the end() iterator is returned.

constexpr iterator erase(const_iterator first, const_iterator last)

Erases the specified elements.

Removes the elements in the range [first, last). Iterators (including the end() iterator) and pointers and references to the elements at or after the point of the erasure are invalidated. The iterator first does not need to be dereferenceable if first == last; erasing an empty range is a no-op.

Note

T must meet the requirements of MoveAssignable.

Note

Does not throw unless an exception is thrown by the assignment operator of T.

Parameters

first – First iterator in the range of elements to remove.
last – Last iterator in the range of elements to remove. This iterator is not actually removed and can be end().

Returns

Iterator following the element removed. If last == end() prior to removal, then the updated end() iterator is returned. If first == last (empty range) then last is returned.

constexpr void push_back(const T &value)

Adds an element to the end.

Appends the given element value to the end of the container. The new element is initialized as a copy of value. If after the operation the new size() is greater than old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all pointers and references to the elements are invalidated. Otherwise only the end() iterator is invalidated.

Note

T must meet the requirements of CopyInsertable.

Note

If an exception is thrown (which can be due to allocation or element copy construction/copy assignment), this function has no effect (strong exception guarantee).

Throws: std::length_error – if the new size() would exceed max_size().
Parameters: value – The value of the element to append.

constexpr void push_back(T &&value)

Adds an element to the end.

Appends the given element value to the end of the container. value is moved into the new element. If after the operation the new size() is greater than old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all pointers and references to the elements are invalidated. Otherwise only the end() iterator is invalidated.

Note

T must meet the requirements of MoveInsertable.

Note

If an exception is thrown (which can be due to allocation or element move construction/move assignment), this function has no effect (strong exception guarantee). If T’s move constructor is not noexcept and T is not CopyInsertable into *this, vector will use the throwing move constructor. If it throws, the guarantee is waived and the effects are unspecified.

Throws: std::length_error – if the new size() would exceed max_size().
Parameters: value – The value of the element to append.

template<class ...Args> constexpr value_type &emplace_back(Args&&... args)

Constructs an element in-place at the end.

Appends a new element to the end of the container using placement new to construct in-place. The arguments are forwarded to the constructor. If after the operation the new size() is greater than the old capacity() a reallocation takes place, in which case all iterators (including the end() iterator) and all references to the elements are invalidated. Otherwise only the end() iterator is invalidated.

Throws: std::length_error – if the new size() would exceed max_size().
Parameters: args – Arguments to forward to the constructor of the element.
Returns: A reference to the inserted element.

constexpr void pop_back()

Removes the last element.

Removes the last element of the container. Calling pop_back() on an empty container results in undefined behavior. The end() iterator and iterators, pointers and references to the last element are invalidated.

constexpr void resize(size_type count)

Changes the number of elements stored.

Resizes the container to count elements, does nothing if count == size(). If the current size is greater than count, the container is reduced to the first count elements. If the current size is less than count, additional default-inserted elements are appended.

Note

If an exception is thrown for any reason, these functions have no effect (strong exception safety guarantee). If T’s move constructor is not noexcept and T is not CopyInsertable into *this, vector will use the throwing move constructor. If it throws, the guarantee is waived and the effects are unspecified.

Note

T must meet the requirements of MoveInsertable and DefaultInsertable.

Throws: std::length_error – If the capacity required by the new vector would exceed max_size().
Parameters: count – New size of the container.

constexpr void resize(size_type count, const value_type &value)

Changes the number of elements stored.

Resizes the container to count elements, does nothing if count == size(). If the current size is greater than count, the container is reduced to the first count elements. If the current size is less than count, additional copies of value are appended.

Note

If an exception is thrown for any reason, these functions have no effect (strong exception safety guarantee). If T’s move constructor is not noexcept and T is not CopyInsertable into *this, vector will use the throwing move constructor. If it throws, the guarantee is waived and the effects are unspecified.

Note

T must meet the requirements of CopyInsertable.

Throws

std::length_error – If the capacity required by the new vector would exceed max_size().

Parameters

count – New size of the container.
value – The value to initialize the new elements with.

constexpr void swap(vector &other) noexcept

Swaps the contents.

Exchanges the contents and capacity of *this with those of other. Does not invoke any move, copy, or swap operations on individual elements. All iterators and references remain valid, except that the end() iterator is invalidated.

Parameters: other – Container to exchange contents with.