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.

Requirements

Header: <cliext/list>

Namespace: cliext

Declarations

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.

Members

list::assign (STL/CLR)

Replaces all elements.

Syntax

void assign(size_type count, value_type val);  
template<typename InIt>  
    void assign(InIt first, InIt last);  
void assign(System::Collections::Generic::IEnumerable<Value>^ right);  

Parameters

count
Number of elements to insert.

first
Beginning of range to insert.

last
End of range to insert.

right
Enumeration to insert.

val
Value of the element to insert.

Remarks

The first member function replaces the controlled sequence with a repetition of count elements of value val. You use it to fill the container with elements all having the same value.

If InIt is an integer type, the second member function behaves the same as assign((size_type)first, (value_type)last). Otherwise, it replaces the controlled sequence with the sequence [first, last). You use it to make the controlled sequence a copy another sequence.

The third member function replaces the controlled sequence with the sequence designated by the enumerator right. You use it to make the controlled sequence a copy of a sequence described by an enumerator.

Example

// cliext_list_assign.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// assign a repetition of values   
    cliext::list<wchar_t> c2;   
    c2.assign(6, L'x');   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// assign an iterator range   
    cliext::list<wchar_t>::iterator it = c1.end();   
    c2.assign(c1.begin(), --it);   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// assign an enumeration   
    c2.assign(   // NOTE: cast is not needed   
        (System::Collections::Generic::IEnumerable<wchar_t>^)%c1);   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
x x x x x x  
a b  
a b c  

list::back (STL/CLR)

Accesses the last element.

Syntax

reference back();  

Remarks

The member function returns a reference to the last element of the controlled sequence, which must be non-empty. You use it to access the last element, when you know it exists.

Example

// cliext_list_back.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// inspect last item   
    System::Console::WriteLine("back() = {0}", c1.back());   

// alter last item and reinspect   
    c1.back() = L'x';   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
 a b c  
back() = c  
 a b x  

list::back_item (STL/CLR)

Accesses the last element.

Syntax

property value_type back_item;  

Remarks

The property accesses the last element of the controlled sequence, which must be non-empty. You use it to read or write the last element, when you know it exists.

Example

// cliext_list_back_item.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// inspect last item   
    System::Console::WriteLine("back_item = {0}", c1.back_item);   

// alter last item and reinspect   
    c1.back_item = L'x';   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
 a b c  
back_item = c  
 a b x  

list::begin (STL/CLR)

Designates the beginning of the controlled sequence.

Syntax

iterator begin();  

Remarks

The member function returns a random-access iterator that designates the first element of the controlled sequence, or just beyond the end of an empty sequence. You use it to obtain an iterator that designates the current beginning of the controlled sequence, but its status can change if the length of the controlled sequence changes.

Example

// cliext_list_begin.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// inspect first two items   
    cliext::list<wchar_t>::iterator it = c1.begin();   
    System::Console::WriteLine("*begin() = {0}", *it);   
    System::Console::WriteLine("*++begin() = {0}", *++it);   

// alter first two items and reinspect   
    *--it = L'x';   
    *++it = L'y';   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
 a b c  
*begin() = a  
*++begin() = b  
 x y c  

list::clear (STL/CLR)

Removes all elements.

Syntax

void clear();  

Remarks

The member function effectively calls list::erase (STL/CLR)( list::begin (STL/CLR)(), list::end (STL/CLR)()). You use it to ensure that the controlled sequence is empty.

Example

// cliext_list_clear.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// clear the container and reinspect   
    c1.clear();   
    System::Console::WriteLine("size() = {0}", c1.size());   

// add elements and clear again   
    c1.push_back(L'a');   
    c1.push_back(L'b');   

    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    c1.clear();   
    System::Console::WriteLine("size() = {0}", c1.size());   
    return (0);   
    }  
 a b c  
size() = 0  
 a b  
size() = 0  

list::const_iterator (STL/CLR)

The type of a constant iterator for the controlled sequence.

Syntax

typedef T2 const_iterator;  

Remarks

The type describes an object of unspecified type T2 that can serve as a constant random-access iterator for the controlled sequence.

Example

// cliext_list_const_iterator.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    cliext::list<wchar_t>::const_iterator cit = c1.begin();   
    for (; cit != c1.end(); ++cit)   
        System::Console::Write(" {0}", *cit);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  

list::const_reference (STL/CLR)

The type of a constant reference to an element.

Syntax

typedef value_type% const_reference;  

Remarks

The type describes a constant reference to an element.

Example

// cliext_list_const_reference.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    cliext::list<wchar_t>::const_iterator cit = c1.begin();   
    for (; cit != c1.end(); ++cit)   
        {   // get a const reference to an element   
        cliext::list<wchar_t>::const_reference cref = *cit;   
        System::Console::Write(" {0}", cref);   
        }   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  

list::const_reverse_iterator (STL/CLR)

The type of a constant reverse iterator for the controlled sequence..

Syntax

typedef T4 const_reverse_iterator;  

Remarks

The type describes an object of unspecified type T4 that can serve as a constant reverse iterator for the controlled sequence.

Example

