std::array (3) - Linux Manuals

std::array: std::array

NAME

std::array - std::array

Synopsis

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

std::array is a container that encapsulates fixed 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. Unlike a C-style array, it doesn't decay to T* automatically. As an aggregate type, 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.
std::array satisfies the requirements of Container and ReversibleContainer except that default-constructed array is not empty and that the complexity of swapping is linear,
satisfies the requirements of ContiguousContainer,
(since C++17) and partially satisfies the requirements of SequenceContainer.
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.

Iterator invalidation

As a rule, iterators to an array are never invalidated throughout the lifetime of the array. One should take note, however, that during swap, the iterator will continue to point to the same array element, and will thus change its value.

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*
                       LegacyRandomAccessIterator
                       and ConstexprIterator
iterator (since C++20)
                       that is a LiteralType
                       (since C++17)
                       Constant LegacyRandomAccessIterator
                       and ConstexprIterator
const_iterator (since C++20)
                       that is a LiteralType
                       (since C++17)
reverse_iterator std::reverse_iterator<iterator>
const_reverse_iterator std::reverse_iterator<const_iterator>

Member functions

Implicitly-defined member functions

constructor initializes the array following the rules of aggregate_initialization (note that default initialization may result in indeterminate values for non-class T)
                      (public member function)
(implicitly declared)

destructor destroys every element of the array
                      (public member function)
(implicitly declared)

operator= overwrites every element of the array with the corresponding element of another array
                      (public member function)
(implicitly declared)

Element access

                      access specified element with bounds checking
at (public member function)
                      access specified element
operator[] (public member function)
                      access the first element
front (public member function)
                      access the last element
back (public member function)
                      direct access to the underlying array
data (public member function)

Iterators

begin returns an iterator to the beginning
cbegin (public member function)

end_ returns an iterator to the end
cend (public member function)

rbegin returns a reverse iterator to the beginning
crbegin (public member function)

rend returns a reverse iterator to the end
crend (public member function)

Capacity

                      checks whether the container is empty
empty (public member function)
                      returns the number of elements
size (public member function)
                      returns the maximum possible number of elements
max_size (public member function)

Operations

                      fill the container with specified value
fill (public member function)
                      swaps the contents
swap (public member function)

Non-member functions

operator==
operator!= lexicographically compares the values in the array
operator< (function template)
operator<=
operator>
operator>=
                      accesses an element of an array
std::get(std::array) (function template)

std::swap(std::array) specializes the std::swap algorithm
                      (function template)
(C++11)

Helper classes

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

Deduction_guides(since C++17)

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 in C++11 prior to the CWG 1270 revision
                                          // (not needed in C++11 after the revision and in C++14 and beyond)
      std::array<int, 3> a2 = {1, 2, 3}; // never required 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 << '\n';

      // ranged for loop is supported
      for(const auto& s: a3)
          std::cout << s << ' ';
  }

Output:

  3 2 1
  a b