list (STL/CLR)
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at list (STL/CLR).
The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container list to manage a sequence of elements as a bidirectional linked list of nodes, each storing one element.
In the description below, GValue is the same as Value unless the latter is a ref type, in which case it is Value^.
Syntax
template<typename Value>
ref class list
: public
System::ICloneable,
System::Collections::IEnumerable,
System::Collections::ICollection,
System::Collections::Generic::IEnumerable<GValue>,
System::Collections::Generic::ICollection<GValue>,
Microsoft::VisualC::StlClr::IList<GValue>
{ ..... };
Parameters
Value
The type of an element in the controlled sequence.
Members
| Type Definition | Description |
|---|---|
| list::const_iterator (STL/CLR) | The type of a constant iterator for the controlled sequence. |
| list::const_reference (STL/CLR) | The type of a constant reference to an element. |
| list::const_reverse_iterator (STL/CLR) | The type of a constant reverse iterator for the controlled sequence. |
| list::difference_type (STL/CLR) | The type of a signed distance between two elements. |
| list::generic_container (STL/CLR) | The type of the generic interface for the container. |
| list::generic_iterator (STL/CLR) | The type of an iterator for the generic interface for the container. |
| list::generic_reverse_iterator (STL/CLR) | The type of a reverse iterator for the generic interface for the container. |
| list::generic_value (STL/CLR) | The type of an element for the generic interface for the container. |
| list::iterator (STL/CLR) | The type of an iterator for the controlled sequence. |
| list::reference (STL/CLR) | The type of a reference to an element. |
| list::reverse_iterator (STL/CLR) | The type of a reverse iterator for the controlled sequence. |
| list::size_type (STL/CLR) | The type of a signed distance between two elements. |
| list::value_type (STL/CLR) | The type of an element. |
| Member Function | Description |
|---|---|
| list::assign (STL/CLR) | Replaces all elements. |
| list::back (STL/CLR) | Accesses the last element. |
| list::begin (STL/CLR) | Designates the beginning of the controlled sequence. |
| list::clear (STL/CLR) | Removes all elements. |
| list::empty (STL/CLR) | Tests whether no elements are present. |
| list::end (STL/CLR) | Designates the end of the controlled sequence. |
| list::erase (STL/CLR) | Removes elements at specified positions. |
| list::front (STL/CLR) | Accesses the first element. |
| list::insert (STL/CLR) | Adds elements at a specified position. |
| list::list (STL/CLR) | Constructs a container object. |
| list::merge (STL/CLR) | Merges two ordered controlled sequences. |
| list::pop_back (STL/CLR) | Removes the last element. |
| list::pop_front (STL/CLR) | Removes the first element. |
| list::push_back (STL/CLR) | Adds a new last element. |
| list::push_front (STL/CLR) | Adds a new first element. |
| list::rbegin (STL/CLR) | Designates the beginning of the reversed controlled sequence. |
| list::remove (STL/CLR) | Removes an element with a specified value. |
| list::remove_if (STL/CLR) | Removes elements that pass a specified test. |
| list::rend (STL/CLR) | Designates the end of the reversed controlled sequence. |
| list::resize (STL/CLR) | Changes the number of elements. |
| list::reverse (STL/CLR) | Reverses the controlled sequence. |
| list::size (STL/CLR) | Counts the number of elements. |
| list::sort (STL/CLR) | Orders the controlled sequence. |
| list::splice (STL/CLR) | Restitches links between nodes. |
| list::swap (STL/CLR) | Swaps the contents of two containers. |
| list::to_array (STL/CLR) | Copies the controlled sequence to a new array. |
| list::unique (STL/CLR) | Removes adjacent elements that pass a specified test. |
| Property | Description |
|---|---|
| list::back_item (STL/CLR) | Accesses the last element. |
| list::front_item (STL/CLR) | Accesses the first element. |
| Operator | Description |
|---|---|
| list::operator= (STL/CLR) | Replaces the controlled sequence. |
| operator!= (list) (STL/CLR) | Determines if a list object is not equal to another list object. |
| operator< (list) (STL/CLR) | Determines if a list object is less than another list object. |
| operator<= (list) (STL/CLR) | Determines if a list object is less than or equal to another list object. |
| operator== (list) (STL/CLR) | Determines if a list object is equal to another list object. |
| operator> (list) (STL/CLR) | Determines if a list object is greater than another list object. |
| operator>= (list) (STL/CLR) | Determines if a list object is greater than or equal to another list object. |
Interfaces
| Interface | Description |
|---|---|
| ICloneable | Duplicate an object. |
| IEnumerable | Sequence through elements. |
| ICollection | Maintain group of elements. |
| IEnumerable<T> | Sequence through typed elements. |
| ICollection<T> | Maintain group of typed elements. |
| IList<Value> | Maintain generic container. |
Remarks
The object allocates and frees storage for the sequence it controls as individual nodes in a bidirectional link list. It rearranges elements by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. Thus, a list is a good candidate for the underlying container for template class queue (STL/CLR) or template class stack (STL/CLR).
A list object supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by list::end (STL/CLR)(). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a list iterator to reach the head node, and it will then compare equal to end(). But you cannot dereference the iterator returned by end().
Note that you cannot refer to a list element directly given its numerical position -- that requires a random-access iterator. So a list is not usable as the underlying container for template class priority_queue (STL/CLR).
A list iterator stores a handle to its associated list node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A list iterator remains valid so long as its associated list node is associated with some list. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to end().
Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does not destroy its elements.
Requirements
Header: <cliext/list>
Namespace: cliext
See Also
deque (STL/CLR)
priority_queue (STL/CLR)
queue (STL/CLR)
stack (STL/CLR)
vector (STL/CLR)
STL/CLR Library Reference