Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/ranges/iota view"

From cppreference.com
< cpp‎ | ranges
m (unifying the exposition-only names)
(Added anchors to data members.)
 
(47 intermediate revisions by 9 users not shown)
Line 1: Line 1:
−
{{cpp/ranges/view title | iota}}
+
{{cpp/ranges/view title|iota}}
 
{{cpp/ranges/iota_view/navbar}}
 
{{cpp/ranges/iota_view/navbar}}
−
 
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl header | ranges}}
+
{{dcl header|ranges}}
−
{{dcl | num=1 | since=c++20 | 1=
+
{{dcl|num=1|since=c++20|1=
−
template<std::weakly_incrementable W,
+
template< std::weakly_incrementable W,
−
        std::semiregular Bound = std::unreachable_sentinel_t>
+
          std::semiregular Bound = std::unreachable_sentinel_t >
−
     requires __WeaklyEqualityComparableWith<W, Bound> && std::semiregular<W>
+
     requires /*weakly-equality-comparable-with*/<W, Bound> && std::copyable<W>
−
class iota_view : public ranges::view_interface<iota_view<W, Bound>>
+
class iota_view
 +
    : public ranges::view_interface<iota_view<W, Bound>>
 
}}
 
}}
−
{{dcl | num=2 | since=c++20 | 1=
+
{{dcl|num=2|since=c++20|1=
 
namespace views {
 
namespace views {
−
     inline constexpr /*unspecified*/ iota = /*unspecified*/;
+
     inline constexpr /* unspecified */ iota = /* unspecified */;
 
}
 
}
 +
}}
 +
{{dcl h|Call signature}}
 +
{{dcl|since=c++20|1=
 +
template< class W >
 +
    requires /* see below */
 +
constexpr /* see below */ iota( W&& value );
 +
}}
 +
{{dcl|since=c++20|1=
 +
template< class W, class Bound >
 +
    requires /* see below */
 +
constexpr /* see below */ iota( W&& value, Bound&& bound );
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
  
−
@1@ A range factory that generates a sequence of elements by repeatedly incrementing an initial value. Can be either bounded or unbounded (infinite)
+
@1@ A range factory that generates a sequence of elements by repeatedly incrementing an initial value. Can be either bounded or unbounded (infinite).
−
@2@ {{c|views::iota(E)}} and {{c|views::iota(E, F)}} are ''expression-equivalent'' to (has the same effect as) {{c|iota_view{E} }} and {{c|iota_view{E, F} }} respectively for any suitable subexpressions {{tt|E}} and {{tt|F}}
+
@2@ {{c|views::iota(e)}} and {{c|views::iota(e, f)}} are [[cpp/language/expressions#Expression-equivalence|expression-equivalent]] to {{c|iota_view<std::decay_t<decltype((e))>>(e)}} and {{c|iota_view(e, f)}} respectively for any suitable subexpressions {{c|e}} and {{c|f}}.
  
−
{{cpp/expr-eq}}
+
{{cpp/ranges/cpo|views|iota}}
−
 
+
−
===Helper templates===
+
−
{{ddcl|1=
+
−
template<std::weakly_incrementable W, std::semiregular Bound>
+
−
inline constexpr bool enable_borrowed_range<ranges::iota_view<W, Bound>> = true;
+
−
}}
+
−
This specialization of {{ltt|cpp/ranges/borrowed_range|std::ranges::enable_borrowed_range}} makes {{tt|iota_view}} satisfy {{lconcept|borrowed_range}}.
+
  
 
===Data members===
 
===Data members===
−
{{member | {{small|std::ranges::iota_view::}}base_ | 2=
+
{{dsc begin}}
−
{{dcl begin}}
+
{{dsc hitem|Member|Definition}}
−
{{dcl |1=
+
{{dsc expos mem obj|spec={{tt|W}}|value_|id=value|the beginning value}}
−
W value_ = W(); /* exposition-only */
+
{{dsc expos mem obj|spec={{tt|Bound}}|bound_|id=bound|the sentinel value, may be unreachable}}
−
}}
+
{{dsc end}}
−
{{dcl end}}
+
−
the current value
+
−
}}
+
−
 
+
−
{{member | {{small|std::ranges::iota_view::}}bound_ | 2=
+
−
{{dcl begin}}
+
−
{{dcl |1=
+
−
Bound bound_ = Bound(); /* exposition-only */
+
−
}}
+
−
{{dcl end}}
+
−
the bound (defaults to {{lc|std::unreachable_sentinel_t}})
+
−
}}
+
  
 
===Member functions===
 
===Member functions===
−
{{member | {{small|std::ranges::iota_view::}}iota_view | 2=
+
{{dsc begin}}
−
{{dcl begin}}
+
{{dsc mem ctor|cpp/ranges/iota_view/iota_view|creates an {{tt|iota_view}}}}
−
{{dcl | num=1 |1=
+
{{dsc mem fun|cpp/ranges/iota_view/begin|obtains the beginning iterator of an {{tt|iota_view}}}}
−
iota_view() = default;
+
{{dsc mem fun|cpp/ranges/iota_view/end|obtains the sentinel denoting the end of an {{tt|iota_view}}}}
−
}}
+
{{dsc mem fun|cpp/ranges/iota_view/empty|tests whether the {{tt|iota_view}} is empty (i.e. the iterator and the sentinel compare equal)}}
−
{{dcl | num=2 |1=
+
{{dsc mem fun|cpp/ranges/iota_view/size|notes={{mark optional}}|obtains the size of an {{tt|iota_view}} (only provided if it is bounded)}}
−
constexpr explicit iota_view(W value);
+
−
}}
+
−
{{dcl | num=3 |1=
+
−
constexpr iota_view(std::type_identity_t<W> value,
+
−
                    std::type_identity_t<Bound> bound);
+
−
}}
+
−
{{dcl end}}
+
  
−
@1@ Value-initializes {{tt|value_}} and {{tt|bound_}}.
+
{{cpp/ranges/view_interface/inherit|embedded=yes|data=invalid|empty=invalid|size=yes}}
−
@2@ Initializes {{tt|value_}} with {{c|value}} and value-initializes {{tt|bound_}}. This constructor is used to create unbounded {{tt|iota_view}}s, e.g. {{c|iota(0)}} yields numbers 0,1,2..., infinitely.
+
{{dsc end}}
−
@3@ Initializes {{tt|value_}} with {{c|value}} and {{tt|bound_}} with {{c|bound}}. The behavior is undefined if {{c|std::totally_ordered_with<W, Bound>}} is modeled and {{c|1=bool(value <= bound)}} is {{c|false}}. This constructor is used to create bounded iota views, e.g. {{c|iota(10, 20)}} yields numbers from 10 to 19.
+
  
−
For {{v|2}} and {{v|3}}, the behavior is undefined if the {{tt|iota_view}} is bounded (i.e. {{tt|Bound}} is not {{lc|std::unreachable_sentinel_t}}) and {{tt|bound_}} is initialized to a value unreachable from {{c|value}}.
+
==={{rl|deduction guides|Deduction guides}}===
−
 
+
−
===Parameters===
+
−
{{par begin}}
+
−
{{par | value | the starting value }}
+
−
{{par | bound | the bound }}
+
−
{{par end}}
+
−
}}
+
−
 
+
−
{{member | {{small|std::ranges::iota_view::}}begin| 2=
+
−
{{dcl begin}}
+
−
{{dcl |
+
−
constexpr /*iterator*/ begin() const;
+
−
}}
+
−
{{dcl end}}
+
−
 
+
−
Returns an {{rl|iterator}} initialized with {{c|value_}}.
+
−
}}
+
−
 
+
−
{{member | {{small|std::ranges::iota_view::}}end| 2=
+
−
{{dcl begin}}
+
−
{{dcl |num=1|1=
+
−
constexpr auto end() const;
+
−
}}
+
−
{{dcl |num=2|1=
+
−
constexpr /*iterator*/ end() const requires std::same_as<W, Bound>;
+
−
}}
+
−
{{dcl end}}
+
−
@1@ Returns a {{rl|sentinel}} of a specific type initialized with {{c|bound_}} if this view is bounded, or {{lc|std::unreachable_sentinel}} if this view is unbounded.
+
−
@2@ Returns an {{rl|iterator}} initialized with {{c|bound_}}.
+
−
}}
+
−
 
+
−
{{member | {{small|std::ranges::iota_view::}}size| 2=
+
−
{{dcl begin}}
+
−
{{dcl |1=
+
−
constexpr auto size() const
+
−
  requires (std::same_as<W, Bound> && __Advanceable<W>) {{!!}}
+
−
          (std::integral<W> && std::integral<Bound>) {{!!}}
+
−
            std::sized_sentinel_for<Bound, W>
+
−
{
+
−
  if constexpr (__IsIntegerLike<W> && __IsIntegerLike<Bound>)
+
−
    return (value_ < 0)
+
−
      ? ((bound_ < 0)
+
−
        ? __MakeUnsignedLike(-value_) - __MakeUnsignedLike(-bound_)
+
−
        : __MakeUnsignedLike(bound_) + __MakeUnsignedLike(-value_))
+
−
      : __MakeUnsignedLike(bound_) - __MakeUnsignedLike(value_);
+
−
  else
+
−
    return __MakeUnsignedLike(bound_ - value_);
+
−
}
+
−
}}
+
−
{{dcl end}}
+
−
Returns the size of the view if the view is bounded.
+
−
}}
+
−
 
+
−
===Deduction guides===
+
−
{{dcl begin}}
+
−
{{dcl|1=
+
−
template<class W, class Bound>
+
−
    requires (!__IsIntegerLike<W> {{!!}} !__IsIntegerLike<Bound> {{!!}}
+
−
              __IsSignedIntegerLike<W> == __IsSignedIntegerLike<Bound>)
+
−
  iota_view(W, Bound) -> iota_view<W, Bound>;
+
−
}}
+
−
{{dcl end}}
+
−
Note that the guide protects itself against signed/unsigned mismatch bugs, like {{c|views::iota(0, v.size())}}, where {{tt|0}} is a (signed) {{tt|int}} and {{tt|v.size()}} is an (unsigned) {{tt|std::size_t}}.
+
  
 
===Nested classes===
 
===Nested classes===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc mem class| cpp/ranges/iota_view/iterator | title=''iterator'' | the iterator type}}
+
{{dsc expos mem class|cpp/ranges/iota_view/iterator|the iterator type}}
−
{{dsc mem class| cpp/ranges/iota_view/sentinel | title=''sentinel'' | the sentinel type used when the {{tt|iota_view}} is bounded and {{tt|Bound}} and {{tt|W}} are not the same type}}
+
{{dsc expos mem class|cpp/ranges/iota_view/sentinel|the sentinel type used when the {{tt|iota_view}} is bounded and {{tt|Bound}} and {{tt|W}} are not the same type}}
 
{{dsc end}}
 
{{dsc end}}
  
−
=== Example ===
+
===Helper templates===
−
{{example|code=
+
{{ddcl|since=c++20|1=
 +
template< std::weakly_incrementable W, std::semiregular Bound >
 +
constexpr bool ranges::enable_borrowed_range<ranges::iota_view<W, Bound>> = true;
 +
}}
 +
This specialization of {{c/core|ranges::enable_borrowed_range}} makes {{tt|iota_view}} satisfy {{lconcept|borrowed_range}}.
 +
 
 +
===Example===
 +
{{example
 +
|code=
 +
#include <algorithm>
 +
#include <iostream>
 
#include <ranges>
 
#include <ranges>
−
#include <iostream>
+
   
 +
struct Bound
 +
{
 +
    int bound;
 +
    bool operator==(int x) const { return x == bound; }
 +
};
  
 
int main()
 
int main()
Line 148: Line 84:
 
         std::cout << i << ' ';
 
         std::cout << i << ' ';
 
     std::cout << '\n';
 
     std::cout << '\n';
−
 
+
   
 
     for (int i : std::views::iota(1, 10))
 
     for (int i : std::views::iota(1, 10))
 
         std::cout << i << ' ';
 
         std::cout << i << ' ';
 
     std::cout << '\n';
 
     std::cout << '\n';
−
 
+
   
 +
    for (int i : std::views::iota(1, Bound{10}))
 +
        std::cout << i << ' ';
 +
    std::cout << '\n';
 +
   
 
     for (int i : std::views::iota(1) {{!}} std::views::take(9))
 
     for (int i : std::views::iota(1) {{!}} std::views::take(9))
 
         std::cout << i << ' ';
 
         std::cout << i << ' ';
 +
    std::cout << '\n';
 +
   
 +
    std::ranges::for_each(std::views::iota(1, 10),
 +
                          [](int i){ std::cout << i << ' '; });
 
     std::cout << '\n';
 
     std::cout << '\n';
 
}
 
}
 
|output=
 
|output=
 +
1 2 3 4 5 6 7 8 9
 +
1 2 3 4 5 6 7 8 9
 
1 2 3 4 5 6 7 8 9
 
1 2 3 4 5 6 7 8 9
 
1 2 3 4 5 6 7 8 9
 
1 2 3 4 5 6 7 8 9
Line 163: Line 109:
 
}}
 
}}
  
−
{{langlinks|es|ja|zh}}
+
===Defect reports===
 +
{{dr list begin}}
 +
{{dr list item|wg=lwg|dr=4096|std=C++20|before={{tt|views::iota}} could copy an {{tt|iota_view}} as-is|after=forbidden}}
 +
{{dr list item|paper=P2325R3|std=C++20|before={{tt|iota_view}} required that {{tt|W}} is {{lconcept|semiregular}}<br>as {{lconcept|view}} required {{lconcept|default_initializable}}|after=only requires that {{tt|W}} is {{lconcept|copyable}}}}
 +
{{dr list end}}
 +
 
 +
===See also===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/algorithm/dsc iota}}
 +
{{dsc inc|cpp/algorithm/ranges/dsc iota}}
 +
{{dsc inc|cpp/ranges/dsc repeat_view}}
 +
{{dsc end}}
 +
 
 +
{{langlinks|es|ja|ru|zh}}

