24 Ranges library [ranges]

24.6 Range factories [range.factories]

This subclause defines range factories, which are utilities to create a view.

Range factories are declared in namespace std::ranges::views.

24.6.1 Empty view [range.empty]

24.6.1.1 Overview [range.empty.overview]

empty_view produces a view of no elements of a particular type.

empty_view<int> e;
static_assert(ranges::empty(e));
static_assert(0 == e.size());

— end example

]

24.6.1.2 Class template empty_view [range.empty.view]

namespace std::ranges {
  template<class T>
    requires is_object_v<T>
  class empty_view : public view_interface<empty_view<T>> {
  public:
    static constexpr T* begin() noexcept { return nullptr; }
    static constexpr T* end() noexcept { return nullptr; }
    static constexpr T* data() noexcept { return nullptr; }
    static constexpr size_t size() noexcept { return 0; }
    static constexpr bool empty() noexcept { return true; }
  };
}

24.6.2 Single view [range.single]

24.6.2.1 Overview [range.single.overview]

single_view produces a view that contains exactly one element of a specified value.

The name views::single denotes a customization point object ([customization.point.object]).

Given a subexpression E, the expression views::single(E) is expression-equivalent to single_view{E}.

[ Example

single_view s{4};
for (int i : s)
  cout << i;        // prints 4

— end example

]

24.6.2.2 Class template single_view [range.single.view]

namespace std::ranges {
  template<copy_constructible T>
    requires is_object_v<T>
  class single_view : public view_interface<single_view<T>> {
  private:
    semiregular-box<T> value_;      // exposition only (see [range.semi.wrap])
  public:
    single_view() = default;
    constexpr explicit single_view(const T& t);
    constexpr explicit single_view(T&& t);
    template<class... Args>
      requires constructible_from<T, Args...>
    constexpr single_view(in_place_t, Args&&... args);

    constexpr T* begin() noexcept;
    constexpr const T* begin() const noexcept;
    constexpr T* end() noexcept;
    constexpr const T* end() const noexcept;
    static constexpr size_t size() noexcept;
    constexpr T* data() noexcept;
    constexpr const T* data() const noexcept;
  };
}

🔗

constexpr explicit single_view(const T& t);

Effects: Initializes value_ with t.

🔗

constexpr explicit single_view(T&& t);

Effects: Initializes value_ with std::move(t).

🔗

template<class... Args>
constexpr single_view(in_place_t, Args&&... args);

Effects: Initializes value_ as if by value_{in_place, std::forward<Args>(args)...}.

🔗

constexpr T* begin() noexcept;
constexpr const T* begin() const noexcept;

Effects: Equivalent to: return data();

🔗

constexpr T* end() noexcept;
constexpr const T* end() const noexcept;

Effects: Equivalent to: return data() + 1;

🔗

static constexpr size_t size() noexcept;

Effects: Equivalent to: return 1;

🔗

constexpr T* data() noexcept;
constexpr const T* data() const noexcept;

Effects: Equivalent to: return value_.operator->();

24.6.3 Iota view [range.iota]

24.6.3.1 Overview [range.iota.overview]

iota_view generates a sequence of elements by repeatedly incrementing an initial value.

The name views::iota denotes a customization point object ([customization.point.object]).

Given subexpressions E and F, the expressions views::iota(E) and views::iota(E, F) are expression-equivalent to iota_view{E} and iota_view{E, F}, respectively.

[ Example

for (int i : iota_view{1, 10})
  cout << i << ' '; // prints: 1 2 3 4 5 6 7 8 9

— end example

]

24.6.3.2 Class template iota_view [range.iota.view]

namespace std::ranges {
  template<class I>
    concept decrementable =     // exposition only
      see below;
  template<class I>
    concept advanceable =       // exposition only
      see below;

  template<weakly_incrementable W, semiregular Bound = unreachable_sentinel_t>
    requires weakly-equality-comparable-with<W, Bound> && semiregular<W>
  class iota_view : public view_interface<iota_view<W, Bound>> {
  private:
    // [range.iota.iterator], class iota_view::iterator
    struct iterator;            // exposition only
    // [range.iota.sentinel], class iota_view::sentinel
    struct sentinel;            // exposition only
    W value_ = W();             // exposition only
    Bound bound_ = Bound();     // exposition only
  public:
    iota_view() = default;
    constexpr explicit iota_view(W value);
    constexpr iota_view(type_identity_t<W> value,
                        type_identity_t<Bound> bound);
    constexpr iota_view(iterator first, sentinel last) : iota_view(*first, last.bound_) {}

