bsl::vector

Synopsis

Declared in <bslstl_vector.h>

template<
    class VALUE_TYPE,
    class ALLOCATOR = allocator<VALUE_TYPE>>
class vector
    : public vectorBase<VALUE_TYPE>

Description

1. A call to any method that would result in a vector having a size or capacity greater than the value returned by max_size triggers a call to bslstl::StdExceptUtil::throwLengthError. 2. A call to an at method that attempts to access a position outside of the valid range of a vector triggers a call to bslstl::StdExceptUtil::throwOutOfRange.

Note that portions of the standard methods are implemented in vectorBase, which is parameterized on only VALUE_TYPE in order to generate smaller debug strings.

This class: * supports a complete set of value-semantic operations

except for BDEX serialization * is exception-neutral * is alias-safe * is const thread-safe For terminology see {bsldoc_glossary}.

In addition, the following members offer a full guarantee of rollback: if an exception is thrown during the invocation of push_back or insert with a single element at the end of a pre-existing object, the object is left in a valid state and its value is unchanged.

Base Classes

Name Description

vectorBase<VALUE_TYPE> This class describes the basic layout for a vector class, to be included into the vector layout before the allocator (provided by bslalg::ContainerBase) to take better advantage of cache prefetching. It is parameterized by VALUE_TYPE only, and implements the portion of vector that does not need to know about its (template parameter) type ALLOCATOR (in order to generate shorter debug strings). This class intentionally has no creators (other than the compiler-generated ones).

Name	Description
`vectorBase<VALUE_TYPE>`	This class describes the basic layout for a vector class, to be included into the `vector` layout before the allocator (provided by `bslalg::ContainerBase`) to take better advantage of cache prefetching. It is parameterized by `VALUE_TYPE` only, and implements the portion of `vector` that does not need to know about its (template parameter) type `ALLOCATOR` (in order to generate shorter debug strings). This class intentionally has no creators (other than the compiler-generated ones).

Type Aliases

Name	Description
`allocator_type`	This `typedef` is an alias to the (template parameter) `ALLOCATOR`.
`const_iterator`	This `typedef` is an alias to `VALUE_TYPE const *`.
`const_pointer`	This `typedef` is an alias to `AllocatorTraits::const_pointer`.
`const_reference`	This `typedef` is an alias to `VALUE_TYPE const&`.
`const_reverse_iterator`	This `typedef` is an alias to `bsl::reverse_iterator<const_iterator>`.
`difference_type`	This `typedef` is an alias to `AllocatorTraits::difference_type`.
`iterator`	This `typedef` is an alias to `VALUE_TYPE *`.
`pointer`	This `typedef` is an alias to `AllocatorTraits::pointer`.
`reference`	This `typedef` is an alias to `VALUE_TYPE&`.
`reverse_iterator`	This `typedef` is an alias to `bsl::reverse_iterator<iterator>`.
`size_type`	This `typedef` is an alias to `AllocatorTraits::size_type`.
`value_type`	This `typedef` is an alias to the (template parameter) `VALUE_TYPE`.

Member Functions