// cliext_list_const_reverse_iterator.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c" reversed   
    cliext::list<wchar_t>::const_reverse_iterator crit = c1.rbegin();   
    cliext::list<wchar_t>::const_reverse_iterator crend = c1.rend();   
    for (; crit != crend; ++crit)   
        System::Console::Write(" {0}", *crit);   
    System::Console::WriteLine();   
    return (0);   
    }  
c b a  

list::difference_type (STL/CLR)

The types of a signed distance between two elements.

Syntax

typedef int difference_type;  

Remarks

The type describes a signed element count.

Example

// cliext_list_difference_type.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// compute positive difference   
    cliext::list<wchar_t>::difference_type diff = 0;   
    for (cliext::list<wchar_t>::iterator it = c1.begin();   
        it != c1.end(); ++it) ++diff;   
    System::Console::WriteLine("end()-begin() = {0}", diff);   

// compute negative difference   
    diff = 0;   
    for (cliext::list<wchar_t>::iterator it = c1.end();   
        it != c1.begin(); --it) --diff;   
    System::Console::WriteLine("begin()-end() = {0}", diff);   
    return (0);   
    }  
 a b c  
end()-begin() = 3  
begin()-end() = -3  

list::empty (STL/CLR)

Tests whether no elements are present.

Syntax

bool empty();  

Remarks

The member function returns true for an empty controlled sequence. It is equivalent to list::size (STL/CLR)() == 0. You use it to test whether the list is empty.

Example

// cliext_list_empty.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    System::Console::WriteLine("size() = {0}", c1.size());   
    System::Console::WriteLine("empty() = {0}", c1.empty());   

// clear the container and reinspect   
    c1.clear();   
    System::Console::WriteLine("size() = {0}", c1.size());   
    System::Console::WriteLine("empty() = {0}", c1.empty());   
    return (0);   
    }  
 a b c  
size() = 3  
empty() = False  
size() = 0  
empty() = True  

list::end (STL/CLR)

Designates the end of the controlled sequence.

Syntax

iterator end();  

Remarks

The member function returns a random-access iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes.

Example

// cliext_list_end.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// inspect last two items   
    cliext::list<wchar_t>::iterator it = c1.end();   
    --it;   
    System::Console::WriteLine("*-- --end() = {0}", *--it);   
    System::Console::WriteLine("*--end() = {0}", *++it);   

// alter first two items and reinspect   
    *--it = L'x';   
    *++it = L'y';   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
 a b c  
*-- --end() = b  
*--end() = c  
 a x y  

list::erase (STL/CLR)

Removes elements at specified positions.

Syntax

iterator erase(iterator where);  
iterator erase(iterator first, iterator last);  

Parameters

first
Beginning of range to erase.

last
End of range to erase.

where
Element to erase.

Remarks

The first member function removes the element of the controlled sequence pointed to by where. You use it to remove a single element.

The second member function removes the elements of the controlled sequence in the range [first, last). You use it to remove zero or more contiguous elements.

Both member functions return an iterator that designates the first element remaining beyond any elements removed, or list::end (STL/CLR)() if no such element exists.

When erasing elements, the number of element copies is linear in the number of elements between the end of the erasure and the nearer end of the sequence. (When erasing one or more elements at either end of the sequence, no element copies occur.)

Example

// cliext_list_erase.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// erase an element and reinspect   
    System::Console::WriteLine("erase(begin()) = {0}",   
        *c1.erase(c1.begin()));   

// add elements and display " b c d e"   
    c1.push_back(L'd');   
    c1.push_back(L'e');   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// erase all but end   
    cliext::list<wchar_t>::iterator it = c1.end();   
    System::Console::WriteLine("erase(begin(), end()-1) = {0}",   
        *c1.erase(c1.begin(), --it));   
    System::Console::WriteLine("size() = {0}", c1.size());   
    return (0);   
    }  
 a b c  
erase(begin()) = b  
 b c d e  
erase(begin(), end()-1) = e  
size() = 1  

list::front (STL/CLR)

Accesses the first element.

Syntax

reference front();  

Remarks

The member function returns a reference to the first element of the controlled sequence, which must be non-empty. You use it to read or write the first element, when you know it exists.

Example

// cliext_list_front.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// inspect first item   
    System::Console::WriteLine("front() = {0}", c1.front());   

// alter first item and reinspect   
    c1.front() = L'x';   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
 a b c  
front() = a  
 x b c  

list::front_item (STL/CLR)

Accesses the first element.

Syntax

property value_type front_item;  

Remarks

The property accesses the first element of the controlled sequence, which must be non-empty. You use it to read or write the first element, when you know it exists.

Example

// cliext_list_front_item.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// inspect first item   
    System::Console::WriteLine("front_item = {0}", c1.front_item);   

// alter first item and reinspect   
    c1.front_item = L'x';   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
 a b c  
front_item = a  
 x b c  

list::generic_container (STL/CLR)

The type of the generic interface for the container.

Syntax

typedef Microsoft::VisualC::StlClr::  
    IList<generic_value>  
    generic_container;  

Remarks

The type describes the generic interface for this template container class.

Example