    constexpr iterator begin() const;
    constexpr auto end() const;
    constexpr iterator end() const requires same_as<W, Bound>;

    constexpr auto size() const requires see below;
  };

  template<class W, class Bound>
    requires (!is-integer-like<W> || !is-integer-like<Bound> ||
              (is-signed-integer-like<W> == is-signed-integer-like<Bound>))
    iota_view(W, Bound) -> iota_view<W, Bound>;
}

Let IOTA-DIFF-T(W) be defined as follows:

(1.1)
If W is not an integral type, or if it is an integral type and sizeof(iter_difference_t<W>) is greater than sizeof(W), then IOTA-DIFF-T(W) denotes iter_difference_t<W>.
(1.2)
Otherwise, IOTA-DIFF-T(W) is a signed integer type of width greater than the width of W if such a type exists.
(1.3)
Otherwise, IOTA-DIFF-T(W) is an unspecified signed-integer-like type ([iterator.concept.winc]) of width not less than the width of W.
[ Note
: It is unspecified whether this type satisfies weakly_incrementable. — end note
]

The exposition-only decrementable concept is equivalent to:

🔗

template<class I>
  concept decrementable =
    incrementable<I> && requires(I i) {
      { --i } -> same_as<I&>;
      { i-- } -> same_as<I>;
    };

When an object is in the domain of both pre- and post-decrement, the object is said to be decrementable.

Let a and b be equal objects of type I.

I models decrementable only if

(4.1)
If a and b are decrementable, then the following are all true:
- (4.1.1)
  addressof(--a) == addressof(a)
- (4.1.2)
  bool(a-- == b)
- (4.1.3)
  bool(((void)a--, a) == --b)
- (4.1.4)
  bool(++(--a) == b).
(4.2)
If a and b are incrementable, then bool(--(++a) == b).

The exposition-only advanceable concept is equivalent to:

🔗

template<class I>
  concept advanceable =
    decrementable<I> && totally_ordered<I> &&
    requires(I i, const I j, const IOTA-DIFF-T(I) n) {
      { i += n } -> same_as<I&>;
      { i -= n } -> same_as<I&>;
      I(j + n);
      I(n + j);
      I(j - n);
      { j - j } -> convertible_to<IOTA-DIFF-T(I)>;
    };

Let D be IOTA-DIFF-T(I).

Let a and b be objects of type I such that b is reachable from a after n applications of ++a, for some value n of type D.

I models advanceable only if

(a += n) is equal to b.
addressof(a += n) is equal to addressof(a).
I(a + n) is equal to (a += n).
For any two positive values x and y of type D, if I(a + D(x + y)) is well-defined, then I(a + D(x + y)) is equal to I(I(a + x) + y).
I(a + D(0)) is equal to a.
If I(a + D(n - 1)) is well-defined, then I(a + n) is equal to [](I c) { return ++c; }(I(a + D(n - 1))).
(b += -n) is equal to a.
(b -= n) is equal to a.
addressof(b -= n) is equal to addressof(b).
I(b - n) is equal to (b -= n).
D(b - a) is equal to n.
D(a - b) is equal to D(-n).
bool(a <= b) is true.

🔗

constexpr explicit iota_view(W value);

Preconditions: Bound denotes unreachable_sentinel_t or Bound() is reachable from value.

Effects: Initializes value_ with value.

🔗

constexpr iota_view(type_identity_t<W> value, type_identity_t<Bound> bound);

Preconditions: Bound denotes unreachable_sentinel_t or bound is reachable from value.

When W and Bound model totally_ordered_with, then bool(value <= bound) is true.

Effects: Initializes value_ with value and bound_ with bound.

🔗

constexpr iterator begin() const;

Effects: Equivalent to: return iterator{value_};

🔗

constexpr auto end() const;

Effects: Equivalent to:

if constexpr (same_as<Bound, unreachable_sentinel_t>)
  return unreachable_sentinel;
else
  return sentinel{bound_};

🔗

constexpr iterator end() const requires same_as<W, Bound>;

Effects: Equivalent to: return iterator{bound_};

🔗

constexpr auto size() const requires see below;

Effects: Equivalent to:

if constexpr (is-integer-like<W> && is-integer-like<Bound>)
  return (value_ < 0)
    ? ((bound_ < 0)
      ? to-unsigned-like(-value_) - to-unsigned-like(-bound_)
      : to-unsigned-like(bound_) + to-unsigned-like(-value_))
    : to-unsigned-like(bound_) - to-unsigned-like(value_);