Name	Description
`vector` [constructor]	Constructors
`~vector` [destructor]	Destroy this vector.
`operator=`	Assignment operators
`adopt`	Adopt all outstanding memory allocations associated with the specified `base` object. The behavior is undefined unless this object is in a default-constructed state.
`append_range`	Append to the end of this object the elements of the specified `range`. Note that `range` must meet the requirements of an input range and the values from `range` must have a type matching or convertible to (template parameter) `VALUE_TYPE`.
`assign`	`assign` overloads
`assign_range`	Assign to this object the elements of the specified `range`. Note that `range` must meet the requirements of an input range and the values from `range` must have a type matching or convertible to (template parameter) `VALUE_TYPE`.
`at`	`at` overloads
`back`	`back` overloads
`begin`	`begin` overloads
`capacity`	Return the capacity of this vector, i.e., the maximum number of elements for which resizing is guaranteed not to trigger a reallocation.
`cbegin`	Return an iterator providing non-modifiable access to the first element in this vector, and the past-the-end iterator if this vector is empty.
`cend`	Return the past-the-end (forward) iterator providing non-modifiable access to this vector.
`clear`	Remove all elements from this vector making its size 0. Note that although this vector is empty after this method returns, it preserves the same capacity it had before the method was called.
`crbegin`	Return a reverse iterator providing non-modifiable access to the last element in this vector, and the past-the-end reverse iterator if this vector is empty.
`crend`	Return the past-the-end reverse iterator providing non-modifiable access to this vector.
`data`	`data` overloads
`emplace`	Insert at the specified `position` in this vector a newly created `value_type` object, constructed by forwarding `get_allocator()` (if required) and the specified (variable number of) `arguments` to the corresponding constructor of `value_type`, and return an iterator referring to the newly created and inserted element. If an exception is thrown (other than by the copy constructor, move constructor, assignment operator, or move assignment operator of `value_type`), `*this` is unaffected. Throw `std::length_error` if `size() == max_size()`. The behavior is undefined unless `position` is an iterator in the range `[begin() .. end()]` (both endpoints included). This method requires that the (template parameter) type `VALUE_TYPE` be `move-insertable` into this vector and `emplace-constructible` from `arguments` (see {Requirements on `VALUE_TYPE`}).
`emplace_back`	Append to the end of this vector a newly created `value_type` object, constructed by forwarding `get_allocator()` (if required) and the specified (variable number of) `arguments` to the corresponding constructor of `value_type`. Return a reference providing modifiable access to the inserted element. If an exception is thrown (other than by the move constructor of a non-copy-insertable `value_type`), `*this` is unaffected. Throw `std::length_error` if `size() == max_size()`. This method requires that the (template parameter) type `VALUE_TYPE` be `move-insertable` into this vector and `emplace-constructible` from `arguments` (see {Requirements on `VALUE_TYPE`}).
`empty`	Return `true` if this vector has size 0, and `false` otherwise.
`end`	`end` overloads
`erase`	`erase` overloads
`front`	`front` overloads
`get_allocator`	Return (a copy of) the allocator used for memory allocation by this vector.
`insert`	`insert` overloads
`insert_range`	Insert at the specified `position` in this object the elements of the specified `range`. Note that `range` must meet the requirements of an input range and the values from `range` must have a type matching or convertible to (template parameter) `VALUE_TYPE`.
`max_size`	Return a theoretical upper bound on the largest number of elements that this vector could possibly hold. Note that there is no guarantee that the vector can successfully grow to the returned size, or even close to that size without running out of resources. Also note that requests to create a vector longer than this number of elements are guaranteed to raise a `std::length_error` exception.
`operator[]`	Subscript operators
`pop_back`	Erase the last element from this vector. The behavior is undefined if this vector is empty.
`push_back`	`push_back` overloads
`rbegin`	`rbegin` overloads
`rend`	`rend` overloads
`reserve`	Change the capacity of this vector to the specified `newCapacity`. If an exception is thrown (other than by the move constructor of a non-copy-insertable `value_type`), `*this` is unaffected. Throw `bsl::length_error` if `newCapacity > max_size()`. This method requires that the (template parameter) type `VALUE_TYPE` be `move-insertable` into this vector (see {Requirements on `VALUE_TYPE`}). Note that the capacity of this vector after this operation has completed may be greater than `newCapacity`.
`resize`	`resize` overloads
`shrink_to_fit`	Reduce the capacity of this vector to its size. If an exception is thrown (other than by the move constructor of a non-copy-insertable `value_type`), `*this` is unaffected. Note that this method has no effect if the capacity is equivalent to the size.
`size`	Return the number of elements in this vector.
`swap`	Exchange the value of this object with that of the specified `other` object; also exchange the allocator of this object with that of `other` if the (template parameter) type `ALLOCATOR` has the `propagate_on_container_swap` trait, and do not modify either allocator otherwise. This method provides the no-throw exception-safety guarantee. This operation has `O[1]` complexity if either this object was created with the same allocator as `other` or `ALLOCATOR` has the `propagate_on_container_swap` trait; otherwise, it has `O[n + m]` complexity, where `n` and `m` are the number of elements in this object and `other`, respectively. Note that this method`s support for swapping objects created with different allocators when `ALLOCATOR` does not have the `propagate_on_container_swap` trait is a departure from the C++ Standard.

Protected Data Members

Name	Description
`d_capacity`	Capacity of data storage in number of elements.
`d_dataBegin_p`	Beginning of data storage (owned).
`d_dataEnd_p`	One past the end of data storage.

Specializations

Name	Description
`vector<Json>`	This class template provides an STL-compliant `vector` that conforms to the `bslma::Allocator` model. For the requirements of a vector class, consult the C++11 standard. In particular, this implementation offers the general rules that:
`vector<MetricSampleGroup>`	This class template provides an STL-compliant `vector` that conforms to the `bslma::Allocator` model. For the requirements of a vector class, consult the C++11 standard. In particular, this implementation offers the general rules that:
`vector<UserFieldValue>`	This class template provides an STL-compliant `vector` that conforms to the `bslma::Allocator` model. For the requirements of a vector class, consult the C++11 standard. In particular, this implementation offers the general rules that:
`vector<ZoneinfoTransition>`	This class template provides an STL-compliant `vector` that conforms to the `bslma::Allocator` model. For the requirements of a vector class, consult the C++11 standard. In particular, this implementation offers the general rules that:
`vector<bool>`
`vector<char>`
`vector<double>`
`vector<float>`
`vector<int>`
`vector<long>`
`vector<long double>`
`vector<long long>`
`vector<short>`
`vector<signed char>`
`vector<unsigned char>`
`vector<unsigned int>`
`vector<unsigned long>`
`vector<unsigned long long>`
`vector<unsigned short>`
`vector<pair<Date, DayOfWeekSet>>`	This class template provides an STL-compliant `vector` that conforms to the `bslma::Allocator` model. For the requirements of a vector class, consult the C++11 standard. In particular, this implementation offers the general rules that:
`vector<void*>`
`vector<char const*>`
`vector<VALUE_TYPE*, ALLOCATOR>`	This partial specialization of `vector` for pointer types to a (template parameter) `VALUE_TYPE` type is implemented in terms of `vector<UintPtr>` to reduce the amount of code generated. Note that this specialization rebinds the (template parameter) `ALLOCATOR` type to an allocator of `UintPtr` so as to satisfy the invariant in the `vector` base class. Note that the contract for all members is the same as the primary template, so documentation is not repeated to avoid accidentally introducing inconsistency over time.

Deduction Guides

Name	Description
`vector<VALUE>`	Deduce the template parameter `VALUE` from the `value_type` of the iterators supplied to the constructor of `vector`.
`vector<VALUE>`	Deduce the template parameter `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `vector`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<VALUE>`.
`vector<VALUE>`	Deduce the template parameter `VALUE` from the `value_type` of the iterators supplied to the constructor of `vector`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<VALUE>`.
`vector<VALUE>`	Deduce the template parameter `VALUE` from the corresponding parameter supplied to the constructor of `vector`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<VALUE>`.
`vector<VALUE, ALLOCATOR>`	Deduce the template parameter `VALUE` from the `value_type` of the iterators supplied to the constructor of `vector`. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
`vector<ranges::range_value_t<t_RANGE>, t_ALLOCATOR>`	Deduce the template parameters `VALUE_TYPE` and `ALLOCATOR` from the parameters supplied to the constructor of `vector`.

Non-Member Functions

Name	Description
`bdlat_valueTypeAssign`	Assign the specified `rhs` vector to the specified `lhs` vector and return 0.
`erase`	Erase all the elements in the specified vector `vec` that compare equal to the specified `value`. Return the number of elements erased.
`erase_if`	Erase all the elements in the specified vector `vec` that satisfy the specified predicate `predicate`. Return the number of elements erased.
`operator<=>`	Perform a lexicographic three-way comparison of the specified `lhs` and the specified `rhs` vectors by using the comparison operators of `VALUE_TYPE` on each element; return the result of that comparison.
`operator<=>`	Perform a three-way comparison of the specified `lhs` and `rhs` vectors and return the result of that comparison.
`operator<=>`	Perform a three-way comparison of the specified `lhs` and `rhs` vectors and return the result of that comparison.
`operator==`	Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise. Two `vector` objects `lhs` and `rhs` have the same value if they have the same number of elements, and each element in the ordered sequence of elements of `lhs` has the same value as the corresponding element in the ordered sequence of elements of `rhs`. This method requires that the (template parameter) type `VALUE_TYPE` be `equality-comparable` (see {Requirements on `VALUE_TYPE`}).
`operator==`	Return `true` if the specified `lhs` and `rhs` vectors have the same value, and `false` otherwise.
`operator==`	Return `true` if the specified `lhs` and `rhs` vectors have the same value, and `false` otherwise.
`swap`	Exchange the values of the specified `a` and `b` objects.
`swap`	Exchange the values of the specified `a` and `b` objects.
`swap`	Exchange the value of the specified `a` object with that of the specified `b` object; also exchange the allocator of `a` with that of `b` if the (template parameter) type `ALLOCATOR` has the `propagate_on_container_swap` trait, and do not modify either allocator otherwise. This function provides the no-throw exception-safety guarantee. This operation has `O[1]` complexity if either `a` was created with the same allocator as `b` or `ALLOCATOR` has the `propagate_on_container_swap` trait; otherwise, it has `O[n + m]` complexity, where `n` and `m` are the number of elements in `a` and `b`, respectively. Note that this function`s support for swapping objects created with different allocators when `ALLOCATOR` does not have the `propagate_on_container_swap` trait is a departure from the C++ Standard.
`::BloombergLP::bdlat_ArrayFunctions::bdlat_arrayAccessElement`	Invoke the specified `accessor` on the element at the specified `index` of the specified `array`. Return the value from the invocation of `accessor`.
`::BloombergLP::bdlat_ArrayFunctions::bdlat_arrayManipulateElement`	Apply the specified `manipulator` to the element at the specified `index` in the specified `array`.
`::BloombergLP::bdlat_ArrayFunctions::bdlat_arrayReserve`	Reserve capacity for the specified `array` to hold at least the specified `numElements` elements.
`::BloombergLP::bdlat_ArrayFunctions::bdlat_arrayResize`	Resize the specified `array` to contain the specified `newSize` elements.
`::BloombergLP::bdlat_ArrayFunctions::bdlat_arraySize`	Return the number of elements in the specified `array`.
`::BloombergLP::bdlat_ArrayFunctions::bdlat_arraySupportsReserve`	Return `true` if the specified `array` supports the `reserve` method.
`::BloombergLP::bdlat_ArrayIterators::backInserter`	Specialization of `backInserter` for `bsl::vector`. Return `bsl::back_insert_iterator instead of` BackInsertIterator'.