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

Forward declaration required by `List&lowbar;NodeProctor`&period;

== Synopsis

Declared in `&lt;bslstl&lowbar;list&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;
    class LIST&lowbar;VALUE,
    class LIST&lowbar;ALLOCATOR = xref:bsl/allocator-0df.adoc[bsl::allocator&lt;VALUE&gt;]&gt;
class list;
----

== Type Aliases

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


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/list-054/2constructor-028.adoc[`list`]         [.small]#[constructor]#
| Constructors
| xref:bsl/list-054/2destructor.adoc[`&#126;list`] [.small]#[destructor]#
| Destroy this list by calling the destructor for each element and deallocating all allocated storage&period;
| xref:bsl/list-054/operator_assign-03.adoc[`operator&equals;`] 
| Assignment operators
| xref:bsl/list-054/append_range.adoc[`append&lowbar;range`] 
| Append to the end of this object the elements of the specified `range`&period; 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`&period;
| xref:bsl/list-054/assign-089.adoc[`assign`] 
| `assign` overloads
| xref:bsl/list-054/assign_range.adoc[`assign&lowbar;range`] 
| Assign to this object the elements of the specified `range`&period; 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`&period;
| 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&hyphen;modifiable access to the first `value&lowbar;type` object in the ordered sequence of `value&lowbar;type` objects maintained by this list, or the `end` iterator if this list is empty&period;
| xref:bsl/list-054/cend.adoc[`cend`] 
| Return the past&hyphen;the&hyphen;end (forward) iterator providing non&hyphen;modifiable access to this list&period;
| xref:bsl/list-054/clear.adoc[`clear`] 
| Remove all the elements from this list&period;
| xref:bsl/list-054/crbegin.adoc[`crbegin`] 
| Return a reverse iterator providing non&hyphen;modifiable access to the last element in this list, and the past&hyphen;the&hyphen;end reverse iterator if this list is empty&period;
| xref:bsl/list-054/crend.adoc[`crend`] 
| Return the past&hyphen;the&hyphen;end reverse iterator providing non&hyphen;modifiable access to this list&period;
| xref:bsl/list-054/emplace.adoc[`emplace`] 
| Insert at the specified `position` in this list a newly created `value&lowbar;type` object, constructed by forwarding `get&lowbar;allocator()` (if required) and the specified (variable number of) `arguments` to the corresponding constructor of `value&lowbar;type`, and return an iterator providing modifiable access to the newly created and inserted element&period; If an exception is thrown (other than by the copy constructor, move constructor, assignment operator, or move assignment operator of `value&lowbar;type`), this method has no effect&period; This method requires that the (template parameter) `VALUE` be `move&hyphen;insertable` into this list and `emplace&hyphen;constructible` from `arguments` (see &lcub;Requirements on `VALUE`&rcub;)&period; The behavior is undefined unless `position` is an iterator in the range `&lsqb;cbegin() &period;&period; cend()&rsqb;` (both endpoints included)&period;
| xref:bsl/list-054/emplace_back.adoc[`emplace&lowbar;back`] 
| Append to the back of this list a newly created `value&lowbar;type` object, constructed by forwarding `get&lowbar;allocator()` (if required) and the specified (variable number of) `arguments` to the corresponding constructor of `value&lowbar;type`&period; Return a reference providing modifiable access to the inserted element&period; If an exception is thrown (other than by the move constructor of a non&hyphen;copy&hyphen;insertable `value&lowbar;type`), this method has no effect&period; This method requires that the (template parameter) `VALUE` be `move&hyphen;insertable` into this list and `emplace&hyphen;constructible` from `arguments` (see &lcub;Requirements on `VALUE`&rcub;)&period;
| xref:bsl/list-054/emplace_front.adoc[`emplace&lowbar;front`] 
| Prepend to the front of this list a newly created `value&lowbar;type` object, constructed by forwarding `get&lowbar;allocator()` (if required) and the specified (variable number of) `arguments` to the corresponding constructor of `value&lowbar;type`&period; Return a reference providing modifiable access to the inserted element&period; If an exception is thrown (other than by the move constructor of a non&hyphen;copy&hyphen;insertable `value&lowbar;type`), this method has no effect&period; This method requires that the (template parameter) `VALUE` be `move&hyphen;insertable` into this list and `emplace&hyphen;constructible` from `arguments` (see &lcub;Requirements on `VALUE`&rcub;)&period;
| xref:bsl/list-054/empty.adoc[`empty`] 
| Return `true` if this list has no elements, and `false` otherwise&period;
| 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&lowbar;allocator`] 
| Return a copy of the allocator used for memory allocation by this list&period;
| xref:bsl/list-054/insert-0a5.adoc[`insert`] 
| `insert` overloads
| xref:bsl/list-054/insert_range.adoc[`insert&lowbar;range`] 
| Insert at the specified `position` in this object the elements of the specified `range`&period; 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`&period;
| xref:bsl/list-054/max_size.adoc[`max&lowbar;size`] 
| Return an upper bound on the largest number of elements that this list could possibly hold&period; 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&period;
| xref:bsl/list-054/merge-076.adoc[`merge`] 
| `merge` overloads
| xref:bsl/list-054/pop_back.adoc[`pop&lowbar;back`] 
| Remove and destroy the last element of this list&period; The behavior is undefined unless this list contains at least one element&period;
| xref:bsl/list-054/pop_front.adoc[`pop&lowbar;front`] 
| Remove and destroy the first element of this list&period; The behavior is undefined unless this list contains at least one element&period;
| xref:bsl/list-054/prepend_range.adoc[`prepend&lowbar;range`] 
| Prepend to the front of this object the elements of the specified `range`&period; 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`&period;
| xref:bsl/list-054/push_back-0f.adoc[`push&lowbar;back`] 
| `push&lowbar;back` overloads
| xref:bsl/list-054/push_front-03.adoc[`push&lowbar;front`] 
| `push&lowbar;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&period;
| xref:bsl/list-054/remove_if.adoc[`remove&lowbar;if`] 
| Erase all the elements in this list for which the specified unary `predicate` returns `true` and return the number of erased elements&period;
| 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&period;
| xref:bsl/list-054/size.adoc[`size`] 
| Return the number of elements in this list&period;
| 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&semi; also exchange the allocator of this object with that of `other` if the (template parameter) type `ALLOCATOR` has the `propagate&lowbar;on&lowbar;container&lowbar;swap` trait, and do not modify either allocator otherwise&period; This method provides the no&hyphen;throw exception&hyphen;safety guarantee&period; This operation has `O&lsqb;1&rsqb;` complexity if either this object was created with the same allocator as `other` or `ALLOCATOR` has the `propagate&lowbar;on&lowbar;container&lowbar;swap` trait&semi; otherwise, it has `O&lsqb;n &plus; m&rsqb;` complexity, where `n` and `m` are the number of elements in this object and `other`, respectively&period; Note that this method&grave;s support for swapping objects created with different allocators when `ALLOCATOR` does not have the `propagate&lowbar;on&lowbar;container&lowbar;swap` trait is a departure from the C&plus;&plus; Standard&period;
| xref:bsl/list-054/unique-0d.adoc[`unique`] 
| `unique` overloads
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/list-08.adoc[`list&lt;VALUE&gt;`] 
| Deduce the template parameter `VALUE` from the `value&lowbar;type` of the iterators supplied to the constructor of `list`&period;
| xref:bsl/list-0a.adoc[`list&lt;VALUE&gt;`] 
| Deduce the template parameter `VALUE` from the value&lowbar;type of the intializer&lowbar;list supplied to the constructor of `list`&period; This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl&colon;&colon;allocator&lt;CHAR&lowbar;TYPE&gt;`&period;
| xref:bsl/list-01.adoc[`list&lt;VALUE&gt;`] 
| Deduce the template parameter `VALUE` from the value&lowbar;type of the iterators supplied to the constructor of `list`&period; This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl&colon;&colon;allocator&lt;CHAR&lowbar;TYPE&gt;`&period;
| xref:bsl/list-05c.adoc[`list&lt;VALUE&gt;`] 
| Deduce the template parameter `VALUE` from the corresponding parameter supplied to the constructor of `list`&period; This deduction guide does not participate unless the supplied allocator is convertible to `bsl&colon;&colon;allocator&lt;VALUE&gt;`&period;
| xref:bsl/list-00.adoc[`list&lt;VALUE, ALLOCATOR&gt;`] 
| Deduce the template parameter `VALUE` from the `value&lowbar;type` of the iterators supplied to the constructor of `list`&period; Deduce the template parameter `ALLOCATOR` from the allocator supplied to the constructor of `list`&period; This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator&period;
| xref:bsl/list-06.adoc[`list&lt;ranges::range&lowbar;value&lowbar;t&lt;t&lowbar;RANGE&gt;, t&lowbar;ALLOCATOR&gt;`] 
| Deduce the template parameters `VALUE&lowbar;TYPE` and `ALLOCATOR` from the parameters supplied to the constructor of `list`&period;
|===


