Namespaces
Variants
Views
Actions

C++ named requirements: LegacyIterator

From cppreference.com
< cpp‎ | named req
 
C++
 
C++ named requirements
 

The LegacyIterator requirements describe types that can be used to identify and traverse the elements of a container.

LegacyIterator is the base set of requirements used by other iterator types: LegacyInputIterator, LegacyOutputIterator, LegacyForwardIterator, LegacyBidirectionalIterator, and LegacyRandomAccessIterator. Iterators can be thought of as an abstraction of pointers.

All the categories of iterators require only those functions that are realizable for a given category in constant time (amortized). Therefore, requirement tables and concept definitions(since C++20) for the iterators do not specify complexity.

Contents

[edit] Requirements

The type It satisfies LegacyIterator if

  • The type It satisfies CopyConstructible, and
  • The type It satisfies CopyAssignable, and
  • The type It satisfies Destructible, and
  • The type It satisfies Swappable, and
  • std::iterator_traits<It> has member typedefs: value_type,(until C++20) difference_type, reference, pointer, and iterator_category, and
  • Given r, an lvalue of type It, the following expressions must be valid and have their specified effects:
Expression Return Type Precondition
*r unspecified r is dereferenceable
++r It& r is incrementable (the behavior of the expression ++r is defined)

Concept

For the definition of std::iterator_traits, the following exposition-only concept is defined.

template<class I>

concept __LegacyIterator =
    requires(I i)
    {
        {   *i } -> __Referenceable;
        {  ++i } -> std::same_as<I&>;
        { *i++ } -> __Referenceable;

    } && std::copyable<I>;

where the exposition-only concept __Referenceable<T> is satisfied if and only if T& is a valid type (in particular, T must not be void).

(since C++20)

[edit] Notes

Note on terminology: The following table shows the names used on this site and corresponding C++ Standard names (with the same meaning). The "Legacy" (and “Cpp17”) prefix emphasizes compatibility with pre-C++20 standards and is used to distinguish these requirements from the new iterator concepts introduced with C++20.

cppreference names C++ Standard names C++20 iterator concepts
LegacyIterator Cpp17Iterator input_or_output_iterator
LegacyInputIterator Cpp17InputIterator input_iterator
LegacyOutputIterator Cpp17OutputIterator output_iterator
LegacyForwardIterator Cpp17ForwardIterator forward_iterator
LegacyBidirectionalIterator Cpp17BidirectionalIterator bidirectional_iterator
LegacyRandomAccessIterator Cpp17RandomAccessIterator random_access_iterator
LegacyContiguousIterator[1] contiguous_iterator
  1. ↑ LegacyContiguousIterator category was only formally specified in C++17, but the iterators of std::vector, std::basic_string, std::array, and std::valarray, as well as pointers into C arrays are often treated as a separate category in pre-C++17 code.

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
LWG 2437 C++98 *r is required to be reference not required for output iterators
LWG 3420 C++20 the exposition-only concept checks copyable first copyable is checked only if the requires-expression yields true

[edit] See also

(C++20)
 specifies that objects of a type can be incremented and dereferenced
(concept) [edit]
Iterator library provides definitions for iterators, iterator traits, adaptors, and utility functions
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/named_req/Iterator&oldid=182604"