std::array for fixed-size sequences

Understanding std::array for fixed-size sequences

std::array<T, N> is a class template whose entire state is one C array member, roughly T elems[N]. Nothing is allocated: the elements sit inside the object, so a local std::array lives on the stack, a static one in static storage, and a member one inside its owner. There is no size field either, because N is a template argument the compiler already knows, which is why sizeof(std::array<int, 5>) is exactly 5 * sizeof(int) and why size() is a constant expression. The mental model is a raw array that finally has the member functions, iterators, and copy semantics you expect from a container.

Because N lives in the type, std::array<int, 3> and std::array<int, 4> are as unrelated as int and double. That rules out push_back and resize, and it means a function parameter pins the length unless you template on it, as in template <std::size_t N> void f(const std::array<int, N>&), or take a std::span. In exchange the length is usable in constant expressions: static_assert(a.size() == 3), std::get<2>(a) with a compile-time-checked index, structured bindings, and tables computed entirely at compile time.

std::array also fixes what raw arrays get wrong: it assigns, copies, compares, and can be returned from a function by value, and it never decays to a pointer, so the length survives every call. The flip side is that a by-value parameter copies all N elements, and swap() is an O(N) element-wise exchange rather than the pointer swap a heap-backed container performs, because there is no buffer to hand over. Initialization follows aggregate rules: braces list the initial values, missing ones are value-initialized, and a declaration with no braces at all leaves trivially-typed elements indeterminate.

Reach for std::array whenever the count is known while you are writing the code, and for a vector when it is not.

#include <array>
#include <iostream>
#include <numeric>
#include <stdexcept>

// N is a template parameter, so one function handles every length
// and no separate count argument is needed.
template <std::size_t N>
int sum(const std::array<int, N>& a) {
    return std::accumulate(a.begin(), a.end(), 0);
}

int main() {
    std::array<int, 5> primes{2, 3, 5, 7, 11};

    std::cout << std::boolalpha;
    std::cout << "size: " << primes.size() << '\n';
    std::cout << "elements only: " << (sizeof(primes) == 5 * sizeof(int)) << '\n';
    std::cout << "ends: " << primes.front() << ' ' << primes.back() << '\n';
    std::cout << "sum: " << sum(primes) << '\n';

    std::array<int, 5> other = primes;   // copies all five ints
    other[0] = 99;
    std::cout << "original untouched: " << primes[0] << '\n';

    try {
        std::cout << primes.at(5) << '\n';   // [] here would be silent UB
    } catch (const std::out_of_range&) {
        std::cout << "at(5) threw out_of_range\n";
    }
}

Worked examples

#include <array>
#include <iostream>

// C++17: a constexpr function can fill and return a std::array,
// so this table exists before the program starts running.
constexpr std::array<int, 6> squares() {
    std::array<int, 6> t{};                  // {} zeroes; without it the ints are indeterminate
    for (std::size_t i = 0; i < t.size(); ++i)
        t[i] = static_cast<int>(i * i);
    return t;
}

int main() {
    constexpr auto table = squares();
    static_assert(table.size() == 6);
    static_assert(table[4] == 16);

    for (std::size_t i = 0; i < table.size(); ++i)
        std::cout << (i == 0 ? "" : " ") << table[i];
    std::cout << '\n' << std::get<3>(table) << '\n';
}

#include <algorithm>
#include <array>
#include <iostream>

// A C-style interface: pointer plus length.
long total(const int* p, std::size_t n) {
    long s = 0;
    for (std::size_t i = 0; i < n; ++i) s += p[i];
    return s;
}

int main() {
    std::array a{5, 1, 4};                 // C++17 deduces std::array<int, 3>
    std::sort(a.begin(), a.end());
    std::cout << a[0] << a[1] << a[2] << '\n';

    std::cout << total(a.data(), a.size()) << '\n';

    std::array<int, 3> b{9, 9, 9};
    a.swap(b);                             // element-wise, O(N)
    std::cout << a[0] << ' ' << b[0] << '\n';

    auto [x, y, z] = b;
    std::cout << x + y + z << '\n';
}

#include <array>
#include <iostream>

int main() {
    // 2 rows of 3: six ints in one block, no pointers between rows.
    std::array<std::array<int, 3>, 2> grid{{{1, 2, 3}, {4, 5, 6}}};

    std::cout << grid[1][2] << '\n';
    std::cout << (sizeof(grid) == 6 * sizeof(int) ? "packed" : "padded") << '\n';

    for (const auto& row : grid) {
        for (int v : row) std::cout << v;
        std::cout << '\n';
    }
}

Important notes

Common mistakes

Try it yourself