// cliext_list_generic_container.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// construct a generic container   
    cliext::list<wchar_t>::generic_container^ gc1 = %c1;   
    for each (wchar_t elem in gc1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// modify generic and display original   
    gc1->insert(gc1->end(), L'd');   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// modify original and display generic   
    c1.push_back(L'e');   

    System::Collections::IEnumerator^ enum1 =   
        gc1->GetEnumerator();   
    while (enum1->MoveNext())   
        System::Console::Write(" {0}", enum1->Current);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
a b c  
a b c d  
a b c d e  

list::generic_iterator (STL/CLR)

The type of an iterator for use with the generic interface for the container.

Syntax

typedef Microsoft::VisualC::StlClr::Generic::  
    ContainerBidirectionalIterator<generic_value>  
    generic_iterator;  

Remarks

The type describes a generic iterator that can be used with the generic interface for this template container class.

Example

// cliext_list_generic_iterator.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// construct a generic container   
    cliext::list<wchar_t>::generic_container^ gc1 = %c1;   
    for each (wchar_t elem in gc1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// modify generic and display original   
    cliext::list<wchar_t>::generic_iterator gcit = gc1->begin();   
    cliext::list<wchar_t>::generic_value gcval = *gcit;   
    *++gcit = gcval;   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
a b c  
a a c  

list::generic_reverse_iterator (STL/CLR)

The type of a reverse iterator for use with the generic interface for the container.

Syntax

typedef Microsoft::VisualC::StlClr::Generic::  
    ReverseBidirectionalIterator<generic_value> generic_reverse_iterator;  

Remarks

The type describes a generic reverse iterator that can be used with the generic interface for this template container class.

Example

// cliext_list_generic_reverse_iterator.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// construct a generic container   
    cliext::list<wchar_t>::generic_container^ gc1 = %c1;   
    for each (wchar_t elem in gc1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// modify generic and display original   
    cliext::list<wchar_t>::generic_reverse_iterator gcit = gc1->rbegin();   
    cliext::list<wchar_t>::generic_value gcval = *gcit;   
    *++gcit = gcval;   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
a b c  
a c c  

list::generic_value (STL/CLR)

The type of an element for use with the generic interface for the container.

Syntax

typedef GValue generic_value;  

Remarks

The type describes an object of type GValue that describes the stored element value for use with the generic interface for this template container class.

Example

// cliext_list_generic_value.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// construct a generic container   
    cliext::list<wchar_t>::generic_container^ gc1 = %c1;   
    for each (wchar_t elem in gc1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// modify generic and display original   
    cliext::list<wchar_t>::generic_iterator gcit = gc1->begin();   
    cliext::list<wchar_t>::generic_value gcval = *gcit;   
    *++gcit = gcval;   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
a b c  
a a c  

list::insert (STL/CLR)

Adds elements at a specified position.

Syntax

iterator insert(iterator where, value_type val);  
void insert(iterator where, size_type count, value_type val);  
template<typename InIt>  
    void insert(iterator where, InIt first, InIt last);  
void insert(iterator where,  
    System::Collections::Generic::IEnumerable<Value>^ right);  

Parameters

count
Number of elements to insert.

first
Beginning of range to insert.

last
End of range to insert.

right
Enumeration to insert.

val
Value of the element to insert.

where
Where in container to insert before.

Remarks

Each of the member functions inserts, before the element pointed to by where in the controlled sequence, a sequence specified by the remaining operands.

The first member function inserts an element with value val and returns an iterator that designates the newly inserted element. You use it to insert a single element before a place designated by an iterator.

The second member function inserts a repetition of count elements of value val. You use it to insert zero or more contiguous elements which are all copies of the same value.

If InIt is an integer type, the third member function behaves the same as insert(where, (size_type)first, (value_type)last). Otherwise, it inserts the sequence [first, last). You use it to insert zero or more contiguous elements copied from another sequence.

The fourth member function inserts the sequence designated by the right. You use it to insert a sequence described by an enumerator.

When inserting a single element, the number of element copies is linear in the number of elements between the insertion point and the nearer end of the sequence. (When inserting one or more elements at either end of the sequence, no element copies occur.) If InIt is an input iterator, the third member function effectively performs a single insertion for each element in the sequence. Otherwise, when inserting N elements, the number of element copies is linear in N plus the number of elements between the insertion point and the nearer end of the sequence.

Example

// cliext_list_insert.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// insert a single value using iterator   
    cliext::list<wchar_t>::iterator it = c1.begin();   
    System::Console::WriteLine("insert(begin()+1, L'x') = {0}",   
        *c1.insert(++it, L'x'));   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// insert a repetition of values   
    cliext::list<wchar_t> c2;   
    c2.insert(c2.begin(), 2, L'y');   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// insert an iterator range   
    it = c1.end();   
    c2.insert(c2.end(), c1.begin(), --it);   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// insert an enumeration   
    c2.insert(c2.begin(),   // NOTE: cast is not needed   
        (System::Collections::Generic::IEnumerable<wchar_t>^)%c1);   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// insert a single value using index   
    it = c2.begin();   
    ++it, ++it, ++it;   
    c2.insert(it, L'z');   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    return (0);   
    }  
 a b c  
insert(begin()+1, L'x') = x  
 a x b c  
 y y  
 y y a x b  
 a x b c y y a x b  

list::iterator (STL/CLR)

The type of an iterator for the controlled sequence.

Syntax

typedef T1 iterator;  

Remarks

The type describes an object of unspecified type T1 that can serve as a random-access iterator for the controlled sequence.

Example

// cliext_list_iterator.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    cliext::list<wchar_t>::iterator it = c1.begin();   
    for (; it != c1.end(); ++it)   
        System::Console::Write(" {0}", *it);   
    System::Console::WriteLine();   

// alter first element and redisplay   
    it = c1.begin();   
    *it = L'x';   
    for (; it != c1.end(); ++it)   
        System::Console::Write(" {0}", *it);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
x b c  

list::list (STL/CLR)

Constructs a container object.

Syntax

list();  
list(list<Value>% right);  
list(list<Value>^ right);  
explicit list(size_type count);  
list(size_type count, value_type val);  
template<typename InIt>  
    list(InIt first, InIt last);  
list(System::Collections::Generic::IEnumerable<Value>^ right);  

Parameters

count
Number of elements to insert.

first
Beginning of range to insert.

last
End of range to insert.

right
Object or range to insert.

val
Value of the element to insert.

Remarks

The constructor:

list();

initializes the controlled sequence with no elements. You use it to specify an empty initial controlled sequence.

The constructor:

list(list<Value>% right);

initializes the controlled sequence with the sequence [right.begin(), right.end()). You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the list object right.

The constructor:

list(list<Value>^ right);

initializes the controlled sequence with the sequence [right->begin(), right->end()). You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the list object whose handle is right.

The constructor:

explicit list(size_type count);

initializes the controlled sequence with count elements each with value value_type(). You use it to fill the container with elements all having the default value.

The constructor:

list(size_type count, value_type val);

initializes the controlled sequence with count elements each with value val. You use it to fill the container with elements all having the same value.

The constructor:

template<typename InIt>

list(InIt first, InIt last);

initializes the controlled sequence with the sequence [first, last). You use it to make the controlled sequence a copy of another sequence.

The constructor:

list(System::Collections::Generic::IEnumerable<Value>^ right);

initializes the controlled sequence with the sequence designated by the enumerator right. You use it to make the controlled sequence a copy of another sequence described by an enumerator.

Example

// cliext_list_construct.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
// construct an empty container   
    cliext::list<wchar_t> c1;   
    System::Console::WriteLine("size() = {0}", c1.size());   

// construct with a repetition of default values   
    cliext::list<wchar_t> c2(3);   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", (int)elem);   
    System::Console::WriteLine();   

// construct with a repetition of values   
    cliext::list<wchar_t> c3(6, L'x');   
    for each (wchar_t elem in c3)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// construct with an iterator range   
    cliext::list<wchar_t>::iterator it = c3.end();   
    cliext::list<wchar_t> c4(c3.begin(), --it);   
    for each (wchar_t elem in c4)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// construct with an enumeration   
    cliext::list<wchar_t> c5(   // NOTE: cast is not needed   
        (System::Collections::Generic::IEnumerable<wchar_t>^)%c3);   
    for each (wchar_t elem in c5)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// construct by copying another container   
    cliext::list<wchar_t> c7(c3);   
    for each (wchar_t elem in c7)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// construct by copying a container handle   
    cliext::list<wchar_t> c8(%c3);   
    for each (wchar_t elem in c8)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    return (0);   
    }  
size() = 0  
 0 0 0  
 x x x x x x  
 x x x x x  
 x x x x x x  
 x x x x x x  
 x x x x x x  

list::merge (STL/CLR)

Merges two ordered controlled sequences.

Syntax

void merge(list<Value>% right);  
template<typename Pred2>  
    void merge(list<Value>% right, Pred2 pred);  

Parameters

pred
Comparer for element pairs.

right
Container to merge in.

Remarks

The first member function removes all elements from the sequence controlled by right and insert them in the controlled sequence. Both sequences must be previously ordered by operator< -- elements must not decrease in value as you progress through either sequence. The resulting sequence is also ordered by operator<. You use this member function to merge two sequences that increase in value into a sequence that also increases in value.

The second member function behaves the same as the first, except that the sequences are ordered by pred -- pred(X, Y) must be false for any element X that follows element Y in the sequence. You use it to merge two sequences ordered by a predicate function or delegate that you specify.

Both functions perform a stable merge -- no pair of elements in either of the original controlled sequences is reversed in the resulting controlled sequence. Also, if a pair of elements X and Y in the resulting controlled sequence has equivalent ordering -- !(X < Y) && !(X < Y) -- an element from the original controlled sequence appears before an element from the sequence controlled by right.

Example

// cliext_list_merge.cpp   
// compile with: /clr   
#include <cliext/list>   

typedef cliext::list<wchar_t> Mylist;   
int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'c');   
    c1.push_back(L'e');   

// display initial contents " a c e"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    cliext::list<wchar_t> c2;   
    c2.push_back(L'b');   
    c2.push_back(L'd');   
    c2.push_back(L'f');   

// display initial contents " b d f"   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// merge and display   
    cliext::list<wchar_t> c3(c1);   
    c3.merge(c2);   
    for each (wchar_t elem in c3)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    System::Console::WriteLine("c2.size() = {0}", c2.size());   

// sort descending, merge descending, and redisplay   
    c1.sort(cliext::greater<wchar_t>());   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    c3.sort(cliext::greater<wchar_t>());   
    for each (wchar_t elem in c3)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    c3.merge(c1, cliext::greater<wchar_t>());   
    for each (wchar_t elem in c3)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    System::Console::WriteLine("c1.size() = {0}", c1.size());   
    return (0);   
    }  
 a c e  
 b d f  
 a b c d e f  
