cxx/stdlib/range.txt

// Copyright 2017-2020 The Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[[range-library]]
=== Range Library

OpenCL {cpp} implements small library that contains useful utilities to manipulate iterator ranges.

[[header-opencl_range-synopsis]]
==== Header <opencl_range> Synopsis

[source]
----
namespace cl
{
template <class It>
struct range_type
{
    constexpr range_type(It& it) noexcept;
    constexpr range_type(It& it, difference_type end) noexcept;
    constexpr range_type(It& it, difference_type begin,
                         difference_type end) noexcept;

    constexpr auto begin( ) noexcept;
    constexpr auto end( ) noexcept;
};

template <class It>
constexpr auto range(It& it) noexcept;

template <class It>
constexpr auto range(It& it, difference_type end) noexcept;

template <class It>
constexpr auto range(It& it, difference_type begin,
                     difference_type end) noexcept;

// difference_type is It::difference_type if present ptrdiff_t otherwise.

}
----

[[range-type]]
==== Range type

Range type represents a given range over iterable type.
Depending on constructor used:

[source]
----
constexpr range_type(It& it) noexcept;
----

Represents range from `begin(it)` to `end(it)`.

[source]
----
constexpr range_type(It& it, difference_type end) noexcept;
----

Represents range from `begin(it)` to `begin(it)+end`.

[source]
----
constexpr range_type(It& it, difference_type begin,
                     difference_type end) noexcept;
----

Represents range from `begin(it)+begin` to `begin(it)+end`.

[[range-function]]
==== Range function

range function is present in three overloads matching `range_type` constructors.
It is a factory function building `range_type`.

NOTE: This function main purpose is enabling the use of range based for loops on built-in vectors.