else
  return to-unsigned-like(bound_ - value_);

Remarks: The expression in the requires-clause is equivalent to

(same_as<W, Bound> && advanceable<W>) || (integral<W> && integral<Bound>) ||
  sized_sentinel_for<Bound, W>

24.6.3.3 Class iota_view::iterator [range.iota.iterator]

namespace std::ranges {
  template<weakly_incrementable W, semiregular Bound>
    requires weakly-equality-comparable-with<W, Bound>
  struct iota_view<W, Bound>::iterator {
  private:
    W value_ = W();             // exposition only
  public:
    using iterator_concept = see below;
    using iterator_category = input_iterator_tag;
    using value_type = W;
    using difference_type = IOTA-DIFF-T(W);

    iterator() = default;
    constexpr explicit iterator(W value);

    constexpr W operator*() const noexcept(is_nothrow_copy_constructible_v<W>);

    constexpr iterator& operator++();
    constexpr void operator++(int);
    constexpr iterator operator++(int) requires incrementable<W>;

    constexpr iterator& operator--() requires decrementable<W>;
    constexpr iterator operator--(int) requires decrementable<W>;

    constexpr iterator& operator+=(difference_type n)
      requires advanceable<W>;
    constexpr iterator& operator-=(difference_type n)
      requires advanceable<W>;
    constexpr W operator[](difference_type n) const
      requires advanceable<W>;

    friend constexpr bool operator==(const iterator& x, const iterator& y)
      requires equality_comparable<W>;

    friend constexpr bool operator<(const iterator& x, const iterator& y)
      requires totally_ordered<W>;
    friend constexpr bool operator>(const iterator& x, const iterator& y)
      requires totally_ordered<W>;
    friend constexpr bool operator<=(const iterator& x, const iterator& y)
      requires totally_ordered<W>;
    friend constexpr bool operator>=(const iterator& x, const iterator& y)
      requires totally_ordered<W>;
    friend constexpr auto operator<=>(const iterator& x, const iterator& y)
      requires totally_ordered<W> && three_way_comparable<W>;

    friend constexpr iterator operator+(iterator i, difference_type n)
      requires advanceable<W>;
    friend constexpr iterator operator+(difference_type n, iterator i)
      requires advanceable<W>;

    friend constexpr iterator operator-(iterator i, difference_type n)
      requires advanceable<W>;
    friend constexpr difference_type operator-(const iterator& x, const iterator& y)
      requires advanceable<W>;
  };
}

iterator::iterator_concept is defined as follows:

(1.1)
If W models advanceable, then iterator_concept is random_access_iterator_tag.
(1.2)
Otherwise, if W models decrementable, then iterator_concept is bidirectional_iterator_tag.
(1.3)
Otherwise, if W models incrementable, then iterator_concept is forward_iterator_tag.
(1.4)
Otherwise, iterator_concept is input_iterator_tag.

[ Note

Overloads for iter_move and iter_swap are omitted intentionally.

— end note

]

🔗

constexpr explicit iterator(W value);

Effects: Initializes value_ with value.

🔗

constexpr W operator*() const noexcept(is_nothrow_copy_constructible_v<W>);

Effects: Equivalent to: return value_;

[ Note

The noexcept clause is needed by the default iter_move implementation.

— end note

]

🔗

constexpr iterator& operator++();

Effects: Equivalent to:

++value_;
return *this;

🔗

constexpr void operator++(int);

Effects: Equivalent to ++*this.

🔗

constexpr iterator operator++(int) requires incrementable<W>;

Effects: Equivalent to:

auto tmp = *this;
++*this;
return tmp;

🔗

constexpr iterator& operator--() requires decrementable<W>;

Effects: Equivalent to:

--value_;
return *this;

🔗

constexpr iterator operator--(int) requires decrementable<W>;

Effects: Equivalent to:

auto tmp = *this;
--*this;
return tmp;

🔗

constexpr iterator& operator+=(difference_type n)
  requires advanceable<W>;

Effects: Equivalent to:

if constexpr (is-integer-like<W> && !is-signed-integer-like<W>) {
  if (n >= difference_type(0))
    value_ += static_cast<W>(n);
  else
    value_ -= static_cast<W>(-n);
} else {
  value_ += n;
}
return *this;

🔗

constexpr iterator& operator-=(difference_type n)
  requires advanceable<W>;