Latest revision as of 19:02, 7 October 2024

 
C++
 
Ranges library
Range adaptors
 
std::ranges::iota_view
Member functions
Deduction guides
Nested classes
Iterator
Helper concepts
Member types
Member functions
Non-member functions
Sentinel
Member functions
Non-member functions
 
Defined in header <ranges>
template< std::weakly_incrementable W,

          std::semiregular Bound = std::unreachable_sentinel_t >
    requires /*weakly-equality-comparable-with*/<W, Bound> && std::copyable<W>
class iota_view

    : public ranges::view_interface<iota_view<W, Bound>>
 (1) (since C++20)
namespace views {

    inline constexpr /* unspecified */ iota = /* unspecified */;

}
 (2) (since C++20)
Call signature
template< class W >

    requires /* see below */

constexpr /* see below */ iota( W&& value );
 (since C++20)
template< class W, class Bound >

    requires /* see below */

constexpr /* see below */ iota( W&& value, Bound&& bound );
 (since C++20)
1) A range factory that generates a sequence of elements by repeatedly incrementing an initial value. Can be either bounded or unbounded (infinite).
2) views::iota(e) and views::iota(e, f) are expression-equivalent to iota_view<std::decay_t<decltype((e))>>(e) and iota_view(e, f) respectively for any suitable subexpressions e and f.

