home | help 
std::array(3)		       C++ Standard Libary		   std::array(3)

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 ini-
     tialized with
	aggregate-initialization given at most N initializers that are	convert-
     ible 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, support-
     ing
	assignment, random access iterators, etc.

	std::array  satisfies  the  requirements of Container and ReversibleCon-
     tainer 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 SequenceCon-
     tainer.

	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.

Template parameters
	T - element type Must be MoveConstructible and MoveAssignable.
	N - the number of elements in the array or 0.

	 This section is incomplete
	 Reason: Complete the descriptions of template parameters.

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
     (until C++17)
			       LegacyContiguousIterator to value_type
			       LegacyRandomAccessIterator		     and
     (since C++17)
			       LegacyContiguousIterator  that  is  a LiteralType
     (until C++20)
	iterator	       to value_type
			       LegacyRandomAccessIterator,
			       contiguous_iterator,  and  ConstexprIterator   to
     (since C++20)
			       value_type

			       LegacyRandomAccessIterator		     and
     (until C++17)
			       LegacyContiguousIterator to const value_type
			       LegacyRandomAccessIterator		     and
     (since C++17)
			       LegacyContiguousIterator  that  is  a LiteralType
     (until C++20)
	const_iterator	       to const value_type
			       LegacyRandomAccessIterator,
			       contiguous_iterator,  and  ConstexprIterator   to
     (since C++20)
			       const value_type

	reverse_iterator       std::reverse_iterator<iterator>
	const_reverse_iterator std::reverse_iterator<const_iterator>

Member functions
Implicitly-defined member functions
			      initializes  the	array following the rules of ag-
     gregate
	constructor	      initialization (note that  default  initialization
     may result in
	(implicitly declared) indeterminate values for non-class T)
			      (public member function)
	destructor	      destroys every element of the array
	(implicitly declared) (public member function)
	operator=	       overwrites  every  element  of the array with the
     corresponding
	(implicitly declared) element of another array
			      (public member function)

Element access
	at		      access specified element with bounds checking
			      (public member function)
	operator[]	      access specified element
			      (public member function)
	front		      access the first element
			      (public member function)
	back		      access the last element
			      (public member function)
	data		      direct access to the underlying contiguous storage
			      (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
	empty		      checks whether the container is empty
			      (public member function)
	size		      returns the number of elements
			      (public member function)
	max_size	      returns the maximum possible number of elements
			      (public member function)

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

Non-member functions
	operator==
	operator!=
	operator<
	operator<=
	operator>
	operator>=
	operator<=>		  lexicographically compares the values  of  two
     arrays
	(C++11) 		  (function template)
	(C++11)(removed in C++20)
	(C++11)(removed in C++20)
	(C++11)(removed in C++20)
	(C++11)(removed in C++20)
	(C++11)(removed in C++20)
	(C++20)
	get(std::array) 	  accesses an element of an array
	(C++11) 		  (function template)
	std::swap(std::array)	  specializes the std::swap algorithm
	(C++11) 		  (function template)
	to_array		   creates  a  std::array object from a built-in
     array
	(C++20) 		  (function template)

Helper classes
	std::tuple_size<std::array>    obtains the size of an array
	(C++11) 		       (class template specialization)
	std::tuple_element<std::array> obtains the type of the elements of array
	(C++11) 		       (class template specialization)

	  Deduction guides (since C++17)

Example
     // Run this code

      #include <algorithm>
      #include <array>
      #include <iostream>
      #include <iterator>
      #include <string>

      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}; // Double braces never required af-
     ter =

	  // Container operations are supported
	  std::sort(a1.begin(), a1.end());
	  std::ranges::reverse_copy(a2, std::ostream_iterator<int>(std::cout,  "
     "));
	  std::cout << '\n';

	  // Ranged for loop is supported
	  std::array<std::string, 2> a3{"E", "\u018E"};
	  for (const auto& s : a3)
	      std::cout << s << ' ';
	  std::cout << '\n';

	  // Deduction guide for array creation (since C++17)
	  [[maybe_unused]]  std::array	a4{3.0, 1.0, 4.0}; // std::array<double,
     3>

	  // Behavior of unspecified elements is the same as with  built-in  ar-
     rays
	  [[maybe_unused]]  std::array<int,  2>  a5;  // No list init, a5[0] and
     a5[1]
						  // are default initialized
	  [[maybe_unused]] std::array<int, 2> a6{}; // List init, both	elements
     are value
						    //	 initialized,	a6[0]  =
     a6[1] = 0
	  [[maybe_unused]] std::array<int, 2> a7{1}; // List  init,  unspecified
     element is value
						     //  initialized, a7[0] = 1,
     a7[1] = 0
      }

Output:
      3 2 1
      E AE

See also
	make_array		     creates a std::array object whose size  and
     optionally
	(library fundamentals TS v2) element type are deduced from the arguments
				     (function template)

Category:
	  * Todo with reason

http://cppreference.com 	   2024.06.10			   std::array(3)
home | help