Class template array

boost::array — A container that encapsulates fixed size arrays.

Synopsis

// In header: <boost/array.hpp>

template<typename T, std::size_t N> 
class array {
public:
  // types
  typedef T                                       value_type;            
  typedef T *                                     iterator;                // Iterator to C-style array, i.e. a pointer. 
  typedef const T *                               const_iterator;          // Constant iterator to array, i.e. a pointer. 
  typedef T &                                     reference;               // Reference to value type. 
  typedef const T &                               const_reference;         // Constant reference to value type. 
  typedef std::size_t                             size_type;               // Type used to represent array size. 
  typedef std::ptrdiff_t                          difference_type;         // Type used to represent distance between iterators. 
  typedef std::reverse_iterator< iterator >       reverse_iterator;      
  typedef std::reverse_iterator< const_iterator > const_reverse_iterator;  // Constant reverse array iterator - std::reverse_iterator<const_iterator> 

  // construct/copy/destruct
  template<typename T2> array< T, N > & operator=(const array< T2, N > &);

  // public member functions
  iterator begin();
  const_iterator begin() const;
  const_iterator cbegin() const;
  iterator end();
  const_iterator end() const;
  const_iterator cend() const;
  reverse_iterator rbegin();
  const_reverse_iterator rbegin() const;
  const_reverse_iterator crbegin() const;
  reverse_iterator rend();
  const_reverse_iterator rend() const;
  const_reverse_iterator crend() const;
  reference operator[](size_type);
  const_reference operator[](size_type) const;
  reference at(size_type);
  const_reference at(size_type) const;
  reference front();
  constexpr const_reference front() const;
  reference back();
  constexpr const_reference back() const;
  void swap(array< T, N > &);
  const T * data() const;
  T * data();
  T * c_array();
  void assign(const T &);
  void fill(const T &);

  // public static functions
  static constexpr size_type size();
  static constexpr bool empty();
  static constexpr size_type max_size();
  static constexpr bool rangecheck(size_type);

  // public data members
  T elems;  // Underlying fixed-size array of elements of type T. 
};

Description

This class represents a container that encapsulates fixed size arrays.

It has the same semantics as a struct holding a C-style array T[N]. Unlike a C-style array, it doesn't decay to T* automatically.

The class combines the performance of a C-style array with the convenience of a standard container.

There is a special case for a zero-length array (N == 0). In that case, array.begin() == array.end(), which is some unique value.

Thread Safety.

Not thread safe

See Also:

std::vector

Template Parameters

```
typename T
```
The array value type
```
std::size_t N
```
The array size

`array` public types

typedef T value_type;

The array value type
typedef std::reverse_iterator< iterator > reverse_iterator;

Reverse array iterator - std::reverse_iterator<iterator>

`array` public construct/copy/destruct

```
template<typename T2> array< T, N > & operator=(const array< T2, N > & rhs);
```
Member group: Assignment with type conversion.
Overwrites element of the array with elements of another array

This function overwrites every element of the this array with the corresponding elements of another array

Complexity.

Linear

See Also:

assign

Returns:

Pointer to this array

`array` public member functions

```
iterator begin();
```
Member group: Iterators.
Returns an iterator to the beginning

This function returns an iterator to the first element of the array.

Complexity.

Constant

Note

If the array is empty, the returned iterator will be equal to end()

See Also:

end

Returns:

Iterator to the first element of the array
```
const_iterator begin() const;
```
Returns a constant iterator to the beginning.
This function returns a constant iterator to the first element of the array. This is the overload that gets called when this is constant.

Complexity.

Constant

Note

If the array is empty, the returned iterator will be equal to end()

See Also:

end

Returns:

Iterator to the first element of the array
```
const_iterator cbegin() const;
```
Returns a constant iterator to the beginning.
This function returns a constant iterator to the first element of the array.

This function is usually called to provide a constant iterator when this is not constant.

Complexity.

Constant

Note

If the array is empty, the returned iterator will be equal to end() @return Iterator to the first element of the array

See Also:

