[#bsl-vector-00d]
= xref:bsl.adoc[bsl]::vector
:relfileprefix: ../
:mrdocs:

STL‐compliant sequence container conforming to the `bslma` model.

== Synopsis

Declared in `<bslstl_vector.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    class VALUE_TYPE,
    class ALLOCATOR = xref:bsl/allocator-0df.adoc[allocator<VALUE_TYPE>]>
class vector
    : public xref:bsl/vectorBase-06.adoc[vectorBase<VALUE_TYPE>]
----

== Description

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:

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

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/vectorBase-06.adoc[vectorBase<VALUE_TYPE>]`
| Allocator‐independent storage layout shared by `vector`.
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/vector-00d/allocator_type.adoc[`allocator_type`] 
| This `typedef` is an alias to the (template parameter) `ALLOCATOR`.
| xref:bsl/vector-00d/const_iterator.adoc[`const_iterator`] 
| This `typedef` is an alias to `VALUE_TYPE const *`.
| xref:bsl/vector-00d/const_pointer.adoc[`const_pointer`] 
| This `typedef` is an alias to `AllocatorTraits::const_pointer`.
| xref:bsl/vector-00d/const_reference.adoc[`const_reference`] 
| This `typedef` is an alias to `VALUE_TYPE const&`.
| xref:bsl/vector-00d/const_reverse_iterator.adoc[`const_reverse_iterator`] 
| This `typedef` is an alias to `bsl::reverse_iterator<const_iterator>`.
| xref:bsl/vector-00d/difference_type.adoc[`difference_type`] 
| This `typedef` is an alias to `AllocatorTraits::difference_type`.
| xref:bsl/vector-00d/iterator.adoc[`iterator`] 
| This `typedef` is an alias to `VALUE_TYPE *`.
| xref:bsl/vector-00d/pointer.adoc[`pointer`] 
| This `typedef` is an alias to `AllocatorTraits::pointer`.
| xref:bsl/vector-00d/reference.adoc[`reference`] 
| This `typedef` is an alias to `VALUE_TYPE&`.
| xref:bsl/vector-00d/reverse_iterator.adoc[`reverse_iterator`] 
| This `typedef` is an alias to `bsl::reverse_iterator<iterator>`.
| xref:bsl/vector-00d/size_type.adoc[`size_type`] 
| This `typedef` is an alias to `AllocatorTraits::size_type`.
| xref:bsl/vector-00d/value_type.adoc[`value_type`] 
| This `typedef` is an alias to the (template parameter) `VALUE_TYPE`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/vector-00d/2constructor-037.adoc[`vector`]         [.small]#[constructor]#
| Constructors
| xref:bsl/vector-00d/2destructor.adoc[`~vector`] [.small]#[destructor]#
| Destroy this vector.
| xref:bsl/vector-00d/operator_assign-0bc.adoc[`operator=`] 
| Assignment operators
| xref:bsl/vectorBase-06/adopt.adoc[`adopt`] 
| Adopt memory allocations from the specified `base` object.
| xref:bsl/vector-00d/append_range.adoc[`append_range`] 
| Append elements from a range to this vector.
| xref:bsl/vector-00d/assign-00.adoc[`assign`] 
| Assign a new value to this vector.
| xref:bsl/vector-00d/assign_range.adoc[`assign_range`] 
| Assign elements from a range to this vector.
| xref:bsl/vectorBase-06/at-0cb.adoc[`at`] 
| `at` overloads
| xref:bsl/vectorBase-06/back-04.adoc[`back`] 
| `back` overloads
| xref:bsl/vectorBase-06/begin-0ce8.adoc[`begin`] 
| `begin` overloads
| xref:bsl/vectorBase-06/capacity.adoc[`capacity`] 
| Return the capacity of this vector, i.e., the maximum number of elements for which resizing is guaranteed not to trigger a reallocation.
| xref:bsl/vectorBase-06/cbegin.adoc[`cbegin`] 
| Return a const iterator to the first element.
| xref:bsl/vectorBase-06/cend.adoc[`cend`] 
| Return the past‐the‐end (forward) iterator providing non‐modifiable access to this vector.
| xref:bsl/vector-00d/clear.adoc[`clear`] 
| Remove all elements from this vector.
| xref:bsl/vectorBase-06/crbegin.adoc[`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.
| xref:bsl/vectorBase-06/crend.adoc[`crend`] 
| Return the past‐the‐end reverse iterator providing non‐modifiable access to this vector.
| xref:bsl/vectorBase-06/data-0e.adoc[`data`] 
| `data` overloads
| xref:bsl/vector-00d/emplace.adoc[`emplace`] 
| Emplace a newly constructed element at the specified position.
| xref:bsl/vector-00d/emplace_back.adoc[`emplace_back`] 
| Emplace a newly constructed element at the end.
| xref:bsl/vectorBase-06/empty.adoc[`empty`] 
| Return `true` if this vector has size 0, and `false` otherwise.
| xref:bsl/vectorBase-06/end-0c.adoc[`end`] 
| `end` overloads
| xref:bsl/vector-00d/erase-00.adoc[`erase`] 
| Erase elements from this vector.
| xref:bsl/vectorBase-06/front-05.adoc[`front`] 
| `front` overloads
| xref:bsl/vector-00d/get_allocator.adoc[`get_allocator`] 
| Return (a copy of) the allocator used for memory allocation by this vector.
| xref:bsl/vector-00d/insert-06b7.adoc[`insert`] 
| `insert` overloads
| xref:bsl/vector-00d/insert_range.adoc[`insert_range`] 
| Insert the elements of `range` before `position`.
| xref:bsl/vector-00d/max_size.adoc[`max_size`] 
| Return a theoretical upper bound on this vector's size.
| xref:bsl/vectorBase-06/operator_subs-02.adoc[`operator[]`] 
| Subscript operators
| xref:bsl/vector-00d/pop_back.adoc[`pop_back`] 
| Erase the last element from this vector. The behavior is undefined if this vector is empty.
| xref:bsl/vector-00d/push_back-0b.adoc[`push_back`] 
| `push_back` overloads
| xref:bsl/vectorBase-06/rbegin-09.adoc[`rbegin`] 
| `rbegin` overloads
| xref:bsl/vectorBase-06/rend-01.adoc[`rend`] 
| `rend` overloads
| xref:bsl/vector-00d/reserve.adoc[`reserve`] 
| Increase capacity to at least `newCapacity` if needed.
| xref:bsl/vector-00d/resize-03.adoc[`resize`] 
| `resize` overloads
| xref:bsl/vector-00d/shrink_to_fit.adoc[`shrink_to_fit`] 
| Request that unused capacity be released.
| xref:bsl/vectorBase-06/size.adoc[`size`] 
| Return the number of elements in this vector.
| xref:bsl/vector-00d/swap.adoc[`swap`] 
| Exchange the value of this object with `other`.
|===


== Protected Data Members

[cols="1,4"]
|===
| Name| Description
| xref:bsl/vectorBase-06/d_capacity.adoc[`d_capacity`] 
| Capacity of data storage in number of elements.
| xref:bsl/vectorBase-06/d_dataBegin_p.adoc[`d_dataBegin_p`] 
| Beginning of data storage (owned).
| xref:bsl/vectorBase-06/d_dataEnd_p.adoc[`d_dataEnd_p`] 
| One past the end of data storage.
|===


== Specializations

[cols="1,4"]
|===
| Name| Description
| xref:bsl/vector-086.adoc[`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.
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/vector-07.adoc[`vector<VALUE>`] 
| Deduce the template parameter `VALUE` from the `value_type` of the iterators supplied to the constructor of `vector`.
| xref:bsl/vector-083.adoc[`vector<VALUE>`] 
| Deduce template arguments for `vector` from constructor arguments.
| xref:bsl/vector-04b.adoc[`vector<VALUE>`] 
| Deduce the template parameter `VALUE` from the `value_type` of the iterators supplied to the constructor of `vector`.
| xref:bsl/vector-009.adoc[`vector<VALUE>`] 
| Deduce the template parameter `VALUE` from the corresponding parameter supplied to the constructor of `vector`.
| xref:bsl/vector-042.adoc[`vector<VALUE, ALLOCATOR>`] 
| Deduce the template parameter `VALUE` from the `value_type` of the iterators supplied to the constructor of `vector`.
| xref:bsl/vector-0a.adoc[`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

[cols="1,4"]
|===
| Name| Description
| xref:bsl/bdlat_valueTypeAssign.adoc[`bdlat_valueTypeAssign`]
| Assign the specified `rhs` vector to the specified `lhs` vector.
| xref:bsl/erase-0c.adoc[`erase`]
| Erase all the elements in the specified vector `vec` that compare equal to the specified `value`. Return the number of elements erased.
| xref:bsl/erase_if-03a.adoc[`erase_if`]
| Erase all the elements in the specified vector `vec` that satisfy the specified predicate `predicate`. Return the number of elements erased.
| xref:bsl/operator_3way-01c.adoc[`operator<=>`]
| Perform a three‐way comparison of the operands.
| xref:bsl/operator_eq-013.adoc[`operator==`]
| Return whether the operands have the same value.
| xref:bsl/swap-0a1.adoc[`swap`]
| Exchange the contents of two vectors.
| xref:BloombergLP/bdlat_ArrayFunctions/bdlat_arrayAccessElement.adoc[`::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`.
| xref:BloombergLP/bdlat_ArrayFunctions/bdlat_arrayManipulateElement.adoc[`::BloombergLP::bdlat_ArrayFunctions::bdlat_arrayManipulateElement`]
| Apply the specified `manipulator` to the element at the specified `index` in the specified `array`.
| xref:BloombergLP/bdlat_ArrayFunctions/bdlat_arrayReserve-01.adoc[`::BloombergLP::bdlat_ArrayFunctions::bdlat_arrayReserve`]
| Reserve capacity for the specified `array` to hold at least the specified `numElements` elements.
| xref:BloombergLP/bdlat_ArrayFunctions/bdlat_arrayResize.adoc[`::BloombergLP::bdlat_ArrayFunctions::bdlat_arrayResize`]
| Resize the specified `array` to contain the specified `newSize` elements.
| xref:BloombergLP/bdlat_ArrayFunctions/bdlat_arraySize.adoc[`::BloombergLP::bdlat_ArrayFunctions::bdlat_arraySize`]
| Return the number of elements in the specified `array`.
| xref:BloombergLP/bdlat_ArrayFunctions/bdlat_arraySupportsReserve-06.adoc[`::BloombergLP::bdlat_ArrayFunctions::bdlat_arraySupportsReserve`]
| Return `true` if the specified `array` supports the `reserve` method.
| xref:BloombergLP/bdlat_ArrayIterators/backInserter-0c.adoc[`::BloombergLP::bdlat_ArrayIterators::backInserter`]
| Specialization of `backInserter` for `bsl::vector`. Return `bsl::back_insert_iterator` instead of `BackInsertIterator`.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#