c2.size() = 0  
 e c a  
 f e d c b a  
 f e e d c c b a a  
c1.size() = 0  

list::operator= (STL/CLR)

Replaces the controlled sequence.

Syntax

list<Value>% operator=(list<Value>% right);  

Parameters

right
Container to copy.

Remarks

The member operator copies right to the object, then returns *this. You use it to replace the controlled sequence with a copy of the controlled sequence in right.

Example

// cliext_list_operator_as.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// assign to a new container   
    cliext::list<wchar_t> c2;   
    c2 = c1;   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
a b c  

list::pop_back (STL/CLR)

Removes the last element.

Syntax

void pop_back();  

Remarks

The member function removes the last element of the controlled sequence, which must be non-empty. You use it to shorten the list by one element at the back.

Example

// cliext_list_pop_back.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// pop an element and redisplay   
    c1.pop_back();   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
a b  

list::pop_front (STL/CLR)

Removes the first element.

Syntax

void pop_front();  

Remarks

The member function removes the first element of the controlled sequence, which must be non-empty. You use it to shorten the list by one element at the front.

Example

// cliext_list_pop_front.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// pop an element and redisplay   
    c1.pop_front();   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
b c  

list::push_back (STL/CLR)

Adds a new last element.

Syntax

void push_back(value_type val);  

