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

NAME
     std::vector - std::vector

Synopsis
	Defined in header <vector>
	template<

	    class T,							   (1)
	    class Allocator = std::allocator<T>

	> class vector;
	namespace pmr {

	    template< class T >
	    using  vector  = std::vector<T,				     (2)
     (since C++17)
	std::pmr::polymorphic_allocator<T>>;

	}

	1) std::vector is a sequence container that  encapsulates  dynamic  size
     arrays.
	2) std::pmr::vector is an alias template that uses a polymorphic alloca-
     tor.

	The  elements  are stored contiguously, which means that elements can be
     accessed not
	only through iterators, but also using offsets to  regular  pointers  to
     elements. This
	means  that  a	pointer  to  an element of a vector may be passed to any
     function that
	expects a pointer to an element of an array.

	The storage of the vector is handled automatically,  being  expanded  as
     needed.
	Vectors  usually occupy more space than static arrays, because more mem-
     ory is
	allocated to handle future growth. This way a vector does  not	need  to
     reallocate
	each time an element is inserted, but only when the additional memory is
     exhausted.
	The  total  amount  of	allocated memory can be queried using capacity()
     function. Extra
	memory can be returned to the system via a call to shrink_to_fit()^[1].

	Reallocations are usually costly operations in terms of performance. The
     reserve()
	function can be used to eliminate reallocations if the	number	of  ele-
     ments is known
	beforehand.

	The  complexity  (efficiency) of common operations on vectors is as fol-
     lows:

	  * Random access - constant dh(1).
	  * Insertion or removal of elements at the  end  -  amortized	constant
     dh(1).
	  * Insertion or removal of elements - linear in the distance to the end
     of the
	    vector dh(n).

	std::vector (for T other than bool) meets the requirements of Container
	, AllocatorAwareContainer
	(since C++11), SequenceContainer
	, ContiguousContainer
	(since C++17) and ReversibleContainer.

	Member functions of std::vector are constexpr: it is possible to
	create and use std::vector objects in the evaluation of a constant
	expression.
									       (since
     C++20)
	However, std::vector objects generally cannot be constexpr, because
	any dynamically allocated storage must be released in the same
	evaluation of constant expression.

	 1. a In libstdc++, shrink_to_fit() is not available in C++98 mode.

Template parameters
		    The type of the elements.

		    T	must   meet   the  requirements  of  CopyAssignable  and
     (until
		    CopyConstructible.
     C++11)
		    The requirements that are imposed on the elements depend  on
     the    (since
		    actual  operations performed on the container. Generally, it
     is     C++11)
		    required that element type is a complete type and meets  the
     (until
		    requirements  of  Erasable, but many member functions impose
     C++17)
		    stricter requirements.
		    The requirements that are imposed on the elements depend  on
     the
		    actual  operations performed on the container. Generally, it
     is
	T	  -  required  that  element  type  meets  the	requirements  of
     Erasable, but
		    many  member  functions  impose  stricter requirements. This
     container
		    (but not its members) can be instantiated with an incomplete
		    element type if the allocator satisfies the  allocator  com-
     pleteness (since
		    requirements.
     C++17)

			      Feature-test    macro		  Value      Std
     Feature
									    Min-
     imal
		    __cpp_lib_incomplete_container_elements 201505L (C++17)  in-
     complete
									    type
									    sup-
     port

		    An allocator that is used to acquire/release memory and to
		    construct/destroy the elements in that memory. The type must
     meet the
		    requirements of Allocator.
	Allocator - The behavior is undefined
		    (until C++20)
		    The program is ill-formed
		    (since C++20) if Allocator::value_type is not the same as T.

Specializations
	The  standard  library	provides a specialization of std::vector for the
     type bool,
	which may be optimized for space efficiency.

	vector<bool> space-efficient dynamic bitset
		     (class template specialization)

	Iterator invalidation

	       Operations				 Invalidated
	All read only operations Never.
	swap, std::swap 	 end()
	clear, operator=, assign Always.
	reserve, shrink_to_fit	 If the vector changed capacity, all of them. If
     not, none.
	erase			 Erased elements and  all  elements  after  them
     (including
				 end()).
	push_back, emplace_back  If the vector changed capacity, all of them. If
     not, only
				 end().
				 If the vector changed capacity, all of them.
	insert,  emplace	   If  not, only those at or after the insertion
     point
				 (including end()).
	resize			 If the vector changed capacity, all of them. If
     not, only
				 end() and any elements erased.
	pop_back		 The element erased and end().