end
```
iterator end();
```
Returns an iterator to the end.
This function returns an iterator to the element following the last element of the array

Complexity.

Constant

Note

If the array is empty, the returned iterator will be equal to end()

See Also:

begin

Returns:

Iterator to the element following the last element of the array
```
const_iterator end() const;
```
Returns a constant iterator to the end.
This function returns a constant iterator to the first element of the array.

This function overload gets called when this is constant.

Complexity.

Constant

Note

If the array is empty, the returned iterator will be equal to end()

See Also:

begin

Returns:

Iterator to the element following the last element of the array
```
const_iterator cend() const;
```
Returns a constant iterator to the end.
This function returns a constant iterator to the element following the last element of the array.

This function is usually called to provide a constant iterator when this is not constant.

Complexity.

Constant

Note

If the array is empty, the returned iterator will be equal to end()

See Also:

cbegin

Returns:

Iterator to the element following the last element of the array
```
reverse_iterator rbegin();
```
Member group: Iterators.
Returns a reverse iterator to the beginning

Returns a reverse iterator to the first element of the reversed array.

This reverse iterator corresponds to the last element of the non-reversed array.

Complexity.

Constant

Note

If the array is empty, the returned iterator is equal to rend().

See Also:

rend

Returns:

Reverse iterator to the first element of the reversed array
```
const_reverse_iterator rbegin() const;
```
Returns a constant reverse iterator to the beginning.
Returns a reverse iterator to the first element of the reversed array.

This reverse iterator corresponds to the last element of the non-reversed array.

This function overload gets called when this is constant.

Complexity.

Constant

Note

If the array is empty, the returned iterator is equal to rend().

See Also:

rend

Returns:

Reverse iterator to the first element of the reversed array
```
const_reverse_iterator crbegin() const;
```
Returns a reverse iterator to the beginning.
Returns a reverse iterator to the first element of the reversed array.

This reverse iterator corresponds to the last element of the non-reversed array.

This function is usually called to provide a constant iterator when this is not constant.

Complexity.

Constant

Note

If the array is empty, the returned iterator is equal to rend().

See Also:

rend

Returns:

Reverse iterator to the first element of the reversed array
```
reverse_iterator rend();
```
Returns a reverse iterator to the end.
Returns a reverse iterator to the element following the last element of the reversed array.

This iterator corresponds to the element preceding the first element of the non-reversed array.

This element acts as a placeholder. Attempting to access it results in undefined behavior.

Complexity.

Constant

Note

If the array is empty, the returned iterator is equal to rend().

See Also:

rend

Returns:

Reverse iterator to the first element of the reversed array
```
const_reverse_iterator rend() const;
```
Returns a constant reverse iterator to the end.
Returns a reverse iterator to the element following the last element of the reversed array.

This iterator corresponds to the element preceding the first element of the non-reversed array.

This element acts as a placeholder. Attempting to access it results in undefined behavior.

This function overload gets called when this is constant.

Complexity.

Constant

Note

If the array is empty, the returned iterator is equal to rend().

See Also:

rend

Returns:

Reverse iterator to the first element of the reversed array
```
const_reverse_iterator crend() const;
```
Returns a constant reverse iterator to the end.
Returns a reverse iterator to the element following the last element of the reversed array.

This iterator corresponds to the element preceding the first element of the non-reversed array.

This element acts as a placeholder. Attempting to access it results in undefined behavior.

This function is usually called to provide a constant iterator when this is not constant.

Complexity.

Constant

Note

If the array is empty, the returned iterator is equal to rend().

See Also:

rend

Returns:

Reverse iterator to the first element of the reversed array
```
reference operator[](size_type i);
```
Member group: Element access.
Access specified element

This function Returns a reference to the element at specified location i.

No bounds checking is performed.

Complexity.

Constant

Preconditions.

!(i < size())

Note

Unlike std::map::operator[], this operator never inserts a new element into the container.

Accessing a nonexistent element through this operator is undefined behavior.

See Also:

at

Parameters:

i

