std::array in C++: how to declare and use one

std::array in C++ is a fixed-size container from the <array> header: std::array<int, 3> scores{72, 95, 41}; holds exactly three ints. It wraps a built-in array and adds what that lacks: scores.size(), a checked scores.at(i), and the ability to be copied, compared and returned. Its size never changes; for one that grows, use std::vector.

A whole program that declares one, asks its size, prints each element and changes one:

#include <array>
#include <iostream>

int main() {
    std::array<int, 3> scores{72, 95, 41};

    std::cout << scores.size() << '\n';  // 3

    for (int score : scores) {
        std::cout << score << '\n';  // 72, then 95, then 41
    }

    scores[2] = 60;
    std::cout << scores[2] << '\n';  // 60
}

It printed:

3
72
95
41
60

The samples are C++17, built with MSVC 19.44, Clang 19.1 (MSVC STL), GCC 16.2 and Clang 23.1 (libc++), and this program printed the same on all four. std::array itself has been in the standard since C++11. Since When lists, for each standard, the first compiler releases that support it.

How do you declare and initialize a std::array?

Write the element type and the size in the angle brackets, then the values in braces. Since C++17 the compiler can also work both out from the values, which is called class template argument deduction:

std::array<int, 3> all{72, 95, 41};  // 72, 95, 41
std::array<int, 3> two{72, 95};      // 72, 95, 0
std::array<int, 3> none{};           // 0, 0, 0
// ...
std::array scores{72, 95, 41};  // C++17: type and size worked out
bool same = std::is_same_v<decltype(scores), std::array<int, 3>>;
std::cout << std::boolalpha << same << '\n';  // true

Printed one per line, all four gave 72, 95, 41, then 72, 95, 0, then three zeros, then true. std::is_same_v is true when two types are the same, so the deduced scores is a std::array<int, 3>.

The standard makes std::array an aggregate, a type filled straight from a braced list, that takes “up to N elements” ([array.overview]). So:

• Fewer values than the size: the remaining ints are 0.
• Empty braces, {}: every element is 0.
• More values than the size: it does not compile. GCC says too many initializers for 'std::array<int, 3>', and the other three refuse it too.

C++20 adds std::to_array, which builds a std::array from a braced list or a built-in array and counts the elements for you:

auto scores = std::to_array({72, 95, 41});  // C++20

All four compiled it as C++20 and rejected it as C++17.

How do you get the size of a std::array?

Call size(): scores.size() returns 3, the number of elements. empty(), front() and back() answer the next questions, whether it has none and what the first and last elements are, and data() gives a pointer to the first element, for a C function that takes one.

std::cout << std::boolalpha;
std::cout << scores.size() << '\n';   // 3
std::cout << scores.empty() << '\n';  // false
std::cout << scores.front() << '\n';  // 72
std::cout << scores.back() << '\n';   // 41

// the size is part of the type: these are two different types
bool same = std::is_same_v<std::array<int, 3>, std::array<int, 4>>;
std::cout << std::boolalpha << same << '\n';  // false

All four printed 3, false, 72 and 41, then false for the two types. The size is written into the type, so an array’s size is fixed when you write the code. There is no push_back.

std::array [] vs at(): which is safe?

at() is: it checks the index and throws std::out_of_range, an exception, when the index is not less than size() (cppreference on std::array::at). [] is not required to check. An index past the end is undefined behavior, which means the standard promises nothing about what the program does (cppreference on the subscript operator). You catch the exception with try and catch:

std::cout << scores.at(1) << '\n';  // 95

try {
    std::cout << scores.at(3) << '\n';  // there is no index 3
} catch (const std::out_of_range&) {
    std::cout << "index 3 is out of range\n";
}

All four printed 95, then index 3 is out of range. The sample prints a message of its own because each standard library words the exception’s what() text differently. Use at() when the index comes from outside the program, such as user input or a file, and [] in a loop that stays below size().

How do you loop over a std::array and pass it to a function?

A range-for, the loop for (int score : scores) in the first program, visits every element in order. To pass one to a function, write its whole type and take it by const reference, which reads the caller’s array without copying it:

int total(const std::array<int, 3>& values) {
    int sum = 0;
    for (int v : values) {
        sum += v;
    }
    return sum;
}

int main() {
    std::array<int, 3> scores{72, 95, 41};
    // ...
    std::cout << total(scores) << '\n';  // 208
}

All four printed 208. For an array of any size, make the function a template on the size N, with the same body; the compiler works N out from the array you pass:

template <std::size_t N>
int total(const std::array<int, N>& values) {
    // ...
}

int main() {
    std::array<int, 3> scores{72, 95, 41};
    std::array<int, 5> more{72, 95, 41, 60, 88};
    std::cout << total(scores) << '\n';  // 208, with N = 3
    std::cout << total(more) << '\n';    // 356, with N = 5
}

It printed 208 and 356 on all four. Since C++20 a function can take std::span, a view that replaces a pointer and a size, instead of the template.

What can a std::array do that a built-in array cannot?

A std::array behaves like a struct holding a built-in array, so it can be returned from a function and assigned with =; the library also gives it ==, which compares the elements with their own ==:

std::array<int, 3> make_scores() {
    return {72, 95, 41};
}

int main() {
    std::array<int, 3> scores = make_scores();
    std::array<int, 3> copy{};
    copy = scores;  // copies all three elements
    std::cout << copy[1] << '\n';  // 95
    std::cout << std::boolalpha << (copy == scores) << '\n';  // true
}

All four printed 95 and true: = copied the three elements, and == compared them value by value. A built-in array refuses the same assignment. copy = scores; on two int[3] arrays does not compile, and Clang says array type 'int[3]' is not assignable. The built-in C++ array has the rest, including why it loses its length when passed to a function.

std::array vs vector: which should you use?

Use std::array when you know the number of elements as you write the code and it never changes, and std::vector for anything else. The difference is where the elements live:

A std::array is its elements: sizeof(std::array<int, 3>) and sizeof(int[3]) both printed 12 on all four, so the wrapper adds no bytes here. A vector holds, in effect, a pointer, a size and a capacity, and its elements live elsewhere, in memory it can reallocate to grow.

Standard library has the rest of the site’s container answers.