std::bidirectional_iterator - cppreference.com (original) (raw)

The concept bidirectional_iterator refines forward_iterator by adding the ability to move an iterator backward.

[edit] Iterator concept determination

Definition of this concept is specified via an exposition-only alias template /*ITER_CONCEPT*/.

In order to determine /*ITER_CONCEPT*/, let ITER_TRAITS denote I if the specialization std::iterator_traits is generated from the primary template, or std::iterator_traits otherwise:

If ITER_TRAITS::iterator_concept is valid and names a type, /*ITER_CONCEPT*/ denotes the type.
Otherwise, if ITER_TRAITS::iterator_category is valid and names a type, /*ITER_CONCEPT*/ denotes the type.
Otherwise, if std::iterator_traits is generated from the primary template, /*ITER_CONCEPT*/ denotes std::random_access_iterator_tag.
(That is, std::derived_from</*ITER_CONCEPT*/, std::bidirectional_iterator_tag> is assumed to be true.)
Otherwise, /*ITER_CONCEPT*/ does not denote a type and results in a substitution failure.

[edit] Semantic requirements

A bidirectional iterator r is said to be decrementable if and only if there exists some s such that ++s == r.

std::bidirectional_iterator is modeled only if all the concepts it subsumes are modeled, and given two objects a and b of type I:

If a is decrementable, a is in the domain of the expressions --a and a--.
Pre-decrement yields an lvalue that refers to the operand: std::addressof(--a) == std::addressof(a).
Post-decrement yields the previous value of the operand: if bool(a == b), then bool(a-- == b).
Post-decrement and pre-decrement perform the same modification on its operand: If bool(a == b), then after evaluating both a-- and --b, bool(a == b) still holds.
Increment and decrement are inverses of each other:
If a is incrementable and bool(a == b), then bool(--(++a) == b).
If a is decrementable and bool(a == b), then bool(++(--a) == b).

[edit] Equality preservation

Expressions declared in requires expressions of the standard library concepts are required to be equality-preserving (except where stated otherwise).

[edit] Notes

Unlike the LegacyBidirectionalIterator requirements, the bidirectional_iterator concept does not require dereference to return an lvalue.

[edit] Example

A minimum bidirectional iterator.

#include #include class SimpleBidiIterator { public: using difference_type = std::ptrdiff_t; using value_type = int; SimpleBidiIterator(); SimpleBidiIterator(const SimpleBidiIterator&); SimpleBidiIterator& operator=(const SimpleBidiIterator&); int operator*() const; SimpleBidiIterator& operator++(); SimpleBidiIterator operator++(int) { auto tmp = *this; ++*this; return tmp; } SimpleBidiIterator& operator--(); SimpleBidiIterator operator--(int) { auto tmp = *this; --*this; return tmp; } bool operator==(const SimpleBidiIterator&) const; }; static_assert(std::bidirectional_iterator);