25 Ranges library [ranges]

Subclause [range.adaptors] defines range adaptors, which are utilities that transform a range into a view with custom behaviors.

These adaptors can be chained to create pipelines of range transformations that evaluate lazily as the resulting view is iterated.

Range adaptors are declared in namespace std​::​ranges​::​views.

The bitwise or operator is overloaded for the purpose of creating adaptor chain pipelines.

The adaptors also support function call syntax with equivalent semantics.

A range adaptor closure object is a unary function object that accepts a range argument.

For a range adaptor closure object C and an expression R such that decltype((R)) models range, the following expressions are equivalent: C(R) R | C

Given an additional range adaptor closure object D, the expression C | D produces another range adaptor closure object E.

E is a perfect forwarding call wrapper ([func.require]) with the following properties:

• (1.1)
  Its target object is an object d of type decay_t<decltype((D))> direct-non-list-initialized with D.
• (1.2)
  It has one bound argument entity, an object c of type decay_t<decltype((C))> direct-non-list-initialized with C.
• (1.3)
  Its call pattern is d(c(arg)), where arg is the argument used in a function call expression of E.

The expression C | D is well-formed if and only if the initializations of the state entities of E are all well-formed.

Given an object t of type T, where

• (2.1)
  t is a unary function object that accepts a range argument,
• (2.2)
  T models derived_from<range_adaptor_closure<T>>,
• (2.3)
  T has no other base classes of type range_adaptor_closure<U> for any other type U, and
• (2.4)
  T does not model range

then the implementation ensures that t is a range adaptor closure object.

The template parameter D for range_adaptor_closure may be an incomplete type.

If an expression of type cv D is used as an operand to the | operator, D shall be complete and model derived_from<range_adaptor_closure<D>>.

The behavior of an expression involving an object of type cv D as an operand to the | operator is undefined if overload resolution selects a program-defined operator| function.

If an expression of type cv U is used as an operand to the | operator, where U has a base class of type range_adaptor_closure<T> for some type T other than U, the behavior is undefined.

The behavior of a program that adds a specialization for range_adaptor_closure is undefined.

A range adaptor object is a customization point object ([customization.point.object]) that accepts a viewable_range as its first argument and returns a view.

If a range adaptor object accepts only one argument, then it is a range adaptor closure object.

If a range adaptor object adaptor accepts more than one argument, then let range be an expression such that decltype((range)) models viewable_range, let args... be arguments such that adaptor(range, args...) is a well-formed expression as specified in the rest of subclause [range.adaptors], and let BoundArgs be a pack that denotes decay_t<decltype((args))>....

The expression adaptor(args...) produces a range adaptor closure object f that is a perfect forwarding call wrapper ([func.require]) with the following properties:

• (8.1)
  Its target object is a copy of adaptor.
• (8.2)
  Its bound argument entities bound_args consist of objects of types BoundArgs... direct-non-list-initialized with std​::​forward<decltype((args))>(args)..., respectively.
• (8.3)
  Its call pattern is adaptor(r, bound_args...), where r is the argument used in a function call expression of f.

The expression adaptor(args...) is well-formed if and only if the initialization of the bound argument entities of the result, as specified above, are all well-formed.

Many types in this subclause are specified in terms of an exposition-only class template movable-box.

movable-box<T> behaves exactly like optional<T> with the following differences:

• (1.1)
  movable-box<T> constrains its type parameter T with move_constructible<T> && is_object_v<T>.
• (1.2)
  The default constructor of movable-box<T> is equivalent to: constexpr movable-box() noexcept(is_nothrow_default_constructible_v<T>) requires default_initializable<T> : movable-box{in_place} {}
• (1.3)
  If copyable<T> is not modeled, the copy assignment operator is equivalent to: constexpr movable-box& operator=(const movable-box& that) noexcept(is_nothrow_copy_constructible_v<T>) requires copy_constructible<T> { if (this != addressof(that)) { if (that) emplace(*that); else reset(); } return *this; }
• (1.4)
  If movable<T> is not modeled, the move assignment operator is equivalent to: constexpr movable-box& operator=(movable-box&& that) noexcept(is_nothrow_move_constructible_v<T>) { if (this != addressof(that)) { if (that) emplace(std::move(*that)); else reset(); } return *this; }

Recommended practice:

• (2.1)
  If copy_constructible<T> is true, movable-box<T> should store only a T if either T models copyable, or is_nothrow_move_constructible_v<T> && is_nothrow_copy_constructible_v<T> is true.
• (2.2)
  Otherwise, movable-box<T> should store only a T if either T models movable or is_nothrow_move_constructible_v<T> is true.

Some types in [range.adaptors] are specified in terms of an exposition-only class template non-propagating-​cache.

non-propagating-cache<T> behaves exactly like optional<T> with the following differences:

• (1.1)
  non-propagating-cache<T> constrains its type parameter T with is_object_v<T>.
• (1.2)
  The copy constructor is equivalent to: constexpr non-propagating-cache(const non-propagating-cache&) noexcept {}
• (1.3)
  The move constructor is equivalent to: constexpr non-propagating-cache(non-propagating-cache&& other) noexcept { other.reset(); }
• (1.4)
  The copy assignment operator is equivalent to: constexpr non-propagating-cache& operator=(const non-propagating-cache& other) noexcept { if (addressof(other) != this) reset(); return *this; }
• (1.5)
  The move assignment operator is equivalent to: constexpr non-propagating-cache& operator=(non-propagating-cache&& other) noexcept { reset(); other.reset(); return *this; }
• (1.6)
  non-propagating-cache<T> has an additional member function template specified as follows:
  🔗

  template<class I> constexpr T& emplace-deref(const I& i); // exposition only
  Mandates: The declaration T t(*i); is well-formed for some invented variable t.

  [Note 1: 

  If *i is a prvalue of type cv T, there is no requirement that it is movable ([dcl.init.general]).

  — end note]

  Effects: Calls reset().

  Then direct-non-list-initializes the contained value with *i.

  Postconditions: *this contains a value.

  Returns: A reference to the new contained value.

  Throws: Any exception thrown by the initialization of the contained value.

  Remarks: If an exception is thrown during the initialization of T, *this does not contain a value, and the previous value (if any) has been destroyed.