[forward.list.ops] (original) (raw)

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

constexpr void splice_after(const_iterator position, forward_list& x);constexpr 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 afterposition, 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.

constexpr void splice_after(const_iterator position, forward_list& x, const_iterator i);constexpr 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, followingposition, 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.

constexpr void splice_after(const_iterator position, forward_list& x, const_iterator first, const_iterator last);constexpr 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 ofx 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.

constexpr size_type remove(const T& value);template<class Predicate> constexpr 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.

constexpr size_type unique();template<class BinaryPredicate> constexpr 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.

constexpr void merge(forward_list& x);constexpr void merge(forward_list&& x);template<class Compare> constexpr void merge(forward_list& x, Compare comp);template<class Compare> constexpr 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, andget_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 intox.

Complexity: At most distance(begin(), end()) + distance(x.begin(), x.end()) - 1 comparisons if addressof(x) != this; otherwise, no comparisons are performed.

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.

constexpr void sort();template<class Compare> constexpr 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()).

constexpr void reverse() noexcept;

Effects: Reverses the order of the elements in the list.

Does not affect the validity of iterators and references.