Position of the element to return

Returns:

Reference to the requested element.
```
const_reference operator[](size_type i) const;
```
Access specified element.
This function Returns a reference to the element at specified location i.

No bounds checking is performed.

This overload gets called when this is constant.

Complexity.

Constant

Preconditions.

!(i < size())

Note

Unlike std::map::operator[], this operator never inserts a new element into the container.

Accessing a nonexistent element through this operator is undefined behavior.

See Also:

at

Parameters:

i

Position of the element to return

Returns:

Reference to the requested element.
```
reference at(size_type i);
```
Access specified element with bounds checking.
This function Returns a reference to the element at specified location i, with bounds checking.

If pos is not within the range of the container, an exception of type std::out_of_range is thrown.

Complexity.

Constant

Preconditions.

!(i < size())

Exception Safety.

std::out_of_range if !(i < size()).

See Also:

operator[]

Parameters:

i

Position of the element to return

Returns:

Reference to the requested element.
```
const_reference at(size_type i) const;
```
Access specified element with bounds checking.
This function Returns a reference to the element at specified location i, with bounds checking.

If pos is not within the range of the container, an exception of type std::out_of_range is thrown.

This overload gets called when this is constant.

Complexity.

Constant

Preconditions.

!(i < size())

Exception Safety.

std::out_of_range if !(i < size()).

See Also:

operator[]

Parameters:

i

Position of the element to return

Returns:

Reference to the requested element.
```
reference front();
```
Access the first array element.
This function returns a reference to the first element in the container.

Calling front on an empty container is undefined.

Complexity.

Constant

Note

c.front() is equivalent to *c.begin()

Preconditions.

!(empty())

See Also:

operator[], at, begin, end

Returns:

Reference to the first array element.
```
constexpr const_reference front() const;
```
Access the first array element.
This function returns a reference to the first element in the container.

Calling front on an empty container is undefined.

This overload gets called when this is constant.

Complexity.

Constant

Note

c.front() is equivalent to *c.begin()

Preconditions.

!(empty())

See Also:

operator[], at, begin, end

Returns:

Reference to the first array element.
```
reference back();
```
Access the last array element.
This function returns a reference to the last element in the container.

Calling front on an empty container is undefined.

Complexity.

Constant

Note

c.back() is equivalent to *stdprev(c.end())

Preconditions.

!(empty())

See Also:

operator[], at, begin, end

Returns:

Reference to the last array element.
```
constexpr const_reference back() const;
```
Access the last array element.
This function returns a reference to the last element in the container.

Calling front on an empty container is undefined.

This overload gets called when this is constant.

Complexity.

Constant

Note

c.back() is equivalent to *stdprev(c.end())

Preconditions.

!(empty())

See Also:

operator[], at, begin, end

Returns:

Reference to the last array element.
```
void swap(array< T, N > & y);
```
Member group: Swap.
Swaps the container contents

Exchanges the contents of the container with those of other.

This function does not cause iterators and references to associate with the other container.

Complexity.

Linear

Note

Because array<T, N> is not dynamically allocated, this operation has linear complexity.

See Also:

fill, std::swap

Parameters:

y

container to exchange the contents with

Returns:

(none)
```
const T * data() const;
```
Member group: Direct access to data.
Direct access to the underlying array

Returns pointer to the underlying array serving as element storage.

This overload gets called when this is constant.

Complexity.

Constant

Note

The pointer is such that range [data(); data() + size()) is always a valid range, even if the container is empty.

When the container is empty, data() is not dereferenceable.

If size() is 0, data() may or may not return a null pointer.

For non-empty containers, the returned pointer compares equal to the address of the first element.

See Also:

front, back, size

Returns:

Pointer to the underlying element storage
```
T * data();
```
Direct access to the underlying array.
Returns pointer to the underlying array serving as element storage.

Complexity.

Constant

Note

The pointer is such that range [data(); data() + size()) is always a valid range, even if the container is empty.

When the container is empty, data() is not dereferenceable.

If size() is 0, data() may or may not return a null pointer.

