forward_list Class

Article
07/11/2012

Describes an object that controls a varying-length sequence of elements. The sequence is stored as a singly-linked list of nodes, each containing a member of type Type.

template<class Type, class Allocator = allocator<Type> >
    class forward_list {
public:
    typedef Allocator allocator_type;
    typedef typename Allocator::pointer pointer;
    typedef typename Allocator::const_pointer
        const_pointer;
    typedef typename Allocator::reference reference;
    typedef typename Allocator::const_reference const_reference;
    typedef typename Allocator::value_type value_type;
    typedef typename Allocator::size_type size_type;
    typedef typename Allocator::difference_type difference_type;

    typedef T0 iterator;
    typedef T1 const_iterator;

    forward_list();
    explicit forward_list(const Allocator& _Alloc);
    explicit forward_list(size_type _Count);
    forward_list(
        size_type _Count, 
        const Type& _Val
    );
    forward_list(
        size_type _Count, 
        const Type& _Val, 
        const Allocator& _Alloc
    );
    forward_list(const forward_list& _Right);
    template<class InputIterator>
        forward_list (
            InputIterator _First, 
            InputIterator _Last
);
    template<class InputIterator>
        forward_list (
            InputIterator _First,
            InputIterator _Last, 
            const Allocator& _Alloc
);

    forward_list (initializer_list<Type> _Init)
    forward_list (
        initializer_list<Type> _Init,
        const Allocator& _Alloc
);
    forward_list (forward_list&& _Right);
 
    ~forward_list();

    forward_list& operator= (const forward_list& _Right);
    forward_list& operator= (forward_list&& _Right);

    iterator before_begin ();
    const_iterator before_begin () const;
    iterator begin ();
    const_iterator begin () const;
    iterator end ();
    const_iterator end () const;

    const_iterator cbefore_begin () const;
    const_iterator cbegin () const;
    const_iterator cend () const;

    void resize (size_type _Count);
    void resize (
        size_type _Count, 
        const Type& _Val
    );
    size_type max_size () const;
    bool empty () const;

    Alloc get_allocator () const;

    reference front ();
    const_reference front () const;

    void push_front (const Type& _Val);
    void push_front (Type&& _Val);
    template<class _Type>
        void emplace_front(_Type&& _Val);
    void pop_front ();

    template<class InputIterator>
        void assign (
            InputIterator _First, 
            InputIterator _Last
);
    void assign (
        size_type _Count, 
        const Type& _Val
    );

    iterator insert_after (
        const_iterator _Pos, 
        const Type& _Val
    );
    void insert_after (
        const_iterator _Pos, 
        size_type _Count, 
        const Type& _Val
    );
    template<class InputIterator >
        void insert_after (
            const_iterator _Pos, 
            InputIterator _First, 
            InputIterator _Last
        );
    void insert_after (
        const iterator _Pos, 
        initializer_list<Type> _Init
)
    iterator insert_after (
        const_iterator _Pos, 
        Type&& _Val
    );
    template<class Type>
        iterator emplace_after(const_iterator _Where, Type&& _Val);
    iterator erase_after (const_iterator _Pos);
    iterator erase_after (
        const_iterator _First, 
        const_iterator _Last
    );
    void clear ();

    void swap (forward_list& _Right);

    void splice_after (
        const_iterator _Pos, 
        forward_list& _List
    );
    void splice_after (
        const_iterator _Pos, 
        forward_list& _List, 
        iterator _First
    );
    void splice_after (
        const_iterator _Pos, 
        forward_list& _List, 
        iterator _First,
        iterator _Last);

    void remove (const Type& _Val);
    template<class Predicate>
        void remove_if (Predicate _Pred);
    void unique ();
    template<class BinaryPredicate>
        void unique (BinaryPredicate _Comp);

    void merge (forward_list& _List);
    template<class BinaryPredicate>
        void merge (
            forward_list& _List, 
            BinaryPredicate _Comp
);
    void sort ();
    template<class BinaryPredicate>
        void sort (BinaryPredicate _Comp);
    void reverse ();
};

Parameters