Contents

Customization point objects

The name views::iota denotes a customization point object, which is a const function object of a literal semiregular class type. For exposition purposes, the cv-unqualified version of its type is denoted as __iota_fn.

All instances of __iota_fn are equal. The effects of invoking different instances of type __iota_fn on the same arguments are equivalent, regardless of whether the expression denoting the instance is an lvalue or rvalue, and is const-qualified or not (however, a volatile-qualified instance is not required to be invocable). Thus, views::iota can be copied freely and its copies can be used interchangeably.

Given a set of types Args..., if std::declval<Args>()... meet the requirements for arguments to views::iota above, __iota_fn models

Otherwise, no function call operator of __iota_fn participates in overload resolution.

[edit] Data members

Member Definition
W value_ the beginning value
(exposition-only member object*)
Bound bound_ the sentinel value, may be unreachable
(exposition-only member object*)

[edit] Member functions

 creates an iota_view
(public member function)
obtains the beginning iterator of an iota_view
(public member function)
obtains the sentinel denoting the end of an iota_view
(public member function)
tests whether the iota_view is empty (i.e. the iterator and the sentinel compare equal)
(public member function)
(optional)
 obtains the size of an iota_view (only provided if it is bounded)
(public member function)
Inherited from std::ranges::view_interface
(C++23)
 returns a constant iterator to the beginning of the range.
