array
Class (C++ Standard Library)
Describes an object that controls a sequence of length N
of elements of type Ty
. The sequence is stored as an array of Ty
, contained in the array<Ty, N>
object.
Syntax
template <class Ty, std::size_t N>
class array;
Parameters
Ty
The type of an element.
N
The number of elements.
Members
Type Definition | Description |
---|---|
const_iterator |
The type of a constant iterator for the controlled sequence. |
const_pointer |
The type of a constant pointer to an element. |
const_reference |
The type of a constant reference to an element. |
const_reverse_iterator |
The type of a constant reverse iterator for the controlled sequence. |
difference_type |
The type of a signed distance between two elements. |
iterator |
The type of an iterator for the controlled sequence. |
pointer |
The type of a pointer to an element. |
reference |
The type of a reference to an element. |
reverse_iterator |
The type of a reverse iterator for the controlled sequence. |
size_type |
The type of an unsigned distance between two elements. |
value_type |
The type of an element. |
Member Function | Description |
---|---|
array |
Constructs an array object. |
assign |
(Obsolete. Use fill .) Replaces all elements. |
at |
Accesses an element at a specified position. |
back |
Accesses the last element. |
begin |
Designates the beginning of the controlled sequence. |
cbegin |
Returns a random-access const iterator to the first element in the array. |
cend |
Returns a random-access const iterator that points just beyond the end of the array. |
crbegin |
Returns a const iterator to the first element in a reversed array. |
crend |
Returns a const iterator to the end of a reversed array. |
data |
Gets the address of the first element. |
empty |
Tests whether elements are present. |
end |
Designates the end of the controlled sequence. |
fill |
Replaces all elements with a specified value. |
front |
Accesses the first element. |
max_size |
Counts the number of elements. |
rbegin |
Designates the beginning of the reversed controlled sequence. |
rend |
Designates the end of the reversed controlled sequence. |
size |
Counts the number of elements. |
swap |
Swaps the contents of two containers. |
Operator | Description |
---|---|
array::operator= |
Replaces the controlled sequence. |
array::operator[] |
Accesses an element at a specified position. |
Remarks
The type has a default constructor array()
and a default assignment operator operator=
, and satisfies the requirements for an aggregate
. Therefore, objects of type array<Ty, N>
can be initialized by using an aggregate initializer. For example,
array<int, 4> ai = { 1, 2, 3 };
creates the object ai
that holds four integer values, initializes the first three elements to the values 1, 2, and 3, respectively, and initializes the fourth element to 0.
Requirements
Header: <array>
Namespace: std
array::array
Constructs an array object.
array();
array(const array& right);
Parameters
right
Object or range to insert.
Remarks
The default constructor array()
leaves the controlled sequence uninitialized (or default initialized). You use it to specify an uninitialized controlled sequence.
The copy constructor array(const array& right)
initializes the controlled sequence with the sequence [right.begin()
, right.end()
). You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the array object right
.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
Myarray c1(c0);
// display contents " 0 1 2 3"
for (const auto& it : c1)
{
std::cout << " " << it;
}
std::cout << std::endl;
return (0);
}
0 1 2 3
0 1 2 3
array::assign
Obsolete in C++11, replaced by fill
. Replaces all elements.
array::at
Accesses an element at a specified position.
reference at(size_type off);
constexpr const_reference at(size_type off) const;
Parameters
off
Position of element to access.
Remarks
The member functions return a reference to the element of the controlled sequence at position off
. If that position is invalid, the function throws an object of class out_of_range
.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display odd elements " 1 3"
std::cout << " " << c0.at(1);
std::cout << " " << c0.at(3);
std::cout << std::endl;
return (0);
}
array::back
Accesses the last element.
reference back();
constexpr const_reference back() const;
Remarks
The member functions return a reference to the last element of the controlled sequence, which must be non-empty.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display last element " 3"
std::cout << " " << c0.back();
std::cout << std::endl;
return (0);
}
0 1 2 3
3
array::begin
Designates the beginning of the controlled sequence.
iterator begin() noexcept;
const_iterator begin() const noexcept;
Remarks
The member functions return a random-access iterator that points at the first element of the sequence (or just beyond the end of an empty sequence).
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display first element " 0"
Myarray::iterator it2 = c0.begin();
std::cout << " " << *it2;
std::cout << std::endl;
return (0);
}
0 1 2 3
0
array::cbegin
Returns a const
iterator that addresses the first element in the range.
const_iterator cbegin() const noexcept;
Return Value
A const
random-access iterator that points at the first element of the range, or the location just beyond the end of an empty range (for an empty range, cbegin() == cend()
).
Remarks
With the return value of cbegin
, the elements in the range can't be modified.
You can use this member function in place of the begin()
member function to guarantee that the return value is const_iterator
. Typically, it's used with the auto
type deduction keyword, as shown in the following example. In the example, consider Container
to be a modifiable (non- const
) container of any kind that supports begin()
and cbegin()
.
auto i1 = Container.begin();
// i1 is Container<T>::iterator
auto i2 = Container.cbegin();
// i2 is Container<T>::const_iterator
array::cend
Returns a const
iterator that addresses the location just beyond the last element in a range.
const_iterator cend() const noexcept;
Return Value
A random-access iterator that points just beyond the end of the range.
Remarks
cend
is used to test whether an iterator has passed the end of its range.
You can use this member function in place of the end()
member function to guarantee that the return value is const_iterator
. Typically, it's used with the auto
type deduction keyword, as shown in the following example. In the example, consider Container
to be a modifiable (non- const
) container of any kind that supports end()
and cend()
.
auto i1 = Container.end();
// i1 is Container<T>::iterator
auto i2 = Container.cend();
// i2 is Container<T>::const_iterator
The value returned by cend
shouldn't be dereferenced.
array::const_iterator
The type of a constant iterator for the controlled sequence.
typedef implementation-defined const_iterator;
Remarks
The type describes an object that can serve as a constant random-access iterator for the controlled sequence.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> MyArray;
int main()
{
MyArray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
std::cout << "it1:";
for (MyArray::const_iterator it1 = c0.begin();
it1 != c0.end();
++it1) {
std::cout << " " << *it1;
}
std::cout << std::endl;
// display first element " 0"
MyArray::const_iterator it2 = c0.begin();
std::cout << "it2:";
std::cout << " " << *it2;
std::cout << std::endl;
return (0);
}
it1: 0 1 2 3
it2: 0
array::const_pointer
The type of a constant pointer to an element.
typedef const Ty *const_pointer;
Remarks
The type describes an object that can serve as a constant pointer to elements of the sequence.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display first element " 0"
Myarray::const_pointer ptr = &*c0.begin();
std::cout << " " << *ptr;
std::cout << std::endl;
return (0);
}
0 1 2 3
0
array::const_reference
The type of a constant reference to an element.
typedef const Ty& const_reference;
Remarks
The type describes an object that can serve as a constant reference to an element of the controlled sequence.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display first element " 0"
Myarray::const_reference ref = *c0.begin();
std::cout << " " << ref;
std::cout << std::endl;
return (0);
}
0 1 2 3
0
array::const_reverse_iterator
The type of a constant reverse iterator for the controlled sequence.
typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
Remarks
The type describes an object that can serve as a constant reverse iterator for the controlled sequence.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display last element " 3"
Myarray::const_reverse_iterator it2 = c0.rbegin();
std::cout << " " << *it2;
std::cout << std::endl;
return (0);
}
0 1 2 3
3
array::crbegin
Returns a const iterator to the first element in a reversed array.
const_reverse_iterator crbegin() const;
Return Value
A const reverse random-access iterator addressing the first element in a reversed array or addressing what had been the last element in the unreversed array.
Remarks
With the return value of crbegin
, the array object can't be modified.
Example
#include <array>
#include <iostream>
int main( )
{
using namespace std;
array<int, 2> v1 = {1, 2};
array<int, 2>::iterator v1_Iter;
array<int, 2>::const_reverse_iterator v1_rIter;
v1_Iter = v1.begin( );
cout << "The first element of array is "
<< *v1_Iter << "." << endl;
v1_rIter = v1.crbegin( );
cout << "The first element of the reversed array is "
<< *v1_rIter << "." << endl;
}
The first element of array is 1.
The first element of the reversed array is 2.
array::crend
Returns a const iterator that addresses the location succeeding the last element in a reversed array.
const_reverse_iterator crend() const noexcept;
Return Value
A const reverse random-access iterator that addresses the location succeeding the last element in a reversed array (the location that had preceded the first element in the unreversed array).
Remarks
crend
is used with a reversed array just as array::cend
is used with an array.
With the return value of crend
(suitably decremented), the array object can't be modified.
crend
can be used to test to whether a reverse iterator has reached the end of its array.
The value returned by crend
shouldn't be dereferenced.
Example
#include <array>
#include <iostream>
int main( )
{
using namespace std;
array<int, 2> v1 = {1, 2};
array<int, 2>::const_reverse_iterator v1_rIter;
for ( v1_rIter = v1.rbegin( ) ; v1_rIter != v1.rend( ) ; v1_rIter++ )
cout << *v1_rIter << endl;
}
2
1
array::data
Gets the address of the first element.
Ty *data();
const Ty *data() const;
Remarks
The member functions return the address of the first element in the controlled sequence.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display first element " 0"
Myarray::pointer ptr = c0.data();
std::cout << " " << *ptr;
std::cout << std::endl;
return (0);
}
0 1 2 3
0
array::difference_type
The type of a signed distance between two elements.
typedef std::ptrdiff_t difference_type;
Remarks
The signed integer type describes an object that can represent the difference between the addresses of any two elements in the controlled sequence. It's a synonym for the type std::ptrdiff_t
.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display distance first-last " -4"
Myarray::difference_type diff = c0.begin() - c0.end();
std::cout << " " << diff;
std::cout << std::endl;
return (0);
}
0 1 2 3
-4
array::empty
Tests whether no elements are present.
constexpr bool empty() const;
Remarks
The member function returns true only if N == 0
.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display whether c0 is empty " false"
std::cout << std::boolalpha << " " << c0.empty();
std::cout << std::endl;
std::array<int, 0> c1;
// display whether c1 is empty " true"
std::cout << std::boolalpha << " " << c1.empty();
std::cout << std::endl;
return (0);
}
0 1 2 3
false
true
array::end
Designates the end of the controlled sequence.
reference end();
const_reference end() const;
Remarks
The member functions return a random-access iterator that points just beyond the end of the sequence.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display last element " 3"
Myarray::iterator it2 = c0.end();
std::cout << " " << *--it2;
std::cout << std::endl;
return (0);
}
0 1 2 3
3
array::fill
Erases an array and copies the specified elements to the empty array.
void fill(const Type& val);
Parameters
val
The value of the element being inserted into the array.
Remarks
fill
replaces each element of the array with the specified value.
Example
#include <array>
#include <iostream>
int main()
{
using namespace std;
array<int, 2> v1 = { 1, 2 };
cout << "v1 = ";
for (const auto& it : v1)
{
std::cout << " " << it;
}
cout << endl;
v1.fill(3);
cout << "v1 = ";
for (const auto& it : v1)
{
std::cout << " " << it;
}
cout << endl;
}
array::front
Accesses the first element.
reference front();
constexpr const_reference front() const;
Remarks
The member functions return a reference to the first element of the controlled sequence, which must be non-empty.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display first element " 0"
std::cout << " " << c0.front();
std::cout << std::endl;
return (0);
}
0 1 2 3
0
array::iterator
The type of an iterator for the controlled sequence.
typedef implementation-defined iterator;
Remarks
The type describes an object that can serve as a random-access iterator for the controlled sequence.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> MyArray;
int main()
{
MyArray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
std::cout << "it1:";
for (MyArray::iterator it1 = c0.begin();
it1 != c0.end();
++it1) {
std::cout << " " << *it1;
}
std::cout << std::endl;
// display first element " 0"
MyArray::iterator it2 = c0.begin();
std::cout << "it2:";
std::cout << " " << *it2;
std::cout << std::endl;
return (0);
}
it1: 0 1 2 3
it2: 0
array::max_size
Counts the number of elements.
constexpr size_type max_size() const;
Remarks
The member function returns N
.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display (maximum) size " 4"
std::cout << " " << c0.max_size();
std::cout << std::endl;
return (0);
}
0 1 2 3
4
array::operator[]
Accesses an element at a specified position.
reference operator[](size_type off);
constexpr const_reference operator[](size_type off) const;
Parameters
off
Position of element to access.
Remarks
The member functions return a reference to the element of the controlled sequence at position off
. If that position is invalid, the behavior is undefined.
There's also a non-member get
function available to get a reference to an element of an array
.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display odd elements " 1 3"
std::cout << " " << c0[1];
std::cout << " " << c0[3];
std::cout << std::endl;
return (0);
}
0 1 2 3
1 3
array::operator=
Replaces the controlled sequence.
array<Value> operator=(array<Value> right);
Parameters
right
Container to copy.
Remarks
The member operator assigns each element of right
to the corresponding element of the controlled sequence, then returns *this
. You use it to replace the controlled sequence with a copy of the controlled sequence in right
.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
Myarray c1;
c1 = c0;
// display copied contents " 0 1 2 3"
// display contents " 0 1 2 3"
for (auto it : c1)
{
std::cout << " " << it;
}
std::cout << std::endl;
return (0);
}
0 1 2 3
0 1 2 3
array::pointer
The type of a pointer to an element.
typedef Ty *pointer;
Remarks
The type describes an object that can serve as a pointer to elements of the sequence.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display first element " 0"
Myarray::pointer ptr = &*c0.begin();
std::cout << " " << *ptr;
std::cout << std::endl;
return (0);
}
0 1 2 3
0
array::rbegin
Designates the beginning of the reversed controlled sequence.
reverse_iterator rbegin()noexcept;
const_reverse_iterator rbegin() const noexcept;
Remarks
The member functions return a reverse iterator that points just beyond the end of the controlled sequence. Hence, it designates the beginning of the reverse sequence.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display last element " 3"
Myarray::const_reverse_iterator it2 = c0.rbegin();
std::cout << " " << *it2;
std::cout << std::endl;
return (0);
}
0 1 2 3
3
array::reference
The type of a reference to an element.
typedef Ty& reference;
Remarks
The type describes an object that can serve as a reference to an element of the controlled sequence.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display first element " 0"
Myarray::reference ref = *c0.begin();
std::cout << " " << ref;
std::cout << std::endl;
return (0);
}
0 1 2 3
0
array::rend
Designates the end of the reversed controlled sequence.
reverse_iterator rend()noexcept;
const_reverse_iterator rend() const noexcept;
Remarks
The member functions return a reverse iterator that points at the first element of the sequence (or just beyond the end of an empty sequence)). Hence, it designates the end of the reverse sequence.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display first element " 0"
Myarray::const_reverse_iterator it2 = c0.rend();
std::cout << " " << *--it2;
std::cout << std::endl;
return (0);
}
0 1 2 3
0
array::reverse_iterator
The type of a reverse iterator for the controlled sequence.
typedef std::reverse_iterator<iterator> reverse_iterator;
Remarks
The type describes an object that can serve as a reverse iterator for the controlled sequence.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display last element " 3"
Myarray::reverse_iterator it2 = c0.rbegin();
std::cout << " " << *it2;
std::cout << std::endl;
return (0);
}
0 1 2 3
3
array::size
Counts the number of elements.
constexpr size_type size() const;
Remarks
The member function returns N
.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display size " 4"
std::cout << " " << c0.size();
std::cout << std::endl;
return (0);
}
0 1 2 3
4
array::size_type
The type of an unsigned distance between two elements.
typedef std::size_t size_type;
Remarks
The unsigned integer type describes an object that can represent the length of any controlled sequence. It's a synonym for the type std::size_t
.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display distance last-first " 4"
Myarray::size_type diff = c0.end() - c0.begin();
std::cout << " " << diff;
std::cout << std::endl;
return (0);
}
0 1 2 3
4
array::swap
Swaps the contents of this array with another array.
void swap(array& right);
Parameters
right
Array to swap contents with.
Remarks
The member function swaps the controlled sequences between *this
and right. It performs element assignments and constructor calls proportional to N
.
There's also a non-member swap
function available to swap two array
instances.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
Myarray c1 = { 4, 5, 6, 7 };
c0.swap(c1);
// display swapped contents " 4 5 6 7"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
swap(c0, c1);
// display swapped contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
return (0);
}
0 1 2 3
4 5 6 7
0 1 2 3
array::value_type
The type of an element.
typedef Ty value_type;
Remarks
The type is a synonym for the template parameter Ty
.
Example
#include <array>
#include <iostream>
typedef std::array<int, 4> Myarray;
int main()
{
Myarray c0 = { 0, 1, 2, 3 };
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
std::cout << " " << it;
}
std::cout << std::endl;
// display contents " 0 1 2 3"
for (const auto& it : c0)
{
Myarray::value_type val = it;
std::cout << " " << val;
}
std::cout << std::endl;
return (0);
}
0 1 2 3
0 1 2 3