Remarks

The member function inserts an element with value val at the end of the controlled sequence. You use it to append another element to the list.

Example

// cliext_list_push_back.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  

list::push_front (STL/CLR)

Adds a new first element.

Syntax

void push_front(value_type val);  

Remarks

The member function inserts an element with value val at the beginning of the controlled sequence. You use it to prepend another element to the list.

Example

// cliext_list_push_front.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_front(L'a');   
    c1.push_front(L'b');   
    c1.push_front(L'c');   

// display contents " c b a"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
c b a  

list::rbegin (STL/CLR)

Designates the beginning of the reversed controlled sequence.

Syntax

reverse_iterator rbegin();  

Remarks

The member function returns a reverse iterator that designates the last element of the controlled sequence, or just beyond the beginning of an empty sequence. Hence, it designates the beginning of the reverse sequence. You use it to obtain an iterator that designates the current beginning of the controlled sequence seen in reverse order, but its status can change if the length of the controlled sequence changes.

Example

// cliext_list_rbegin.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// inspect first two items in reversed sequence   
    cliext::list<wchar_t>::reverse_iterator rit = c1.rbegin();   
    System::Console::WriteLine("*rbegin() = {0}", *rit);   
    System::Console::WriteLine("*++rbegin() = {0}", *++rit);   

// alter first two items and reinspect   
    *--rit = L'x';   
    *++rit = L'y';   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
 a b c  
*rbegin() = c  
*++rbegin() = b  
 a y x  

list::reference (STL/CLR)

The type of a reference to an element.

Syntax

typedef value_type% reference;  

Remarks

The type describes a reference to an element.

Example

// cliext_list_reference.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    cliext::list<wchar_t>::iterator it = c1.begin();   
    for (; it != c1.end(); ++it)   
        {   // get a reference to an element   
        cliext::list<wchar_t>::reference ref = *it;   
        System::Console::Write(" {0}", ref);   
        }   
    System::Console::WriteLine();   

// modify contents " a b c"   
    for (it = c1.begin(); it != c1.end(); ++it)   
        {   // get a reference to an element   
        cliext::list<wchar_t>::reference ref = *it;   

        ref += (wchar_t)(L'A' - L'a');   
        System::Console::Write(" {0}", ref);   
        }   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
A B C  

list::remove (STL/CLR)

Removes an element with a specified value.

Syntax

void remove(value_type val);  

Parameters

val
Value of the element to remove.

Remarks

The member function removes an element in the controlled sequence for which ((System::Object^)val)->Equals((System::Object^)x) is true (if any). You use it to erase an arbitrary element with the specified value.

Example

// cliext_list_remove.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// fail to remove and redisplay   
    c1.remove(L'A');   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();  

// remove and redisplay   
    c1.remove(L'b');   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
a b c  
a c  

list::remove_if (STL/CLR)

Removes elements that pass a specified test.

Syntax

template<typename Pred1>  
    void remove_if(Pred1 pred);  

Parameters

pred
Test for elements to remove.

Remarks

The member function removes from the controlled sequence (erases) every element X for which pred(X) is true. You use it to remove all elements that satisfy a condition you specify as a function or delegate.

Example

// cliext_list_remove_if.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'b');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b b b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// fail to remove and redisplay   
    c1.remove_if(cliext::binder2nd<cliext::equal_to<wchar_t> >(   
        cliext::equal_to<wchar_t>(), L'd'));   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// remove and redisplay   
    c1.remove_if(cliext::binder2nd<cliext::not_equal_to<wchar_t> >(   
        cliext::not_equal_to<wchar_t>(), L'b'));   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b b b c  
a b b b c  
b b b  

list::rend (STL/CLR)

Designates the end of the reversed controlled sequence.

Syntax

reverse_iterator rend();  

Remarks

