std::ranges...lements_view(3)

🎀 NAME 🎀

okay bestie, welcome to the manual page for std::ranges::views::elements, std::ranges::elements_view — the full NAME line is std::ranges::views::elements, std::ranges::elements_view — std::ranges::views::elements, std::ranges::elements_view, and you'll see this page labeled std::ranges...lements_view(3) in the C++ Standard Libary manual. yes, that spelling is in the header, not me 💀.

---

✨ Synopsis ✨

Defined in header <ranges>. here's the main character class template, and it's marked (1) since C++20:

template< ranges::input_range V, std::size_t N >
    requires ranges::view<V> &&
             has-tuple-element<ranges::range_value_t<V>, N> &&
             has-tuple-element<std::remove_reference_t<
                 ranges::range_reference_t<V>>, N> &&
             returnable-element<ranges::range_reference_t<V>, N>
class elements_view : public ranges::view_interface<elements_view<V, N>>;

and the views::elements variable template is (2) since C++20:

namespace views {
    template< std::size_t N >
    inline constexpr /* unspecified */ elements = /* unspecified */;
}

📞 Call signature

since C++20, bestie:

template< ranges::viewable_range R >
    requires /* see below */
constexpr ranges::view auto elements<N>( R&& r );

🧠 Helper concepts 🧠

this one is (3), (until C++23), and it's exposition only*:

template< class T, std::size_t N >
concept has-tuple-element =
    requires(T t) {
        typename std::tuple_size<T>::type;
        requires N < std::tuple_size_v<T>;
        typename std::tuple_element_t<N, T>;
        { std::get<N>(t) } -> std::convertible_to<
                                  const std::tuple_element_t<N, T>&>;
    };

then in (since C++23) it's still exposition only* and becomes:

template< class T, std::size_t N >
concept has-tuple-element =
    tuple-like<T> && N < std::tuple_size_v<T>;

and (4) is this exposition only* concept:

template< class T, std::size_t N >
concept returnable-element =
    std::is_reference_v<T> || std::move_constructible<
        std::tuple_element_t<N, T>>;

so, translating the whole vibe:

1. Accepts a view of tuple-like values, and issues a view with a value type of the N-th element of the adapted view's value-type.
2. Every specialization of views::elements is a RangeAdaptorObject. The expression views::elements<M>(e) is expression-equivalent to elements_view<views::all_t<decltype((e))>, M>{e} for any suitable subexpression e and constant expression M.
3. Ensures that the elements of the underlying view are tuple-like values, see tuple-like (since C++23).
4. Ensures that dangling references cannot be returned.

elements_view models the concepts random_access_range, bidirectional_range, forward_range, input_range, common_range, and sized_range when the underlying view V models respective concepts.

---

🛠️ Member functions

• constructor — constructs a elements_view (C++20) (public member function)
• base — returns a copy of the underlying (adapted) view (C++20) (public member function)
• begin — returns an iterator to the beginning (C++20) (public member function)
• end — returns an iterator or a sentinel to the end (C++20) (public member function)
• size — returns the number of elements. Provided only if the underlying (adapted) range satisfies sized_range. (C++20) (public member function)

🌸 Inherited from std::ranges::view_interface

• empty — returns whether the derived view is empty. Provided if it satisfies sized_range or forward_range. (C++20) (public member function of std::ranges::view_interface<D>)
• cbegin — returns a constant iterator to the beginning of the range. (C++23) (public member function of std::ranges::view_interface<D>)
• cend — returns a sentinel for the constant iterator of the range. (C++23) (public member function of std::ranges::view_interface<D>)
• operator bool — returns whether the derived view is not empty. Provided if ranges::empty is applicable to it. (C++20) (public member function of std::ranges::view_interface<D>)
• front — returns the first element in the derived view. Provided if it satisfies forward_range. (C++20) (public member function of std::ranges::view_interface<D>)
• back — returns the last element in the derived view. Provided if it satisfies bidirectional_range and common_range. (C++20) (public member function of std::ranges::view_interface<D>)
• operator[] — returns the n^th element in the derived view. Provided if it satisfies random_access_range. (C++20) (public member function of std::ranges::view_interface<D>)

---

🪆 Nested classes

• iterator — the iterator type (C++20) (exposition-only member class template*)
• sentinel — the sentinel type (C++20) (exposition-only member class template*)

---

🧰 Helper templates

since C++20, this is the borrowed-range glow-up:

template<class T, std::size_t N>
inline constexpr bool
enable_borrowed_range<std::ranges::elements_view<T, N>> =
    std::ranges::enable_borrowed_range<T>;

This specialization of std::ranges::enable_borrowed_range makes elements_view satisfy borrowed_range when the underlying view satisfies it.

---

💻 Example

// Run this code

#include <iostream>
#include <ranges>
#include <string>
#include <tuple>
#include <vector>

int main()
{
    const std::vector<std::tuple<int, char, std::string>> vt
    {
        {1, 'A', "α"},
        {2, 'B', "β"},
        {3, 'C', "γ"},
        {4, 'D', "δ"},
        {5, 'E', "ε"},
    };

    for (int const e : std::views::elements<0>(vt))
        std::cout << e << ' ';
    std::cout << '\n';

    for (char const e : vt | std::views::elements<1>)
        std::cout << e << ' ';
    std::cout << '\n';

    for (std::string const& e : std::views::elements<2>(vt))
        std::cout << e << ' ';
    std::cout << '\n';
}

🖨️ Output

1 2 3 4 5
A B C D E
α β γ δ ε

---

🩹 Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• LWG 3494 — applied to C++20. Behavior as published: elements_view was never a borrowed_range. Correct behavior: it is a borrowed_range if its underlying view is.
• LWG 3502 — applied to C++20. Behavior as published: dangling reference could be obtained from elements_view. Correct behavior: such usage is forbidden.

---

👀 See also

• ranges::keys_view / views::keys (C++20) — takes a view consisting of pair-like values and produces a view of the first elements of each pair (class template) (range adaptor object)
• ranges::values_view / views::values (C++20) — takes a view consisting of pair-like values and produces a view of the second elements of each pair (class template) (range adaptor object)
• ranges::zip_view / views::zip (C++23) — a view consisting of tuples of references to corresponding elements of the adapted views (class template) (customization point object)
• ranges::zip_transform_view / views::zip_transform (C++23) — a view consisting of tuples of results of application of a transformation function to corresponding elements of the adapted views (class template) (customization point object)
• slice — BLAS-like slice of a valarray: starting index, length, stride (class)

---

mwah 💋 this page came from http://cppreference.com, version/date 2024.06.10, and the manual label std::ranges...lements_view(3) — catch you in the next page, bestie 🫶✨