Member types
	Member type	       Definition
	value_type	       T
	allocator_type	       Allocator
	size_type	       Unsigned integer type (usually std::size_t)
	difference_type        Signed integer type (usually std::ptrdiff_t)
	reference	       value_type&
	const_reference        const value_type&
			       Allocator::pointer			  (until
     C++11)
	pointer 		std::allocator_traits<Allocator>::pointer (since
     C++11)

			       Allocator::const_pointer
     (until C++11)
	const_pointer		 std::allocator_traits<Allocator>::const_pointer
     (since C++11)

			       LegacyRandomAccessIterator		     and
     (until C++20)
			       LegacyContiguousIterator to value_type
			       LegacyRandomAccessIterator,
	iterator		contiguous_iterator,  and  ConstexprIterator  to
     (since C++20)
			       value_type

			       LegacyRandomAccessIterator		     and
     (until C++20)
			       LegacyContiguousIterator to const value_type
			       LegacyRandomAccessIterator,
	const_iterator		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
	constructor   constructs the vector
		      (public member function)
	destructor    destructs the vector
		      (public member function)
	operator=     assigns values to the container
		      (public member function)
	assign	      assigns values to the container
		      (public member function)
	assign_range  assigns a range of values to the container
	(C++23)       (public member function)
	get_allocator returns the associated allocator
		      (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)
	(C++11)
	end	      returns an iterator to the end
	cend	      (public member function)
	(C++11)
	rbegin	      returns a reverse iterator to the beginning
	crbegin       (public member function)
	(C++11)
	rend	      returns a reverse iterator to the end
	crend	      (public member function)
	(C++11)

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)
	reserve       reserves storage
		      (public member function)
		      returns  the  number  of elements that can be held in cur-
     rently allocated
	capacity      storage
		      (public member function)
	shrink_to_fit reduces memory usage by freeing unused memory
	(DR*)	      (public member function)

Modifiers
	clear	      clears the contents
		      (public member function)
	insert	      inserts elements
		      (public member function)
	insert_range  inserts a range of elements
	(C++23)       (public member function)
	emplace       constructs element in-place
	(C++11)       (public member function)
	erase	      erases elements
		      (public member function)
	push_back     adds an element to the end
		      (public member function)
	emplace_back  constructs an element in-place at the end
	(C++11)       (public member function)
	append_range  adds a range of elements to the end
	(C++23)       (public member function)
	pop_back      removes the last element
		      (public member function)
	resize	      changes the number of elements stored
		      (public member function)
	swap	      swaps the contents
		      (public member function)

Non-member functions
	operator==
	operator!=
	operator<
	operator<=
	operator>
	operator>=	       lexicographically compares the values of two vec-
     tors
	operator<=>	       (function template)
	(removed in C++20)
	(removed in C++20)
	(removed in C++20)
	(removed in C++20)
	(removed in C++20)
	(C++20)
	std::swap(std::vector) specializes the std::swap algorithm
			       (function template)
	erase(std::vector)     erases all elements satisfying specific criteria
	erase_if(std::vector)  (function template)
	(C++20)

	  Deduction guides (since C++17)

Notes
	    Feature-test macro	     Value    Std		    Feature
	__cpp_lib_containers_ranges 202202L (C++23) Ranges construction and  in-
     sertion for
						    containers

Example
     // Run this code

      #include <iostream>
      #include <vector>

      int main()
      {
	  // Create a vector containing integers
	  std::vector<int> v = {8, 4, 5, 9};

	  // Add two more integers to vector
	  v.push_back(6);
	  v.push_back(9);

	  // Overwrite element at position 2
	  v[2] = -1;

	  // Print out the vector
	  for (int n : v)
	      std::cout << n << ' ';
	  std::cout << '\n';
      }

Output:
      8 4 -1 9 6 9

	Defect reports

	The  following	behavior-changing  defect  reports were applied retroac-
     tively to
	previously published C++ standards.

	  DR	Applied to	     Behavior as published		 Correct
     behavior
	LWG 69	C++98	   contiguity of the storage for elements of  required
			   vector was not required
			   T was not required to be CopyConstructible T is  also
     required to
	LWG  230  C++98      (an element of type T might not be able to be Copy-
     Constructible
			   be constructed)
	LWG 464 C++98	   access to the underlying storage of an     data func-
     tion provided
			   empty vector resulted in UB

http://cppreference.com 	   2024.06.10			  std::vector(3)

home | help