The member function returns a reverse iterator that points just beyond the beginning of the controlled sequence. Hence, it designates the end of the reverse sequence. You use it to obtain an iterator that designates the current end of the controlled sequence seen in reverse order, but its status can change if the length of the controlled sequence changes.

Example

// cliext_list_rend.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// inspect first two items   
    cliext::list<wchar_t>::reverse_iterator rit = c1.rend();   
    --rit;   
    System::Console::WriteLine("*-- --rend() = {0}", *--rit);   
    System::Console::WriteLine("*--rend() = {0}", *++rit);   

// alter first two items and reinspect   
    *--rit = L'x';   
    *++rit = L'y';   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
 a b c  
*-- --rend() = b  
*--rend() = a  
 y x c  

list::resize (STL/CLR)

Changes the number of elements.

Syntax

void resize(size_type new_size);  
void resize(size_type new_size, value_type val);  

Parameters

new_size
New size of the controlled sequence.

val
Value of the padding element.

Remarks

The member functions both ensure that list::size (STL/CLR)() henceforth returns new_size. If it must make the controlled sequence longer, the first member function appends elements with value value_type(), while the second member function appends elements with value val. To make the controlled sequence shorter, both member functions effectively erase the last element list::size (STL/CLR)() - new_size times. You use it to ensure that the controlled sequence has size new_size, by either trimming or padding the current controlled sequence.

Example

// cliext_list_resize.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
// construct an empty container and pad with default values   
    cliext::list<wchar_t> c1;   
    System::Console::WriteLine("size() = {0}", c1.size());   
    c1.resize(4);   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", (int)elem);   
    System::Console::WriteLine();   

// resize to empty   
    c1.resize(0);   
    System::Console::WriteLine("size() = {0}", c1.size());   

// resize and pad   
    c1.resize(5, L'x');   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
size() = 0  
 0 0 0 0  
size() = 0  
 x x x x x  

list::reverse (STL/CLR)

Reverses the controlled sequence.

Syntax

void reverse();  

Remarks

The member function reverses the order of all elements in the controlled sequence. You use it to reflect a list of elements.

Example

// cliext_list_reverse.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// reverse and redisplay   
    c1.reverse();   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
c b a  

list::reverse_iterator (STL/CLR)

The type of a reverse iterator for the controlled sequence.

Syntax

typedef T3 reverse_iterator;  

Remarks

The type describes an object of unspecified type T3 that can serve as a reverse iterator for the controlled sequence.

Example

// cliext_list_reverse_iterator.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c" reversed   
    cliext::list<wchar_t>::reverse_iterator rit = c1.rbegin();   
    for (; rit != c1.rend(); ++rit)   
        System::Console::Write(" {0}", *rit);   
    System::Console::WriteLine();   

// alter first element and redisplay   
    rit = c1.rbegin();   
    *rit = L'x';   
    for (; rit != c1.rend(); ++rit)   
        System::Console::Write(" {0}", *rit);   
    System::Console::WriteLine();   
    return (0);   
    }  
c b a  
x b a  

list::size (STL/CLR)

Counts the number of elements.

Syntax

size_type size();  

Remarks

The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see list::empty (STL/CLR)().

Example

// cliext_list_size.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    System::Console::WriteLine("size() = {0} starting with 3", c1.size());   

// clear the container and reinspect   
    c1.clear();   
    System::Console::WriteLine("size() = {0} after clearing", c1.size());   

// add elements and clear again   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    System::Console::WriteLine("size() = {0} after adding 2", c1.size());   
    return (0);   
    }  
 a b c  
size() = 3 starting with 3  
size() = 0 after clearing  
size() = 2 after adding 2  

list::size_type (STL/CLR)

The type of a signed distance between two element.

Syntax

typedef int size_type;  

Remarks

The type describes a non-negative element count.

Example

// cliext_list_size_type.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// compute positive difference   
    cliext::list<wchar_t>::size_type diff = 0;   
    for (cliext::list<wchar_t>::iterator it = c1.begin();   
        it != c1.end(); ++it)   
        ++diff;   
    System::Console::WriteLine("end()-begin() = {0}", diff);   
    return (0);   
    }  
 a b c  
end()-begin() = 3  

list::sort (STL/CLR)

Orders the controlled sequence.

Syntax

void sort();  
template<typename Pred2>  
    void sort(Pred2 pred);  

Parameters

pred
Comparer for element pairs.

Remarks

The first member function rearranges the elements in the controlled sequence so that they are ordered by operator< -- elements do not decrease in value as you progress through the sequence. You use this member function to sort the sequence in increasing order.

The second member function behaves the same as the first, except that the sequence is ordered by pred -- pred(X, Y) is false for any element X that follows element Y in the resultant sequence. You use it to sort the sequence in an order that you specify by a predicate function or delegate.

Both functions perform a stable sort -- no pair of elements in the original controlled sequence is reversed in the resulting controlled sequence.

Example

// cliext_list_sort.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// sort descending and redisplay   
    c1.sort(cliext::greater<wchar_t>());   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// sort ascending and redisplay   
    c1.sort();   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
c b a  
a b c  

list::splice (STL/CLR)

Restitch links between nodes.

Syntax

void splice(iterator where, list<Value>% right);  
void splice(iterator where, list<Value>% right,  
    iterator first);  
