[vector.capacity] (original) (raw)

23 Containers library [containers]

23.3 Sequence containers [sequences]

23.3.13 Class template vector [vector]

23.3.13.3 Capacity [vector.capacity]

constexpr size_type capacity() const noexcept;

Returns: The total number of elements that the vector can hold without requiring reallocation.

Complexity: Constant time.

constexpr void reserve(size_type n);

Preconditions: T is Cpp17MoveInsertable into vector.

Effects: A directive that informs avectorof a planned change in size, so that it can manage the storage allocation accordingly.

Afterreserve(),capacity()is greater or equal to the argument ofreserveif reallocation happens; and equal to the previous value ofcapacity()otherwise.

Reallocation happens at this point if and only if the current capacity is less than the argument ofreserve().

If an exception is thrown other than by the move constructor of a non-Cpp17CopyInsertable type, there are no effects.

Throws: length_error if n >max_size().198

Complexity: It does not change the size of the sequence and takes at most linear time in the size of the sequence.

Remarks: Reallocation invalidates all the references, pointers, and iterators referring to the elements in the sequence, as well as the past-the-end iterator.

[Note 1:

If no reallocation happens, they remain valid.

— _end note_]

No reallocation shall take place during insertions that happen after a call to reserve()until an insertion would make the size of the vector greater than the value of capacity().

constexpr void shrink_to_fit();

Preconditions: T is Cpp17MoveInsertable into vector.

Effects: shrink_to_fit is a non-binding request to reducecapacity() to size().

[Note 2:

The request is non-binding to allow latitude for implementation-specific optimizations.

— _end note_]

It does not increase capacity(), but may reduce capacity()by causing reallocation.

If an exception is thrown other than by the move constructor of a non-Cpp17CopyInsertable T, there are no effects.

Complexity: If reallocation happens, linear in the size of the sequence.

Remarks: Reallocation invalidates all the references, pointers, and iterators referring to the elements in the sequence as well as the past-the-end iterator.

[Note 3:

If no reallocation happens, they remain valid.

— _end note_]

constexpr void swap(vector& x) noexcept(allocator_traits<Allocator>::propagate_on_container_swap::value || allocator_traits<Allocator>::is_always_equal::value);

Effects: Exchanges the contents andcapacity()of*thiswith that of x.

Complexity: Constant time.

constexpr void resize(size_type sz);

Preconditions: T is_Cpp17MoveInsertable_ and Cpp17DefaultInsertable into vector.

Effects: If sz < size(), erases the last size() - sz elements from the sequence.

Otherwise, appends sz - size() default-inserted elements to the sequence.

Remarks: If an exception is thrown other than by the move constructor of a non-Cpp17CopyInsertable T, there are no effects.

constexpr void resize(size_type sz, const T& c);

Preconditions: T is_Cpp17CopyInsertable_ into vector.

Effects: If sz < size(), erases the last size() - sz elements from the sequence.

Otherwise, appends sz - size() copies of c to the sequence.

Remarks: If an exception is thrown, there are no effects.