Skip to content

Update <array> functions reference #5684

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
v-dirichards merged 7 commits into from
Jan 27, 2026
Merged

Update <array> functions reference #5684

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
09c5a32
Update `get` syntax in `<array>` functions reference
Rageking8 Aug 20, 2025
b0d9bb4
Update `swap` syntax in `<array>` functions reference
Rageking8 Aug 20, 2025
e30b46e
Add "Template parameters" headings in `<array>` functions reference
Rageking8 Aug 20, 2025
183ce44
Document C++20 `std::to_array` function
Rageking8 Aug 20, 2025
99323ab
Simplify single "See also" link in `<array>` functions reference
Rageking8 Aug 20, 2025
d1f2f14
Update metadata in 2 standard library topics
Rageking8 Aug 20, 2025
a1cd597
Fix type references in array get function signatures
TylerMSFT Jan 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 94 additions & 19 deletions docs/standard-library/array-functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,45 @@
---
title: "<array> functions"
description: "Learn more about: <array> 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++]"]
---
# `<array>` functions

The `<array>` header includes two non-member functions, `get` and `swap`, that operate on **array** objects.
The `<array>` header includes three non-member functions, `get`, `swap`, and `to_array` that operate on **array** objects.

## <a name="get"></a> `get`

Returns a reference to the specified element of the array.

```cpp
template <int Index, class T, size_t N>
constexpr T& get(array<T, N>& arr) noexcept;
template <std::size_t Index, class Type, std::size_t Size>
constexpr Type& get(std::array<Type, Size>& arr) noexcept;

template <int Index, class T, size_t N>
constexpr const T& get(const array<T, N>& arr) noexcept;
template <std::size_t Index, class Type, std::size_t Size>
constexpr const Type& get(const std::array<Type, Size>& arr) noexcept;

template <int Index, class T, size_t N>
constexpr T&& get(array<T, N>&& arr) noexcept;
template <std::size_t Index, class Type, std::size_t Size>
constexpr Type&& get(std::array<Type, Size>&& arr) noexcept;

template <std::size_t Index, class Type, std::size_t Size>
constexpr const Type&& get(const std::array<Type, Size>&& 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.

Expand Down Expand Up @@ -75,18 +80,20 @@ int main()
A non-member template specialization of `std::swap` that swaps two **array** objects.

```cpp
template <class Ty, std::size_t N>
void swap(array<Ty, N>& left, array<Ty, N>& right);
template <class Type, std::size_t Size>
void swap(std::array<Type, Size>& left, std::array<Type, Size>& 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.

Expand Down Expand Up @@ -143,6 +150,74 @@ int main()
0 1 2 3
```

## <a name="to_array"></a> `to_array`

Converts a built-in array to a `std::array` object.

```cpp
// C++20
template <class Type, std::size_t Size>
constexpr std::array<std::remove_cv_t<Type>, Size> to_array(Type (&arr)[Size]);

// C++20
template <class Type, std::size_t Size>
constexpr std::array<std::remove_cv_t<Type>, 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 <array>
#include <iostream>

int main()
{
int arr1[]{ 1, 2, 3 };
std::array<int, 3> 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<char, 7> 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

[`<array>`](../standard-library/array.md)
[`<array>`](array.md)
5 changes: 3 additions & 2 deletions docs/standard-library/array.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: "Learn more about: <array>"
title: "<array>"
ms.date: "11/04/2016"
description: "Learn more about: <array>"
ms.date: 11/04/2016
f1_keywords: ["<array>"]
helpviewer_keywords: ["array header"]
---
Expand Down Expand Up @@ -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

Expand Down