void splice(iterator where, list<Value>% right,  
    iterator first, iterator last);  

Parameters

first
Beginning of range to splice.

last
End of range to splice.

right
Container to splice from.

where
Where in container to splice before.

Remarks

The first member function inserts the sequence controlled by right before the element in the controlled sequence pointed to by where. It also removes all elements from right. (%right must not equal this.) You use it to splice all of one list into another.

The second member function removes the element pointed to by first in the sequence controlled by right and inserts it before the element in the controlled sequence pointed to by where. (If where == first || where == ++first, no change occurs.) You use it to splice a single element of one list into another.

The third member function inserts the subrange designated by [first, last) from the sequence controlled by right before the element in the controlled sequence pointed to by where. It also removes the original subrange from the sequence controlled by right. (If right == this, the range [first, last) must not include the element pointed to by where.) You use it to splice a subsequence of zero or more elements from one list into another.

Example

// cliext_list_splice.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// splice to a new list   
    cliext::list<wchar_t> c2;   
    c2.splice(c2.begin(), c1);   
    System::Console::WriteLine("c1.size() = {0}", c1.size());   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// return one element   
    c1.splice(c1.end(), c2, c2.begin());   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// return remaining elements   
    c1.splice(c1.begin(), c2, c2.begin(), c2.end());   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    System::Console::WriteLine("c2.size() = {0}", c2.size());   
    return (0);   
    }  
 a b c  
c1.size() = 0  
 a b c  
 a  
 b c  
 b c a  
c2.size() = 0  

list::swap (STL/CLR)

Swaps the contents of two containers.

Syntax

void swap(list<Value>% right);  

Parameters

right
Container to swap contents with.

Remarks

The member function swaps the controlled sequences between *this and right. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers.

Example

// cliext_list_swap.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// construct another container with repetition of values   
    cliext::list<wchar_t> c2(5, L'x');   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// swap and redisplay   
    c1.swap(c2);   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  
x x x x x  
x x x x x  
a b c  

list::to_array (STL/CLR)

Copies the controlled sequence to a new array.

Syntax

cli::array<Value>^ to_array();  

Remarks

The member function returns an array containing the controlled sequence. You use it to obtain a copy of the controlled sequence in array form.

Example

// cliext_list_to_array.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// copy the container and modify it   
    cli::array<wchar_t>^ a1 = c1.to_array();   

    c1.push_back(L'd');   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// display the earlier array copy   
    for each (wchar_t elem in a1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c d  
a b c  

list::unique (STL/CLR)

Removes adjacent elements that pass a specified test.

Syntax

void unique();  
template<typename Pred2>  
    void unique(Pred2 pred);  

Parameters

pred
Comparer for element pairs.

Remarks

The first member function removes from the controlled sequence (erases) every element that compares equal to its preceding element -- if element X precedes element Y and X == Y, the member function removes Y. You use it to remove all but one copy of every subsequence of adjacent elements that compare equal. Note that if the controlled sequence is ordered, such as by calling list::sort (STL/CLR)(), the member function leaves only elements with unique values. (Hence the name).

The second member function behaves the same as the first, except that it removes each element Y following an element X for which pred(X, Y). You use it to remove all but one copy of every subsequence of adjacent elements that satisfy a predicate function or delegate that you specify. Note that if the controlled sequence is ordered, such as by calling sort(pred), the member function leaves only elements that do not have equivalent ordering with any other elements.

Example

// cliext_list_unique.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display initial contents " a a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// display contents after unique   
    cliext::list<wchar_t> c2(c1);   
    c2.unique();   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// display contents after unique(not_equal_to)   
    c2 = c1;   
    c2.unique(cliext::not_equal_to<wchar_t>());   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   
    return (0);   
    }  
a a b c  
a b c  
a a  

list::value_type (STL/CLR)

The type of an element.

Syntax

typedef Value value_type;  

Remarks

The type is a synonym for the template parameter Value.

Example

// cliext_list_value_type.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c" using value_type   
    for (cliext::list<wchar_t>::iterator it = c1.begin();   
        it != c1.end(); ++it)   
        {   // store element in value_type object   
        cliext::list<wchar_t>::value_type val = *it;   

        System::Console::Write(" {0}", val);   
        }   
    System::Console::WriteLine();   
    return (0);   
    }  
a b c  

operator!= (list) (STL/CLR)

List not equal comparison.

Syntax

template<typename Value>  
    bool operator!=(list<Value>% left,  
        list<Value>% right);  

Parameters

left
Left container to compare.

right
Right container to compare.

Remarks

The operator function returns !(left == right). You use it to test whether left is not ordered the same as right when the two lists are compared element by element.

Example

// cliext_list_operator_ne.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// assign to a new container   
    cliext::list<wchar_t> c2;   
    c2.push_back(L'a');   
    c2.push_back(L'b');   
    c2.push_back(L'd');   

// display contents " a b d"   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    System::Console::WriteLine("[a b c] != [a b c] is {0}",   
        c1 != c1);   
    System::Console::WriteLine("[a b c] != [a b d] is {0}",   
        c1 != c2);   
    return (0);   
    }  
 a b c  
 a b d  
[a b c] != [a b c] is False  
[a b c] != [a b d] is True  

