diff --git a/docs/standard-library/array-functions.md b/docs/standard-library/array-functions.md index 60e9c8027c5..709189a51eb 100644 --- a/docs/standard-library/array-functions.md +++ b/docs/standard-library/array-functions.md @@ -1,40 +1,45 @@ --- title: " functions" description: "Learn more about: functions" -ms.date: 11/04/2016 -f1_keywords: ["array/std::array::get", "array/std::get", "array/std::swap"] -helpviewer_keywords: ["std::array [C++], get", "std::get [C++]", "std::swap [C++]"] +ms.date: 08/20/2025 +f1_keywords: ["array/std::array::get", "array/std::get", "array/std::swap", "array/std::to_array"] +helpviewer_keywords: ["std::array [C++], get", "std::get [C++]", "std::swap [C++]", "std::to_array [C++]"] --- # `` functions -The `` header includes two non-member functions, `get` and `swap`, that operate on **array** objects. +The `` header includes three non-member functions, `get`, `swap`, and `to_array` that operate on **array** objects. ## `get` Returns a reference to the specified element of the array. ```cpp -template -constexpr T& get(array& arr) noexcept; +template +constexpr T& get(std::array& arr) noexcept; -template -constexpr const T& get(const array& arr) noexcept; +template +constexpr const T& get(const std::array& arr) noexcept; -template -constexpr T&& get(array&& arr) noexcept; +template +constexpr T&& get(std::array&& arr) noexcept; + +template +constexpr const T&& get(const std::array&& arr) noexcept; ``` -### Parameters +### Template parameters *`Index`*\ The element offset. -*`T`*\ +*`Type`*\ The type of an element. -*`N`*\ +*`Size`*\ The number of elements in the array. +### Parameters + *`arr`*\ The array to select from. @@ -75,18 +80,20 @@ int main() A non-member template specialization of `std::swap` that swaps two **array** objects. ```cpp -template -void swap(array& left, array& right); +template +void swap(std::array& left, std::array& right); ``` -### Parameters +### Template parameters -*`Ty`*\ +*`Type`*\ The type of an element. -*`N`*\ +*`Size`*\ The size of the array. +### Parameters + *`left`*\ The first array to swap. @@ -143,6 +150,74 @@ int main() 0 1 2 3 ``` +## `to_array` + +Converts a built-in array to a `std::array` object. + +```cpp +// C++20 +template +constexpr std::array, Size> to_array(Type (&arr)[Size]); + +// C++20 +template +constexpr std::array, Size> to_array(Type (&&arr)[Size]); +``` + +### Template parameters + +*`Type`*\ +The type of an element. + +*`Size`*\ +The size of the input array. + +### Parameters + +*`arr`*\ +The input array used for conversion. + +### Example + +```cpp +// std_to_array.cpp +// Requires /std:c++20 or later + +#include +#include + +int main() +{ + int arr1[]{ 1, 2, 3 }; + std::array arr2 = std::to_array(arr1); + + std::cout << "std::to_array(arr1):\n"; + for (const auto& i : arr2) + { + std::cout << i << " "; + } + std::cout << std::endl; + + // The size is 7 as it includes the null terminator + std::array arr3 = std::to_array("string"); + + std::cout << "\nstd::to_array(\"string\"):\n"; + for (const auto& i : arr3) + { + std::cout << i << " "; + } + std::cout << std::endl; +} +``` + +```Output +std::to_array(arr1): +1 2 3 + +std::to_array("string"): +s t r i n g +``` + ## See also -[``](../standard-library/array.md) +[``](array.md) diff --git a/docs/standard-library/array.md b/docs/standard-library/array.md index 85273440ba3..331316ee9e2 100644 --- a/docs/standard-library/array.md +++ b/docs/standard-library/array.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 11/04/2016 f1_keywords: [""] helpviewer_keywords: ["array header"] --- @@ -45,6 +45,7 @@ Defines the container class template **array** and several supporting templates. |-|-| |[get](../standard-library/array-functions.md#get)|Get specified array element.| |[swap](../standard-library/array-functions.md#swap)|Exchanges the contents of one array with the contents of another array.| +| [`to_array`](array-functions.md#to_array) | Converts a built-in array to a `std::array` object. | ## See also