std::array

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Containers library

Sequence

array (C++11)

vector

vector<bool>

inplace_vector (C++26)

deque

forward_list (C++11)

list

Associative

set

multiset

map

multimap

Unordered associative

unordered_set (C++11)

unordered_multiset (C++11)

unordered_map (C++11)

unordered_multimap (C++11)

Adaptors

stack

queue

priority_queue

flat_set (C++23)

flat_multiset (C++23)

flat_map (C++23)

flat_multimap (C++23)

Views

span (C++20)

mdspan (C++23)

Tables

Iterator invalidation

Member function table

Non-member function table

 

std::array

Member types
Member functions
Element access array::at array::operator[]    array::front array::back array::data Operations array::fill array::swap	Iterators array::beginarray::cbegin array::endarray::cend array::rbeginarray::crbegin    array::rendarray::crend	Capacity array::empty array::size array::max_size
Non-member functions
operator==operator<=> (C++20) get(std::array) swap(std::array) to_array (C++20)	operator|=operator<operator>operator<=operator>= (until C++20)(until C++20)(until C++20)(until C++20)(until C++20)
Helper classes
tuple_size<std::array>
tuple_element<std::array>
Deduction guides (C++17)

 

Defined in header <array>
template<     class T,     std::size_t N > struct array;		(since C++11)

std::array is a container that encapsulates constant size arrays.

This container is an aggregate type with the same semantics as a struct holding a C-style array T[N] as its only non-static data member. It can be initialized with aggregate-initialization, given at most N initializers that are convertible to T: std::array<int, 3> a = {1,2,3};

The struct combines the performance and accessibility of a C-style array with the benefits of a standard container, such as knowing its own size, supporting assignment, random access iterators, etc.

There is a special case for a zero-length array (N == 0). In that case, array.begin() == array.end(), which is some unique value. The effect of calling front() or back() on a zero-sized array is undefined.

An array can also be used as a tuple of N elements of the same type.

Member types

Member type	Definition
value_type	T
size_type	std::size_t
difference_type	std::ptrdiff_t
reference	value_type&
const_reference	const value_type&
pointer	value_type*
const_pointer	const value_type*
iterator	LegacyRandomAccessIterator and LegacyContiguousIterator to value_type (until C++17) LegacyRandomAccessIterator and LegacyContiguousIterator that is a LiteralType to value_type (since C++17) (until C++20) LegacyRandomAccessIterator, contiguous_iterator, and ConstexprIterator to value_type (since C++20)
const_iterator	LegacyRandomAccessIterator and LegacyContiguousIterator to const value_type (until C++17) LegacyRandomAccessIterator and LegacyContiguousIterator that is a LiteralType to const value_type (since C++17) (until C++20) LegacyRandomAccessIterator, contiguous_iterator, and ConstexprIterator to const value_type (since C++20)
reverse_iterator	std::reverse_iterator<iterator>
const_reverse_iterator	std::reverse_iterator<const_iterator>

Member functions

Implicitly-defined member functions
(constructor) (implicitly declared)	default-constructs or copy-constructs every element of the array (public member function)
(destructor) (implicitly declared)	destroys every element of the array (public member function)
operator= (implicitly declared)	overwrites every element of the array with the corresponding element of another array (public member function)
Element access
at	access specified element with bounds checking (public member function)
operator[]	access specified element (public member function)
front	access the first element (public member function)
back	access the last element (public member function)
data	direct access to the underlying contiguous storage (public member function)
Iterators
begincbegin	returns an iterator to the beginning (public member function)
endcend	returns an iterator to the end (public member function)
rbegincrbegin	returns a reverse iterator to the beginning (public member function)
rendcrend	returns a reverse iterator to the end (public member function)
Capacity
empty	checks whether the container is empty (public member function)
size	returns the number of elements (public member function)
max_size	returns the maximum possible number of elements (public member function)
Operations
fill	fill the container with specified value (public member function)
swap	swaps the contents (public member function)

Non-member functions

operator==operator!=operator<operator<=operator>operator>=operator<=> (C++11)(C++11)(removed in C++20)(C++11)(removed in C++20)(C++11)(removed in C++20)(C++11)(removed in C++20)(C++11)(removed in C++20)(C++20)	lexicographically compares the values of two arrays (function template)
get(std::array) (C++11)	accesses an element of an array (function template)
std::swap(std::array) (C++11)	specializes the std::swap algorithm (function template)

Helper classes

std::tuple_size<std::array> (C++11)	obtains the size of an array (class template specialization)
std::tuple_element<std::array> (C++11)	obtains the type of the elements of array (class template specialization)

Example

Run this code

#include <string>
#include <iterator>
#include <iostream>
#include <algorithm>
#include <array>
 
int main()
{
    // construction uses aggregate initialization
    std::array<int, 3> a1{ {1,2,3} };  // double-braces required
    std::array<int, 3> a2 = {1, 2, 3}; // except after =
    std::array<std::string, 2> a3 = { {std::string("a"), "b"} };
 
    // container operations are supported
    std::sort(a1.begin(), a1.end());
    std::reverse_copy(a2.begin(), a2.end(), 
                      std::ostream_iterator<int>(std::cout, " "));
 
    std::cout << std::endl;
 
    // ranged for loop is supported
    for(auto& s: a3)
        std::cout << s << ' ';
}

Output:

3 2 1 
a b