For non-empty containers, the returned pointer compares equal to the address of the first element.

See Also:

front, back, size

Returns:

Pointer to the underlying element storage
```
T * c_array();
```
Direct access to the underlying array.
Returns pointer to the underlying array serving as element storage.

Complexity.

Constant

Note

The pointer is such that range [data(); data() + size()) is always a valid range, even if the container is empty.

When the container is empty, data() is not dereferenceable.

If size() is 0, data() may or may not return a null pointer.

This function is not available in std::array

For non-empty containers, the returned pointer compares equal to the address of the first element.

See Also:

front, back, size

Returns:

Pointer to the underlying element storage
```
void assign(const T & value);
```
Assign one value to all elements.
This function assigns the same value to all arrays elements

Complexity.

Linear

Note

This function is not available in std::array.

This function is a synonym for fill.

See Also:

operator=, fill

Returns:

(none)
```
void fill(const T & value);
```
Assign one value to all elements.
This function assigns the same value to all arrays elements

Complexity.

Linear

Note

This function is not available in std::array

See Also:

operator=

Returns:

(none)

	Note
If the array is empty, the returned iterator will be equal to end()

	Note
If the array is empty, the returned iterator will be equal to end()

	Note
If the array is empty, the returned iterator will be equal to end() @return Iterator to the first element of the array

	Note
If the array is empty, the returned iterator will be equal to end()

	Note
If the array is empty, the returned iterator will be equal to end()

	Note
If the array is empty, the returned iterator will be equal to end()

	Note
If the array is empty, the returned iterator is equal to rend().

	Note
If the array is empty, the returned iterator is equal to rend().

	Note
If the array is empty, the returned iterator is equal to rend().

	Note
If the array is empty, the returned iterator is equal to rend().

	Note
If the array is empty, the returned iterator is equal to rend().

	Note
If the array is empty, the returned iterator is equal to rend().

	Note
Unlike std::map::operator[], this operator never inserts a new element into the container.

	Note
Unlike std::map::operator[], this operator never inserts a new element into the container.

	Note
`c.front()` is equivalent to `*c.begin()`

	Note
`c.front()` is equivalent to `*c.begin()`

	Note
`c.back()` is equivalent to `*stdprev(c.end())`

	Note
`c.back()` is equivalent to `*stdprev(c.end())`

	Note
Because array<T, N> is not dynamically allocated, this operation has linear complexity.

	Note
The pointer is such that range [data(); data() + size()) is always a valid range, even if the container is empty.

	Note
The pointer is such that range [data(); data() + size()) is always a valid range, even if the container is empty.

`array` public static functions

```
static constexpr size_type size();
```
Member group: Capacity.
Returns the number of elements

This function returns the number of elements in the container.

Complexity.

Constant

Note

size() is equivalent to std::distance(begin(), end())

See Also:

empty, max_size

Returns:

The number of elements in the container
```
static constexpr bool empty();
```
Checks whether the container is empty.
This function checks whether the container is empty

Complexity.

Constant

Note

empty() is equivalent to begin() == end()

See Also:

size, max_size

Returns:

true if the container is empty, false otherwise
```
static constexpr size_type max_size();
```
Returns the maximum possible number of elements.
Returns the maximum number of elements the container is able to hold due to system or library implementation limitations

Complexity.

Constant

Note

Because array<T, N> is a fixed-size container, the value returned by max_size() is equivalent to size()

See Also:

size, empty

Returns:

Maximum number of elements
```
static constexpr bool rangecheck(size_type i);
```
Member group: Check range.
Check range

This function checks if i in the valid range for the array.

This function may be private because it is static.

Complexity.

Constant

Exception Safety.

Throws std::out_of_range if i is not in the valid range.

Note

This function is not available in std::array

See Also:

size, empty

Returns:

True if i is in the valid range for the array

	Note
	`size()` is equivalent to `std::distance(begin(), end())`

	Note
	Because array<T, N> is a fixed-size container, the value returned by `max_size()` is equivalent to `size()`