Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

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

  1. typename T

    The array value type

  2. std::size_t N

    The array size

array public types

  1. typedef T value_type;

    The array value type

  2. typedef std::reverse_iterator< iterator > reverse_iterator;

    Reverse array iterator - std::reverse_iterator<iterator>

array public construct/copy/destruct

  1. 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

  1. 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] 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

  2. 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] 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

  3. 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] 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

  4. 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] 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

  5. 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] 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

  6. 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] 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

  7. 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] 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

  8. 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] 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

  9. 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] 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

  10. 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] 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

  11. 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] 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

  12. 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] 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

  13. 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] 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.

  14. 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] 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.

  15. 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.

  16. 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.

  17. 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] Note

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

    Preconditions. 

    !(empty())

    See Also:

    operator[], at, begin, end

    Returns:

    Reference to the first array element.

  18. 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] Note

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

    Preconditions. 

    !(empty())

    See Also:

    operator[], at, begin, end

    Returns:

    Reference to the first array element.

  19. 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] Note

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

    Preconditions. 

    !(empty())

    See Also:

    operator[], at, begin, end

    Returns:

    Reference to the last array element.

  20. 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] Note

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

    Preconditions. 

    !(empty())

    See Also:

    operator[], at, begin, end

    Returns:

    Reference to the last array element.

  21. 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] 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)

  22. 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] 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

  23. T * data();
    Direct access to the underlying array.

    Returns pointer to the underlying array serving as element storage.

    Complexity. 

    Constant

    [Note] 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

  24. T * c_array();
    Direct access to the underlying array.

    Returns pointer to the underlying array serving as element storage.

    Complexity. 

    Constant

    [Note] 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

  25. void assign(const T & value);
    Assign one value to all elements.

    This function assigns the same value to all arrays elements

    Complexity. 

    Linear

    [Note] Note

    This function is not available in std::array.

    This function is a synonym for fill.

    See Also:

    operator=, fill

    Returns:

    (none)

  26. void fill(const T & value);
    Assign one value to all elements.

    This function assigns the same value to all arrays elements

    Complexity. 

    Linear

    [Note] Note

    This function is not available in std::array

    See Also:

    operator=

    Returns:

    (none)

array public static functions

  1. 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] Note

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

    See Also:

    empty, max_size

    Returns:

    The number of elements in the container

  2. static constexpr bool empty();
    Checks whether the container is empty.

    This function checks whether the container is empty

    Complexity. 

    Constant

    [Note] Note

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

    See Also:

    size, max_size

    Returns:

    true if the container is empty, false otherwise

  3. 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] 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

  4. 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] 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


PrevUpHomeNext