(public member function of std::ranges::view_interface<D>) [edit]
(C++23)
 returns a sentinel for the constant iterator of the range.
(public member function of std::ranges::view_interface<D>) [edit]
returns whether the derived view is not empty. Provided if ranges::empty is applicable to it.
(public member function of std::ranges::view_interface<D>) [edit]
returns the first element in the derived view. Provided if it satisfies forward_range.
(public member function of std::ranges::view_interface<D>) [edit]
returns the last element in the derived view. Provided if it satisfies bidirectional_range and common_range.
(public member function of std::ranges::view_interface<D>) [edit]
returns the nth element in the derived view. Provided if it satisfies random_access_range.
(public member function of std::ranges::view_interface<D>) [edit]

[edit] Deduction guides

[edit] Nested classes

 the iterator type
(exposition-only member class*)
the sentinel type used when the iota_view is bounded and Bound and W are not the same type
(exposition-only member class*)

[edit] Helper templates

template< std::weakly_incrementable W, std::semiregular Bound >
constexpr bool ranges::enable_borrowed_range<ranges::iota_view<W, Bound>> = true;
 (since C++20)

This specialization of ranges::enable_borrowed_range makes iota_view satisfy borrowed_range.

[edit] Example

Run this code
#include <algorithm>
#include <iostream>
#include <ranges>
 
