cpp/ranges/to

The overloads of the range conversion function construct a new non-view object from a source range as its first argument by calling a constructor taking a range, a tagged ranged constructor, a constructor taking an iterator-sentinel pair, or by back inserting each element of the source range into the arguments-constructed object.

@1@ Constructs an object of type from the elements of  in the following:
 * @a@ If does not satisfy  or  is :
 * @1@ Constructing a non-view object as if direct-initializing (but not direct-list-initializing) an object of type from the source range  and the rest of the functional arguments  if  is.
 * @2@ Otherwise, constructing a non-view object as if direct-initializing (but not direct-list-initializing) an object of type from additional disambiguation tag, the source range  and the rest of the functional arguments  if  is.
 * @3@ Otherwise, constructing a non-view object as if direct-initializing (but not direct-list-initializing) an object of type from the iterator-sentinel pair ( as an iterator and  as sentinel, where iterator and sentinel have the same type. In other words, the source range must be a common range), and the rest of function arguments  if all of the conditions below are :


 * If is valid and denotes a type that satisfies
 * @4@ Otherwise, constructing a non-view range object as if direct-initializing (but not direct-list-initializing) an object of type from the rest of the function arguments  with the following equivalent call below after the construction:
 * @4@ Otherwise, constructing a non-view range object as if direct-initializing (but not direct-list-initializing) an object of type from the rest of the function arguments  with the following equivalent call below after the construction:
 * @4@ Otherwise, constructing a non-view range object as if direct-initializing (but not direct-list-initializing) an object of type from the rest of the function arguments  with the following equivalent call below after the construction:

If the satisfies  and  satisfies, the constructed object  of type  is able to reserve storage with the initial storage size  to prevent additional allocations during inserting new elements. Each range reference element of is back inserted to  through  with back inserter adaptor. The operations above are valid if both of the conditions below are :
 * @b@ Otherwise, the return expression is equivalent to:
 * @b@ Otherwise, the return expression is equivalent to:
 * @b@ Otherwise, the return expression is equivalent to:

Which allows nested range constructions within the range if is. Otherwise, the program is ill-formed.

@2@ Constructs an object of deduced type from the elements of. Let be an exposition only type that satisfies :

Let be defined as follows: The call is equivalent to. @3-4@ Returns a perfect forwarding call wrapper that is also a. @5@ The exposition-only variable template is  if it satisfies  and is eligible to be reservable. @6@ The exposition-only variable template is  if  is back insertable by a member function call  or. @7@ The exposition-only function template returns an output iterator of type  if member function  is available, otherwise the type is.
 * , if that expression is valid.
 * Otherwise,, if that expression is valid.
 * Otherwise,, if that expression is valid.
 * Otherwise, the program is ill-formed.

@8@ The exposition-only concept is used in the definition of containers in constructing an input range  and its range reference type must be convertible to.

Return value
@1-2@ a constructed non-view object @3-4@ a range adaptor closure object of unspecified type, with the following properties: {{member|{{small|ranges::to}} return type|2=

The return type is derived from {{c|ranges::range_adaptor_closure}}.

Member objects
The returned object behaves as if it has no target object, and an std object constructed with, except that the returned object's assignment behavior is unspecified and the names are for exposition only.

Constructors
The return type of  behaves as if its copy/move constructors perform a memberwise copy/move. It is if all of its member objects (specified above) are, and is  otherwise.

Member function
Given an object obtained from an earlier call to, when a glvalue  designating  is invoked in a function call expression , an invocation of the stored object takes place, as if by
 * , where
 * is a source range object that must satisfy
 * is an integer pack
 * is an lvalue in the call expression if it is an lvalue in the call expression, and is an rvalue otherwise. Thus can move the bound arguments into the call, where  would copy.
 * The specified template argument is  or  the deduced type from a class template  that must not satisfy.

The program is ill-formed if has volatile-qualified type. }}

Exceptions
Only throws if construction of a range object throws.