== Friends

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

== 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`&period; Return the number of elements erased&period;
| xref:bsl/erase_if-076.adoc[`erase&lowbar;if`]
| Erase all the elements in the specified list `l` that satisfy the specified predicate `predicate`&period; Return the number of elements erased&period;
| xref:bsl/operator_3way-0f6.adoc[`operator&lt;&equals;&gt;`]
| Perform a lexicographic three&hyphen;way comparison of the specified `lhs` and the specified `rhs` lists by using the comparison operators of `VALUE` on each element&semi; return the result of that comparison&period;
| xref:bsl/operator_eq-0b6.adoc[`operator&equals;&equals;`]
| Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise&period; 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`&period; This method requires that the (template parameter) type `VALUE` be `equality&hyphen;comparable` (see &lcub;Requirements on `VALUE`&rcub;)&period;
| xref:bsl/swap-06d9.adoc[`swap`]
| Exchange the value of the specified `a` object with that of the specified `b` object&semi; also exchange the allocator of `a` with that of `b` if the (template parameter) type `ALLOCATOR` has the `propagate&lowbar;on&lowbar;container&lowbar;swap` trait, and do not modify either allocator otherwise&period; This function provides the no&hyphen;throw exception&hyphen;safety guarantee&period; This operation has `O&lsqb;1&rsqb;` complexity if either `a` was created with the same allocator as `b` or `ALLOCATOR` has the `propagate&lowbar;on&lowbar;container&lowbar;swap` trait&semi; otherwise, it has `O&lsqb;n &plus; m&rsqb;` complexity, where `n` and `m` are the number of elements in `a` and `b`, respectively&period; Note that this function&grave;s support for swapping objects created with different allocators when `ALLOCATOR` does not have the `propagate&lowbar;on&lowbar;container&lowbar;swap` trait is a departure from the C&plus;&plus; Standard&period;
|===


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