Effects: Equivalent to:

if constexpr (is-integer-like<W> && !is-signed-integer-like<W>) {
  if (n >= difference_type(0))
    value_ -= static_cast<W>(n);
  else
    value_ += static_cast<W>(-n);
} else {
  value_ -= n;
}
return *this;

🔗

constexpr W operator[](difference_type n) const
  requires advanceable<W>;

Effects: Equivalent to: return W(value_ + n);

🔗

friend constexpr bool operator==(const iterator& x, const iterator& y)
  requires equality_comparable<W>;

Effects: Equivalent to: return x.value_ == y.value_;

🔗

friend constexpr bool operator<(const iterator& x, const iterator& y)
  requires totally_ordered<W>;

Effects: Equivalent to: return x.value_ < y.value_;

🔗

friend constexpr bool operator>(const iterator& x, const iterator& y)
  requires totally_ordered<W>;

Effects: Equivalent to: return y < x;

🔗

friend constexpr bool operator<=(const iterator& x, const iterator& y)
  requires totally_ordered<W>;

Effects: Equivalent to: return !(y < x);

🔗

friend constexpr bool operator>=(const iterator& x, const iterator& y)
  requires totally_ordered<W>;

Effects: Equivalent to: return !(x < y);

🔗

friend constexpr auto operator<=>(const iterator& x, const iterator& y)
  requires totally_ordered<W> && three_way_comparable<W>;

Effects: Equivalent to: return x.value_ <=> y.value_;

🔗

friend constexpr iterator operator+(iterator i, difference_type n)
  requires advanceable<W>;

Effects: Equivalent to: return i += n;

🔗

friend constexpr iterator operator+(difference_type n, iterator i)
  requires advanceable<W>;

Effects: Equivalent to: return i + n;

🔗

friend constexpr iterator operator-(iterator i, difference_type n)
  requires advanceable<W>;

Effects: Equivalent to: return i -= n;

🔗

friend constexpr difference_type operator-(const iterator& x, const iterator& y)
  requires advanceable<W>;

Effects: Equivalent to:

using D = difference_type;
if constexpr (is-integer-like<W>) {
  if constexpr (is-signed-integer-like<W>)
    return D(D(x.value_) - D(y.value_));
  else
    return (y.value_ > x.value_)
      ? D(-D(y.value_ - x.value_))
      : D(x.value_ - y.value_);
} else {
  return x.value_ - y.value_;
}

24.6.3.4 Class iota_view::sentinel [range.iota.sentinel]

namespace std::ranges {
  template<weakly_incrementable W, semiregular Bound>
    requires weakly-equality-comparable-with<W, Bound>
  struct iota_view<W, Bound>::sentinel {
  private:
    Bound bound_ = Bound();     // exposition only
  public:
    sentinel() = default;
    constexpr explicit sentinel(Bound bound);

    friend constexpr bool operator==(const iterator& x, const sentinel& y);

    friend constexpr iter_difference_t<W> operator-(const iterator& x, const sentinel& y)
      requires sized_sentinel_for<Bound, W>;
    friend constexpr iter_difference_t<W> operator-(const sentinel& x, const iterator& y)
      requires sized_sentinel_for<Bound, W>;
  };
}

🔗

constexpr explicit sentinel(Bound bound);

Effects: Initializes bound_ with bound.

🔗

friend constexpr bool operator==(const iterator& x, const sentinel& y);

Effects: Equivalent to: return x.value_ == y.bound_;

🔗

friend constexpr iter_difference_t<W> operator-(const iterator& x, const sentinel& y)
  requires sized_sentinel_for<Bound, W>;

Effects: Equivalent to: return x.value_ - y.bound_;

🔗

friend constexpr iter_difference_t<W> operator-(const sentinel& x, const iterator& y)
  requires sized_sentinel_for<Bound, W>;

Effects: Equivalent to: return -(y - x);

24.6.4 Istream view [range.istream]

24.6.4.1 Overview [range.istream.overview]

basic_istream_view models input_range and reads (using operator>>) successive elements from its corresponding input stream.

[ Example

auto ints = istringstream{"0 1  2   3     4"};
ranges::copy(istream_view<int>(ints), ostream_iterator<int>{cout, "-"});
// prints 0-1-2-3-4-

— end example

]

24.6.4.2 Class template basic_istream_view [range.istream.view]

namespace std::ranges {
  template<class Val, class CharT, class Traits>
    concept stream-extractable =                // exposition only
      requires(basic_istream<CharT, Traits>& is, Val& t) {
         is >> t;
      };

