std::to_array(3)

💖 std::to_array — C++ Standard Library 💖

okay bestie, welcome to the std::to_array(3) page. This is the C++ Standard Library glow-up where a one-dimensional built-in array becomes a std::array, and honestly? iconic. ✨

💖 NAME 💖

std::to_array — std::to_array (yes, that's the whole name, no cap)

✨ SYNOPSIS ✨

Defined in header <array>:

template< class T, std::size_t N >
constexpr std::array<std::remove_cv_t<T>, N> to_array( T (&a)[N] );

(1) (since C++20)

template< class T, std::size_t N >
constexpr std::array<std::remove_cv_t<T>, N> to_array( T (&&a)[N] );

(2) (since C++20)

Creates a std::array from the one dimensional built-in array a. Copying or moving multidimensional built-in array is not supported. 🫶

1. For every i in 0, ..., N - 1, copy-initializes result's correspond element with a[i]. This overload is ill-formed when std::is_constructible_v<T, T&> is false.
2. For every i in 0, ..., N - 1, move-initializes result's correspond element with std::move(a[i]). This overload is ill-formed when std::is_move_constructible_v<T> is false.

Both overloads are ill-formed when std::is_array_v<T> is true. 🚨

🎀 PARAMETERS 🎀

• a — the built-in array to be converted the std::array

🌸 TYPE REQUIREMENTS 🌸

• T must meet the requirements of CopyConstructible in order to use overload (1).
• T must meet the requirements of MoveConstructible in order to use overload (2).

🦋 RETURN VALUE 🦋

1. std::array<std::remove_cv_t<T>, N>{ a[0], ..., a[N - 1] }
2. std::array<std::remove_cv_t<T>, N>{ std::move(a[0]), ..., std::move(a[N - 1]) }

💅 NOTES 💅

There are some occasions where class template argument deduction of std::array cannot be used while to_array is available:

• to_array can be used when the element type of the std::array is manually specified and the length is deduced, which is preferable when implicit conversion is wanted.
• to_array can copy a string literal, while class template argument deduction constructs a std::array of a single pointer to its first character.

std::to_array<long>({3, 4}); // OK: implicit conversion
// std::array<long>{3, 4};   // error: too few template arguments
std::to_array("foo");        // creates std::array<char, 4>{'f', 'o', 'o', '\0'}
std::array{"foo"};           // creates std::array<const char*, 1>{"foo"}

Feature-test macro tea ☕:

• __cpp_lib_to_array — value 201907L, standard (C++20), feature std::to_array

👑 POSSIBLE IMPLEMENTATION 👑

to_array (1)

namespace detail
{
    template<class T, std::size_t N, std::size_t... I>
    constexpr std::array<std::remove_cv_t<T>, N>
        to_array_impl(T (&a)[N], std::index_sequence<I...>)
    {
        return {{a[I]...}};
    }
}

template<class T, std::size_t N>
constexpr std::array<std::remove_cv_t<T>, N> to_array(T (&a)[N])
{
    return detail::to_array_impl(a, std::make_index_sequence<N>{});
}

to_array (2)

namespace detail
{
    template<class T, std::size_t N, std::size_t... I>
    constexpr std::array<std::remove_cv_t<T>, N>
        to_array_impl(T (&&a)[N], std::index_sequence<I...>)
    {
        return {{std::move(a[I])...}};
    }
}

template<class T, std::size_t N>
constexpr std::array<std::remove_cv_t<T>, N> to_array(T (&&a)[N])
{
    return detail::to_array_impl(std::move(a), std::make_index_sequence<N>{});
}

🌈 EXAMPLE 🌈

// Run this code

#include <array>
#include <memory>
#include <string_view>
#include <type_traits>
#include <utility>

// creates a constexpr array of string_view's
constexpr auto w1n = std::to_array<std::string_view>({
    "Mary", "Patricia", "Linda", "Barbara", "Elizabeth", "Jennifer"
});
static_assert(std::is_same_v<decltype(w1n), const std::array<std::string_view, 6>>);
static_assert(w1n.size() == 6 and w1n[5] == "Jennifer");

int main()
{
    // copies a string literal
    auto a1 = std::to_array("foo");
    static_assert(a1.size() == 4);

    // deduces both element type and length
    auto a2 = std::to_array({0, 2, 1, 3});
    static_assert(std::is_same_v<decltype(a2), std::array<int, 4>>);

    // deduces length with element type specified
    // implicit conversion happens
    auto a3 = std::to_array<long>({0, 1, 3});
    static_assert(std::is_same_v<decltype(a3), std::array<long, 3>>);

    auto a4 = std::to_array<std::pair<int, float>>(
        {{3, 0.0f}, {4, 0.1f}, {4, 0.1e23f}});
    static_assert(a4.size() == 3);

    // creates a non-copyable std::array
    auto a5 = std::to_array({std::make_unique<int>(3)});
    static_assert(a5.size() == 1);

    // error: copying multidimensional arrays is not supported
    // char s[2][6] = {"nice", "thing"};
    // auto a6 = std::to_array(s);
}

🌟 SEE ALSO 🌟

• make_array — creates a std::array object whose size and optionally element type are deduced from the arguments (library fundamentals TS v2) (function template)

---

mwah 💋 this page came from http://cppreference.com, version/date 2024.06.10, and it is the std::to_array(3) page. bye bestie, go make some arrays 🫶💖