[array]

# 23 Containers library [[containers]](./#containers)

## 23.3 Sequence containers [[sequences]](sequences#array)

### 23.3.3 Class template array [array]

#### [23.3.3.1](#overview) Overview [[array.overview]](array.overview)

[1](#overview-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6108)

The header [<array>](array.syn#header:%3carray%3e "23.3.2 Header <array> synopsis [array.syn]") defines a class template for storing fixed-size
sequences of objects[.](#overview-1.sentence-1)

An array is a [contiguous container](container.reqmts#def:container,contiguous "23.2.2.2 Container requirements [container.reqmts]")[.](#overview-1.sentence-2)

An instance of array<T, N> stores N elements of type T,
so that size() == N is an invariant[.](#overview-1.sentence-3)

[2](#overview-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6116)

An array is an [aggregate](dcl.init.aggr#def:aggregate "9.5.2 Aggregates [dcl.init.aggr]") that can be
list-initialized with up
to N elements whose types are convertible to T[.](#overview-2.sentence-1)

[3](#overview-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6123)

An array meets all of the requirements
of a container ([[container.reqmts]](container.reqmts "23.2.2.2 Container requirements")) and
of a reversible container ([[container.rev.reqmts]](container.rev.reqmts "23.2.2.3 Reversible container requirements")),
except that a default
constructed array object is not empty if N>0[.](#overview-3.sentence-1)

An array meets some of the requirements of a[sequence container](sequence.reqmts "23.2.4 Sequence containers [sequence.reqmts]")[.](#overview-3.sentence-2)

Descriptions are provided here
only for operations on array that are not described in
one of these tables and
for operations where there is additional semantic information[.](#overview-3.sentence-3)

[4](#overview-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6137)

array<T, N> is a structural type ([[temp.param]](temp.param#term.structural.type "13.2 Template parameters")) ifT is a structural type[.](#overview-4.sentence-1)

Two values a1 and a2 of type array<T, N> are [template-argument-equivalent](temp.type#def:template-argument-equivalent "13.6 Type equivalence [temp.type]") if and only if
each pair of corresponding elements in a1 and a2 are template-argument-equivalent[.](#overview-4.sentence-2)

[5](#overview-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6145)

The types iterator and const_iterator meet
the [constexpr iterator](iterator.requirements.general#def:iterator,constexpr "24.3.1 General [iterator.requirements.general]") requirements[.](#overview-5.sentence-1)

[🔗](#lib:array_)

namespace std {template<class T, size_t N>struct array {// typesusing value_type = T; using pointer = T*; using const_pointer = const T*; using reference = T&; using const_reference = const T&; using size_type = size_t; using difference_type = ptrdiff_t; using iterator = *implementation-defined*; // see [[container.requirements]](container.requirements "23.2 Requirements")using const_iterator = *implementation-defined*; // see [[container.requirements]](container.requirements "23.2 Requirements")using reverse_iterator = std::reverse_iterator<iterator>; using const_reverse_iterator = std::reverse_iterator<const_iterator>; // no explicit construct/copy/destroy for aggregate typeconstexpr void fill(const T& u); constexpr void swap(array&) noexcept(is_nothrow_swappable_v<T>); // iteratorsconstexpr iterator begin() noexcept; constexpr const_iterator begin() const noexcept; constexpr iterator end() noexcept; constexpr const_iterator end() const noexcept; constexpr reverse_iterator rbegin() noexcept; constexpr const_reverse_iterator rbegin() const noexcept; constexpr reverse_iterator rend() noexcept; constexpr const_reverse_iterator rend() const noexcept; constexpr const_iterator cbegin() const noexcept; constexpr const_iterator cend() const noexcept; constexpr const_reverse_iterator crbegin() const noexcept; constexpr const_reverse_iterator crend() const noexcept; // capacityconstexpr bool empty() const noexcept; constexpr size_type size() const noexcept; constexpr size_type max_size() const noexcept; // element accessconstexpr reference operator[](size_type n); constexpr const_reference operator[](size_type n) const; constexpr reference at(size_type n); // freestanding-deletedconstexpr const_reference at(size_type n) const; // freestanding-deletedconstexpr reference front(); constexpr const_reference front() const; constexpr reference back(); constexpr const_reference back() const; constexpr T* data() noexcept; constexpr const T* data() const noexcept; }; template<class T, class... U> array(T, U...) -> array<T, 1 + sizeof...(U)>;}

#### [23.3.3.2](#cons) Constructors, copy, and assignment [[array.cons]](array.cons)

[1](#cons-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6218)

An array relies on the implicitly-declared special
member functions ([[class.default.ctor]](class.default.ctor "11.4.5.2 Default constructors"), [[class.dtor]](class.dtor "11.4.7 Destructors"), [[class.copy.ctor]](class.copy.ctor "11.4.5.3 Copy/move constructors")) to
conform to the container requirements table in [[container.requirements]](container.requirements "23.2 Requirements")[.](#cons-1.sentence-1)

In addition to the requirements specified in the container requirements table,
the implicitly-declared move constructor and move assignment operator for array require that T be *Cpp17MoveConstructible* or *Cpp17MoveAssignable*,
respectively[.](#cons-1.sentence-2)

[🔗](#cons-itemdecl:1)

`template<class T, class... U>
  array(T, U...) -> array<T, 1 + sizeof...(U)>;
`

[2](#cons-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6234)

*Mandates*: (is_same_v<T, U> && ...) is true[.](#cons-2.sentence-1)

#### [23.3.3.3](#members) Member functions [[array.members]](array.members)

[🔗](#lib:array,size_)

`constexpr size_type size() const noexcept;
`

[1](#members-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6247)

*Returns*: N[.](#members-1.sentence-1)

[🔗](#lib:array,data)

`constexpr T* data() noexcept;
constexpr const T* data() const noexcept;
`

[2](#members-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6259)

*Returns*: A pointer such that [data(), data() + size()) is a valid range[.](#members-2.sentence-1)

For a
non-empty array, data() == addressof(front()) is true[.](#members-2.sentence-2)

[🔗](#lib:array,fill)

`constexpr void fill(const T& u);
`

[3](#members-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6271)

*Effects*: As if by fill_n(begin(), N, u)[.](#members-3.sentence-1)

[🔗](#lib:array,swap)

`constexpr void swap(array& y) noexcept(is_nothrow_swappable_v<T>);
`

[4](#members-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6282)

*Effects*: Equivalent to swap_ranges(begin(), end(), y.begin())[.](#members-4.sentence-1)

[5](#members-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6286)

[*Note [1](#members-note-1)*:

Unlike the swap function for other containers, array​::​swap takes linear time, can exit via an exception, and does not cause iterators to
become associated with the other container[.](#members-5.sentence-1)

— *end note*]

#### [23.3.3.4](#special) Specialized algorithms [[array.special]](array.special)

[🔗](#lib:array,swap_)

`template<class T, size_t N>
  constexpr void swap(array<T, N>& x, array<T, N>& y) noexcept(noexcept(x.swap(y)));
`

[1](#special-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6303)

*Constraints*: N == 0 or is_swappable_v<T> is true[.](#special-1.sentence-1)

[2](#special-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6307)

*Effects*: As if by x.swap(y)[.](#special-2.sentence-1)

[3](#special-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6311)

*Complexity*: Linear in N[.](#special-3.sentence-1)

#### [23.3.3.5](#zero) Zero-sized arrays [[array.zero]](array.zero)

[1](#zero-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6319)

array shall provide support for the special case N == 0[.](#zero-1.sentence-1)

[2](#zero-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6322)

In the case that N == 0, begin() == end() == unique value[.](#zero-2.sentence-1)

The return value of data() is unspecified[.](#zero-2.sentence-2)

[3](#zero-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6326)

The effect of calling front() or back() for a zero-sized array is
undefined[.](#zero-3.sentence-1)

[4](#zero-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6330)

Member function swap() shall have a
non-throwing exception specification[.](#zero-4.sentence-1)

#### [23.3.3.6](#creation) Array creation functions [[array.creation]](array.creation)

[🔗](#lib:to_array)

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

[1](#creation-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6344)

*Mandates*: is_array_v<T> is false andis_constructible_v<remove_cv_t<T>, T&> is true[.](#creation-1.sentence-1)

[2](#creation-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6349)

*Preconditions*: T meets the *Cpp17CopyConstructible* requirements[.](#creation-2.sentence-1)

[3](#creation-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6353)

*Returns*: {{ a[0], …, a[N - 1] }}[.](#creation-3.sentence-1)

[🔗](#lib:to_array_)

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

[4](#creation-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6365)

*Mandates*: is_array_v<T> is false andis_constructible_v<remove_cv_t<T>, T> is true[.](#creation-4.sentence-1)

[5](#creation-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6370)

*Preconditions*: T meets the *Cpp17MoveConstructible* requirements[.](#creation-5.sentence-1)

[6](#creation-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6374)

*Returns*: {{ std​::​move(a[0]), …, std​::​move(a[N - 1]) }}[.](#creation-6.sentence-1)

#### [23.3.3.7](#tuple) Tuple interface [[array.tuple]](array.tuple)

[🔗](#lib:array__)

`template<class T, size_t N>
  struct tuple_size<array<T, N>> : integral_constant<size_t, N> { };
`

[🔗](#lib:tuple_element)

`template<size_t I, class T, size_t N>
  struct tuple_element<I, array<T, N>> {
    using type = T;
  };
`

[1](#tuple-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6398)

*Mandates*: I < N is true[.](#tuple-1.sentence-1)

[🔗](#lib:array,get)

`template<size_t I, class T, size_t N>
  constexpr T& get(array<T, N>& a) noexcept;
template<size_t I, class T, size_t N>
  constexpr T&& get(array<T, N>&& a) noexcept;
template<size_t I, class T, size_t N>
  constexpr const T& get(const array<T, N>& a) noexcept;
template<size_t I, class T, size_t N>
  constexpr const T&& get(const array<T, N>&& a) noexcept;
`

[2](#tuple-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6416)

*Mandates*: I < N is true[.](#tuple-2.sentence-1)

[3](#tuple-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L6420)

*Returns*: A reference to the Ith element of a,
where indexing is zero-based[.](#tuple-3.sentence-1)