  template<movable Val, class CharT, class Traits>
    requires default_initializable<Val> &&
             stream-extractable<Val, CharT, Traits>
  class basic_istream_view : public view_interface<basic_istream_view<Val, CharT, Traits>> {
  public:
    basic_istream_view() = default;
    constexpr explicit basic_istream_view(basic_istream<CharT, Traits>& stream);

    constexpr auto begin()
    {
      if (stream_) {
        *stream_ >> object_;
      }
      return iterator{*this};
    }

    constexpr default_sentinel_t end() const noexcept;

  private:
    struct iterator;                                    // exposition only
    basic_istream<CharT, Traits>* stream_ = nullptr;    // exposition only
    Val object_ = Val();                                // exposition only
  };
}

🔗

constexpr explicit basic_istream_view(basic_istream<CharT, Traits>& stream);

Effects: Initializes stream_ with addressof(stream).

🔗

constexpr default_sentinel_t end() const noexcept;

Effects: Equivalent to: return default_sentinel;

🔗

template<class Val, class CharT, class Traits>
basic_istream_view<Val, CharT, Traits> istream_view(basic_istream<CharT, Traits>& s);

Effects: Equivalent to: return basic_istream_view<Val, CharT, Traits>{s};

24.6.4.3 Class template basic_istream_view::iterator [range.istream.iterator]

namespace std::ranges {
  template<movable Val, class CharT, class Traits>
    requires default_initializable<Val> &&
             stream-extractable<Val, CharT, Traits>
  class basic_istream_view<Val, CharT, Traits>::iterator {      // exposition only
  public:
    using iterator_concept = input_iterator_tag;
    using difference_type = ptrdiff_t;
    using value_type = Val;

    iterator() = default;
    constexpr explicit iterator(basic_istream_view& parent) noexcept;

    iterator(const iterator&) = delete;
    iterator(iterator&&) = default;

    iterator& operator=(const iterator&) = delete;
    iterator& operator=(iterator&&) = default;

    iterator& operator++();
    void operator++(int);

    Val& operator*() const;

    friend bool operator==(const iterator& x, default_sentinel_t);

  private:
    basic_istream_view* parent_ = nullptr;                      // exposition only
  };
}

🔗

constexpr explicit iterator(basic_istream_view& parent) noexcept;

Effects: Initializes parent_ with addressof(parent).

🔗

iterator& operator++();

Preconditions: parent_->stream_ != nullptr is true.

Effects: Equivalent to:

*parent_->stream_>> parent_->object_;
return *this;

🔗

void operator++(int);

Preconditions: parent_->stream_ != nullptr is true.

Effects: Equivalent to ++*this.

🔗

Val& operator*() const;

Preconditions: parent_->stream_ != nullptr is true.

Effects: Equivalent to: return parent_->object_;

🔗

friend bool operator==(const iterator& x, default_sentinel_t);

Effects: Equivalent to: return x.parent_ == nullptr || !*x.parent_->stream_;

24 Ranges library [ranges]

24.6 Range factories [range.factories]

24.6.1 Empty view [range.empty]

24.6.1.1 Overview [range.empty.overview]

24.6.1.2 Class template empty_­view [range.empty.view]

24.6.2 Single view [range.single]

24.6.2.1 Overview [range.single.overview]

24.6.2.2 Class template single_­view [range.single.view]

24.6.3 Iota view [range.iota]

24.6.3.1 Overview [range.iota.overview]

24.6.3.2 Class template iota_­view [range.iota.view]

24.6.3.3 Class iota_­view​::​iterator [range.iota.iterator]

24.6.3.4 Class iota_­view​::​sentinel [range.iota.sentinel]

24.6.4 Istream view [range.istream]

24.6.4.1 Overview [range.istream.overview]

24.6.4.2 Class template basic_­istream_­view [range.istream.view]

24.6.4.3 Class template basic_­istream_­view​::​iterator [range.istream.iterator]

24.6.1.2 Class template empty_view [range.empty.view]

24.6.2.2 Class template single_view [range.single.view]

24.6.3.2 Class template iota_view [range.iota.view]

24.6.3.3 Class iota_view::iterator [range.iota.iterator]

24.6.3.4 Class iota_view::sentinel [range.iota.sentinel]

24.6.4.2 Class template basic_istream_view [range.istream.view]

24.6.4.3 Class template basic_istream_view::iterator [range.istream.iterator]