struct Bound
{
    int bound;
    bool operator==(int x) const { return x == bound; }
};
 
int main()
{
    for (int i : std::ranges::iota_view{1, 10})
        std::cout << i << ' ';
    std::cout << '\n';
 
    for (int i : std::views::iota(1, 10))
        std::cout << i << ' ';
    std::cout << '\n';
 
    for (int i : std::views::iota(1, Bound{10}))
        std::cout << i << ' ';
    std::cout << '\n';
 
    for (int i : std::views::iota(1) | std::views::take(9))
        std::cout << i << ' ';
    std::cout << '\n';
 
    std::ranges::for_each(std::views::iota(1, 10),
                          [](int i){ std::cout << i << ' '; });
    std::cout << '\n';
}

Output: 

1 2 3 4 5 6 7 8 9
1 2 3 4 5 6 7 8 9
1 2 3 4 5 6 7 8 9
1 2 3 4 5 6 7 8 9
1 2 3 4 5 6 7 8 9

[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 4096 C++20 views::iota could copy an iota_view as-is forbidden
P2325R3 C++20 iota_view required that W is semiregular
as view required default_initializable 		only requires that W is copyable

[edit] See also

(C++11)
 fills a range with successive increments of the starting value
(function template) [edit]
(C++23)
 fills a range with successive increments of the starting value
(niebloid)[edit]
(C++23)
 a view consisting of a generated sequence by repeatedly producing the same value
(class template) (customization point object)[edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/ranges/iota_view&oldid=176915"