23 Containers library [containers]

23.3 Sequence containers [sequences]

23.3.7 Class template forward_list [forward.list]

23.3.7.6 Operations [forward.list.ops]

In this subclause, arguments for a template parameter named Predicate or BinaryPredicate shall meet the corresponding requirements in [algorithms.requirements].
The semantics of i + n, where i is an iterator into the list and n is an integer, are the same as those of next(i, n).
The expression i - n, where i is an iterator into the list and n is an integer, means an iterator j such that j + n == i is true.
For merge and sort, the definitions and requirements in [alg.sorting] apply.
void splice_after(const_iterator position, forward_list& x); void splice_after(const_iterator position, forward_list&& x);
Preconditions: position is before_begin() or is a dereferenceable iterator in the range [begin(), end()).
get_allocator() == x.get_allocator() is true.
addressof(x) != this is true.
Effects: Inserts the contents of x after position, and x becomes empty.
Pointers and references to the moved elements of x now refer to those same elements but as members of *this.
Iterators referring to the moved elements will continue to refer to their elements, but they now behave as iterators into *this, not into x.
Throws: Nothing.
Complexity:
void splice_after(const_iterator position, forward_list& x, const_iterator i); void splice_after(const_iterator position, forward_list&& x, const_iterator i);
Preconditions: position is before_begin() or is a dereferenceable iterator in the range [begin(), end()).
The iterator following i is a dereferenceable iterator in x.
get_allocator() == x.get_allocator() is true.
Effects: Inserts the element following i into *this, following position, and removes it from x.
The result is unchanged if position == i or position == ++i.
Pointers and references to *++i continue to refer to the same element but as a member of *this.
Iterators to *++i continue to refer to the same element, but now behave as iterators into *this, not into x.
Throws: Nothing.
Complexity:
void splice_after(const_iterator position, forward_list& x, const_iterator first, const_iterator last); void splice_after(const_iterator position, forward_list&& x, const_iterator first, const_iterator last);
Preconditions: position is before_begin() or is a dereferenceable iterator in the range [begin(), end()).
(first, last) is a valid range in x, and all iterators in the range (first, last) are dereferenceable.
position is not an iterator in the range (first, last).
get_allocator() == x.get_allocator() is true.
Effects: Inserts elements in the range (first, last) after position and removes the elements from x.
Pointers and references to the moved elements of x now refer to those same elements but as members of *this.
Iterators referring to the moved elements will continue to refer to their elements, but they now behave as iterators into *this, not into x.
Complexity:
size_type remove(const T& value); template<class Predicate> size_type remove_if(Predicate pred);
Effects: Erases all the elements in the list referred to by a list iterator i for which the following conditions hold: *i == value (for remove()), pred(*i) is true (for remove_if()).
Invalidates only the iterators and references to the erased elements.
Returns: The number of elements erased.
Throws: Nothing unless an exception is thrown by the equality comparison or the predicate.
Complexity: Exactly distance(begin(), end()) applications of the corresponding predicate.
Remarks: Stable.
size_type unique(); template<class BinaryPredicate> size_type unique(BinaryPredicate binary_pred);
Let binary_pred be equal_to<>{} for the first overload.
Preconditions: binary_pred is an equivalence relation.
Effects: Erases all but the first element from every consecutive group of equivalent elements.
That is, for a nonempty list, erases all elements referred to by the iterator i in the range [begin() + 1, end()) for which binary_pred(*i, *(i - 1)) is true.
Invalidates only the iterators and references to the erased elements.
Returns: The number of elements erased.
Throws: Nothing unless an exception is thrown by the predicate.
Complexity: If empty() is false, exactly distance(begin(), end()) - 1 applications of the corresponding predicate, otherwise no applications of the predicate.
void merge(forward_list& x); void merge(forward_list&& x); template<class Compare> void merge(forward_list& x, Compare comp); template<class Compare> void merge(forward_list&& x, Compare comp);
Let comp be less<> for the first two overloads.
Preconditions: *this and x are both sorted with respect to the comparator comp, and get_allocator() == x.get_allocator() is true.
Effects: If addressof(x) == this, there are no effects.
Otherwise, merges the two sorted ranges [begin(), end()) and [x.begin(), x.end()).
The result is a range that is sorted with respect to the comparator comp.
Pointers and references to the moved elements of x now refer to those same elements but as members of *this.
Iterators referring to the moved elements will continue to refer to their elements, but they now behave as iterators into *this, not into x.
Complexity: At most distance(begin(), end()) + distance(x.begin(), x.end()) - 1 comparisons if addressof(x) != this; otherwise, no comparisons are performed.
Remarks: Stable ([algorithm.stable]).
If addressof(x) != this, x is empty after the merge.
No elements are copied by this operation.
If an exception is thrown other than by a comparison, there are no effects.
void sort(); template<class Compare> void sort(Compare comp);
Effects: Sorts the list according to the operator< or the comp function object.
If an exception is thrown, the order of the elements in *this is unspecified.
Does not affect the validity of iterators and references.
Complexity: Approximately comparisons, where N is distance(begin(), end()).
Remarks: Stable.
void reverse() noexcept;
Effects: Reverses the order of the elements in the list.
Does not affect the validity of iterators and references.
Complexity: Linear time.