[#bsl-list-054]
= xref:bsl.adoc[bsl]::list
:relfileprefix: ../
:mrdocs:

Forward declaration required by `List_NodeProctor`.

== Synopsis

Declared in `<bslstl_list.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    class LIST_VALUE,
    class LIST_ALLOCATOR = xref:bsl/allocator-0df.adoc[bsl::allocator<VALUE>]>
class list;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/list-054/allocator_type.adoc[`allocator_type`] 
| Allocator type used by this list.
| xref:bsl/list-054/const_iterator.adoc[`const_iterator`] 
| Iterator providing non‐modifiable access to elements in this list.
| xref:bsl/list-054/const_pointer.adoc[`const_pointer`] 
| Pointer to a non‐modifiable element in this list.
| xref:bsl/list-054/const_reference.adoc[`const_reference`] 
| Reference to a non‐modifiable element stored in this list.
| xref:bsl/list-054/const_reverse_iterator.adoc[`const_reverse_iterator`] 
| Reverse iterator over non‐modifiable list elements.
| xref:bsl/list-054/difference_type.adoc[`difference_type`] 
| Signed integral type used to express distances between iterators.
| xref:bsl/list-054/iterator.adoc[`iterator`] 
| Iterator providing modifiable access to elements in this list.
| xref:bsl/list-054/pointer.adoc[`pointer`] 
| Pointer to a modifiable element in this list.
| xref:bsl/list-054/reference.adoc[`reference`] 
| Reference to an element stored in this list.
| xref:bsl/list-054/reverse_iterator.adoc[`reverse_iterator`] 
| Reverse iterator over modifiable list elements.
| xref:bsl/list-054/size_type.adoc[`size_type`] 
| Unsigned integral type large enough to hold any valid element count.
| xref:bsl/list-054/value_type.adoc[`value_type`] 
| Type of the elements stored in this list.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/list-054/2constructor-028.adoc[`list`]         [.small]#[constructor]#
| Constructors
| xref:bsl/list-054/2destructor.adoc[`~list`] [.small]#[destructor]#
| Destroy this list by calling the destructor for each element and deallocating all allocated storage.
| xref:bsl/list-054/operator_assign-03.adoc[`operator=`] 
| Assignment operators
| xref:bsl/list-054/append_range.adoc[`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`.
| xref:bsl/list-054/assign-089.adoc[`assign`] 
| `assign` overloads
| xref:bsl/list-054/assign_range.adoc[`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`.
| xref:bsl/list-054/back-0b.adoc[`back`] 
| `back` overloads
| xref:bsl/list-054/begin-0d.adoc[`begin`] 
| `begin` overloads
| xref:bsl/list-054/cbegin.adoc[`cbegin`] 
| Return an iterator providing non‐modifiable access to the first `value_type` object in the ordered sequence of `value_type` objects maintained by this list, or the `end` iterator if this list is empty.
| xref:bsl/list-054/cend.adoc[`cend`] 
| Return the past‐the‐end (forward) iterator providing non‐modifiable access to this list.
| xref:bsl/list-054/clear.adoc[`clear`] 
| Remove all the elements from this list.
| xref:bsl/list-054/crbegin.adoc[`crbegin`] 
| Return a reverse iterator providing non‐modifiable access to the last element in this list, and the past‐the‐end reverse iterator if this list is empty.
| xref:bsl/list-054/crend.adoc[`crend`] 
| Return the past‐the‐end reverse iterator providing non‐modifiable access to this list.
| xref:bsl/list-054/emplace.adoc[`emplace`] 
| Insert at the specified `position` in this list 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 providing modifiable access 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 method has no effect. This method requires that the (template parameter) `VALUE` be `move‐insertable` into this list and `emplace‐constructible` from `arguments` (see {Requirements on `VALUE`}). The behavior is undefined unless `position` is an iterator in the range `[cbegin() .. cend()]` (both endpoints included).
| xref:bsl/list-054/emplace_back.adoc[`emplace_back`] 
| Append to the back of this list 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 method has no effect. This method requires that the (template parameter) `VALUE` be `move‐insertable` into this list and `emplace‐constructible` from `arguments` (see {Requirements on `VALUE`}).
| xref:bsl/list-054/emplace_front.adoc[`emplace_front`] 
| Prepend to the front of this list 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 method has no effect. This method requires that the (template parameter) `VALUE` be `move‐insertable` into this list and `emplace‐constructible` from `arguments` (see {Requirements on `VALUE`}).
| xref:bsl/list-054/empty.adoc[`empty`] 
| Return `true` if this list has no elements, and `false` otherwise.
| xref:bsl/list-054/end-04.adoc[`end`] 
| `end` overloads
| xref:bsl/list-054/erase-0e.adoc[`erase`] 
| `erase` overloads
| xref:bsl/list-054/front-08.adoc[`front`] 
| `front` overloads
| xref:bsl/list-054/get_allocator.adoc[`get_allocator`] 
| Return a copy of the allocator used for memory allocation by this list.
| xref:bsl/list-054/insert-0a5.adoc[`insert`] 
| `insert` overloads
| xref:bsl/list-054/insert_range.adoc[`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`.
| xref:bsl/list-054/max_size.adoc[`max_size`] 
| Return an upper bound on the largest number of elements that this list could possibly hold. Note that the return value of this function does not guarantee that this list can successfully grow that large, or even close to that large without running out of resources.
| xref:bsl/list-054/merge-076.adoc[`merge`] 
| `merge` overloads
| xref:bsl/list-054/pop_back.adoc[`pop_back`] 
| Remove and destroy the last element of this list. The behavior is undefined unless this list contains at least one element.
| xref:bsl/list-054/pop_front.adoc[`pop_front`] 
| Remove and destroy the first element of this list. The behavior is undefined unless this list contains at least one element.
| xref:bsl/list-054/prepend_range.adoc[`prepend_range`] 
| Prepend to the front 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`.
| xref:bsl/list-054/push_back-0f.adoc[`push_back`] 
| `push_back` overloads
| xref:bsl/list-054/push_front-03.adoc[`push_front`] 
| `push_front` overloads
| xref:bsl/list-054/rbegin-01.adoc[`rbegin`] 
| `rbegin` overloads
| xref:bsl/list-054/remove.adoc[`remove`] 
| Erase all the elements having the specified `value` from this list and return the number of erased elements.
| xref:bsl/list-054/remove_if.adoc[`remove_if`] 
| Erase all the elements in this list for which the specified unary `predicate` returns `true` and return the number of erased elements.
| xref:bsl/list-054/rend-0d.adoc[`rend`] 
| `rend` overloads
| xref:bsl/list-054/resize-09.adoc[`resize`] 
| `resize` overloads
| xref:bsl/list-054/reverse.adoc[`reverse`] 
| Reverse the order of the elements in this list.
| xref:bsl/list-054/size.adoc[`size`] 
| Return the number of elements in this list.
| xref:bsl/list-054/sort-08.adoc[`sort`] 
| `sort` overloads
| xref:bsl/list-054/splice-0a6.adoc[`splice`] 
| `splice` overloads
| xref:bsl/list-054/swap.adoc[`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.
| xref:bsl/list-054/unique-0d.adoc[`unique`] 
| `unique` overloads
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/list-08.adoc[`list<VALUE>`] 
| Deduce the template parameter `VALUE` from the `value_type` of the iterators supplied to the constructor of `list`.
| xref:bsl/list-0a.adoc[`list<VALUE>`] 
| Deduce the template parameter `VALUE` from the value_type of the intializer_list supplied to the constructor of `list`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<CHAR_TYPE>`.
| xref:bsl/list-01.adoc[`list<VALUE>`] 
| Deduce the template parameter `VALUE` from the value_type of the iterators supplied to the constructor of `list`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<CHAR_TYPE>`.
| xref:bsl/list-05c.adoc[`list<VALUE>`] 
| Deduce the template parameter `VALUE` from the corresponding parameter supplied to the constructor of `list`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<VALUE>`.
| xref:bsl/list-00.adoc[`list<VALUE, ALLOCATOR>`] 
| Deduce the template parameter `VALUE` from the `value_type` of the iterators supplied to the constructor of `list`. Deduce the template parameter `ALLOCATOR` from the allocator supplied to the constructor of `list`. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
| xref:bsl/list-06.adoc[`list<ranges::range_value_t<t_RANGE>, t_ALLOCATOR>`] 
| Deduce the template parameters `VALUE_TYPE` and `ALLOCATOR` from the parameters supplied to the constructor of `list`.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/List_NodeProctor.adoc[bsl::List_NodeProctor]`
| This class provides a proctor to free a node containing an uninitialized `VALUE` object in the event that an exception is thrown.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/erase-086.adoc[`erase`]
| Erase all the elements in the specified list `l` that compare equal to the specified `value`. Return the number of elements erased.
| xref:bsl/erase_if-076.adoc[`erase_if`]
| Erase all the elements in the specified list `l` that satisfy the specified predicate `predicate`. Return the number of elements erased.
| xref:bsl/operator_3way-0f6.adoc[`operator<=>`]
| Perform a lexicographic three‐way comparison of the specified `lhs` and the specified `rhs` lists by using the comparison operators of `VALUE` on each element; return the result of that comparison.
| xref:bsl/operator_eq-0b6.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise. Two `list` 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` be `equality‐comparable` (see {Requirements on `VALUE`}).
| xref:bsl/swap-06d9.adoc[`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.
|===


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