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^.

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

Interfaces

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

Reference

deque (STL/CLR)

priority_queue (STL/CLR)

queue (STL/CLR)

stack (STL/CLR)

vector (STL/CLR)

Other Resources

STL/CLR Library Reference