operator< (list) (STL/CLR)

List less than comparison.

Syntax

template<typename Value>  
    bool operator<(list<Value>% left,  
        list<Value>% right);  

Parameters

left
Left container to compare.

right
Right container to compare.

Remarks

The operator function returns true if, for the lowest position i for which !(right[i] < left[i]) it is also true that left[i] < right[i]. Otherwise, it returns left->size() < right->size() You use it to test whether left is ordered before right when the two lists are compared element by element.

Example

// cliext_list_operator_lt.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// assign to a new container   
    cliext::list<wchar_t> c2;   
    c2.push_back(L'a');   
    c2.push_back(L'b');   
    c2.push_back(L'd');   

// display contents " a b d"   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    System::Console::WriteLine("[a b c] < [a b c] is {0}",   
        c1 < c1);   
    System::Console::WriteLine("[a b c] < [a b d] is {0}",   
        c1 < c2);   
    return (0);   
    }  
 a b c  
 a b d  
[a b c] < [a b c] is False  
[a b c] < [a b d] is True  

operator<= (list) (STL/CLR)

List less than or equal comparison.

Syntax

template<typename Value>  
    bool operator<=(list<Value>% left,  
        list<Value>% right);  

Parameters

left
Left container to compare.

right
Right container to compare.

Remarks

The operator function returns !(right < left). You use it to test whether left is not ordered after right when the two lists are compared element by element.

Example

// cliext_list_operator_le.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// assign to a new container   
    cliext::list<wchar_t> c2;   
    c2.push_back(L'a');   
    c2.push_back(L'b');   
    c2.push_back(L'd');   

// display contents " a b d"   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    System::Console::WriteLine("[a b c] <= [a b c] is {0}",   
        c1 <= c1);   
    System::Console::WriteLine("[a b d] <= [a b c] is {0}",   
        c2 <= c1);   
    return (0);   
    }  
 a b c  
 a b d  
[a b c] <= [a b c] is True  
[a b d] <= [a b c] is False  

operator== (list) (STL/CLR)

List equal comparison.

Syntax

template<typename Value>  
    bool operator==(list<Value>% left,  
        list<Value>% right);  

Parameters

left
Left container to compare.

right
Right container to compare.

Remarks

The operator function returns true only if the sequences controlled by left and right have the same length and, for each position i, left[i] == right[i]. You use it to test whether left is ordered the same as right when the two lists are compared element by element.

Example

// cliext_list_operator_eq.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// assign to a new container   
    cliext::list<wchar_t> c2;   
    c2.push_back(L'a');   
    c2.push_back(L'b');   
    c2.push_back(L'd');   

// display contents " a b d"   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    System::Console::WriteLine("[a b c] == [a b c] is {0}",   
        c1 == c1);   
    System::Console::WriteLine("[a b c] == [a b d] is {0}",   
        c1 == c2);   
    return (0);   
    }  
 a b c  
 a b d  
[a b c] == [a b c] is True  
[a b c] == [a b d] is False  

operator> (list) (STL/CLR)

List greater than comparison.

Syntax

template<typename Value>  
    bool operator>(list<Value>% left,  
        list<Value>% right);  

Parameters

left
Left container to compare.

right
Right container to compare.

Remarks

The operator function returns right < left. You use it to test whether left is ordered after right when the two lists are compared element by element.

Example

// cliext_list_operator_gt.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// assign to a new container   
    cliext::list<wchar_t> c2;   
    c2.push_back(L'a');   
    c2.push_back(L'b');   
    c2.push_back(L'd');   

// display contents " a b d"   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    System::Console::WriteLine("[a b c] > [a b c] is {0}",   
        c1 > c1);   
    System::Console::WriteLine("[a b d] > [a b c] is {0}",   
        c2 > c1);   
    return (0);   
    }  
 a b c  
 a b d  
[a b c] > [a b c] is False  
[a b d] > [a b c] is True  

operator>= (list) (STL/CLR)

List greater than or equal comparison.

Syntax

template<typename Value>  
    bool operator>=(list<Value>% left,  
        list<Value>% right);  

Parameters

left
Left container to compare.

right
Right container to compare.

Remarks

The operator function returns !(left < right). You use it to test whether left is not ordered before right when the two lists are compared element by element.

Example

// cliext_list_operator_ge.cpp   
// compile with: /clr   
#include <cliext/list>   

int main()   
    {   
    cliext::list<wchar_t> c1;   
    c1.push_back(L'a');   
    c1.push_back(L'b');   
    c1.push_back(L'c');   

// display contents " a b c"   
    for each (wchar_t elem in c1)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

// assign to a new container   
    cliext::list<wchar_t> c2;   
    c2.push_back(L'a');   
    c2.push_back(L'b');   
    c2.push_back(L'd');   

// display contents " a b d"   
    for each (wchar_t elem in c2)   
        System::Console::Write(" {0}", elem);   
    System::Console::WriteLine();   

    System::Console::WriteLine("[a b c] >= [a b c] is {0}",   
        c1 >= c1);   
    System::Console::WriteLine("[a b c] >= [a b d] is {0}",   
        c1 >= c2);   
    return (0);   
    }  
 a b c  
 a b d  
[a b c] >= [a b c] is True  
[a b c] >= [a b d] is False