Parameter	Description
Type	The element data type to be stored in the forward_list.
_Alloc	The stored allocator object that encapsulates details about the forward_list allocation and deallocation of memory. This parameter is optional. The default value is allocator<Type>.
_Count	The number of elements in a forward_list.
_Val	The element to add to the forward_list.
_Right	The list to incorporate into the forward_list.
_Pos	The iterator indicating a location in the forward_list.
_First	The iterator indicating the start location for a range of elements in the forward_list.
_Last	The iterator indicating the end location for a range of elements in the forward_list.
_Init	The initializer list
_List	The forward_list to merge, splice, or assign from.
_Comp	The comparison function.

Remarks

A forward_list object allocates and frees storage for the sequence it controls through a stored object of class Allocator that is based on allocator Class (commonly known as std::allocator). For more information, see Allocators. An allocator object must have the same external interface as an object of template class allocator.

Note

The stored allocator object is not copied when the container object is assigned.

Iterators, pointers and references might become invalid when elements of their controlled sequence are erased through forward_list. Insertions and splices performed on the controlled sequence through forward_list do not invalidate iterators.

Additions to the controlled sequence might occur by calls to forward_list::insert_after, which is the only member function that calls the constructor Type(const _Type&). forward_list might also call move constructors. If such an expression throws an exception, the container object inserts no new elements and rethrows the exception. Thus, an object of template class forward_list is left in a known state when such exceptions occur.

Constructors

forward_list

Constructs an object of type forward_list.

Typedefs

allocator_type	A type that represents the allocator class for a forward list object.
const_iterator	A type that provides a constant iterator for the forward list.
const_pointer	A type that provides a pointer to a const element in a forward list.
const_reference	A type that provides a constant reference to an element in the forward list.
difference_type	A signed integer type that can be used to represent the number of elements of a forward list in a range between elements pointed to by iterators.
iterator	A type that provides an iterator for the forward list.
pointer	A type that provides a pointer to an element in the forward list.
reference	A type that provides a reference to an element in the forward list.
size_type	A type that represents the unsigned distance between two elements.
value_type	A type that represents the type of element stored in a forward list.

Member Functions

assign	Erases elements from a forward list and copies a new set of elements to a target forward list.
before_begin	Returns an iterator addressing the position before the first element in a forward list.
begin	Returns an iterator addressing the first element in a forward list.
cbefore_begin	Returns a const iterator addressing the position before the first element in a forward list.
cbegin	Returns a const iterator addressing the first element in a forward list.
cend	Returns a const iterator that addresses the location succeeding the last element in a forward list.
clear	Erases all the elements of a forward list.
emplace_after	Move constructs a new element after a specified position.
emplace_front	Adds an element constructed in place to the beginning of the list.
empty	Tests whether a forward list is empty.
end	Returns an iterator that addresses the location succeeding the last element in a forward list.
erase_after	Removes elements from the forward list after a specified position.
front	Returns a reference to the first element in a forward list.
get_allocator	Returns a copy of the allocator object used to construct a forward list.
insert_after	Adds elements to the forward list after a specified position.
max_size	Returns the maximum length of a forward list.
merge	Removes the elements from the argument list, inserts them into the target forward list, and orders the new, combined set of elements in ascending order or in some other specified order.
pop_front	Deletes the element at the beginning of a forward list.
push_front	Adds an element to the beginning of a forward list.
remove	Erases elements in a forward list that matches a specified value.
remove_if	Erases elements from a forward list for which a specified predicate is satisfied.
resize	Specifies a new size for a forward list.
reverse	Reverses the order in which the elements occur in a forward list.
sort	Arranges the elements in ascending order or with an order specified by a predicate.
splice_after	Restitches links between nodes.
swap	Exchanges the elements of two forward lists.
unique	Removes adjacent elements that pass a specified test.

Operators

operator=

Replaces the elements of the forward list with a copy of another forward list.

Requirements

Header: <forward_list>

Namespace: std

Share via

forward_list Class

Parameters

Remarks

Constructors

Typedefs

Member Functions

Operators

Requirements

See Also

Reference

Other Resources

Additional resources