std::allocator<T>::allocate_at_least

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Dynamic memory management

Uninitialized memory algorithms uninitialized_copy uninitialized_fill uninitialized_move (C++17) uninitialized_default_construct (C++17) uninitialized_value_construct (C++17) destroy (C++17) destroy_at (C++17) voidify (C++20) uninitialized_copy_n (C++11) uninitialized_fill_n uninitialized_move_n (C++17) uninitialized_default_construct_n (C++17) uninitialized_value_construct_n (C++17) destroy_n (C++17) construct_at (C++20) Constrained uninitialized memory algorithms ranges::uninitialized_copy (C++20) ranges::uninitialized_fill (C++20) ranges::uninitialized_move (C++20) ranges::construct_at (C++20) ranges::destroy (C++20) ranges::destroy_n (C++20) ranges::destroy_at (C++20) ranges::uninitialized_copy_n (C++20) ranges::uninitialized_fill_n (C++20) ranges::uninitialized_move_n (C++20) ranges::uninitialized_default_construct (C++20) ranges::uninitialized_value_construct (C++20) ranges::uninitialized_default_construct_n (C++20)   ranges::uninitialized_value_construct_n (C++20) Allocators allocator allocator_traits (C++11) allocation_result (C++23) allocator_arg (C++11) uses_allocator (C++11) uses_allocator_construction_args (C++20) make_obj_using_allocator (C++20) uninitialized_construct_using_allocator (C++20) scoped_allocator_adaptor (C++11) pmr::polymorphic_allocator (C++17) Memory resources pmr::memory_resource (C++17) pmr::get_default_resource (C++17) pmr::set_default_resource (C++17) pmr::new_delete_resource (C++17) pmr::null_memory_resource (C++17) pmr::synchronized_pool_resource (C++17) pmr::unsynchronized_pool_resource (C++17)   pmr::monotonic_buffer_resource (C++17) pmr::pool_options (C++17) Garbage collection support declare_reachable (C++11)(until C++23) undeclare_reachable (C++11)(until C++23) declare_no_pointers (C++11)(until C++23) undeclare_no_pointers (C++11)(until C++23) pointer_safety (C++11)(until C++23) get_pointer_safety (C++11)(until C++23) Uninitialized storage raw_storage_iterator (until C++20*) get_temporary_buffer (until C++20*) return_temporary_buffer (until C++20*) Explicit lifetime management start_lifetime_asstart_lifetime_as_array (C++23)(C++23)

Smart pointers unique_ptr (C++11) shared_ptr (C++11) weak_ptr (C++11) auto_ptr (until C++17*) owner_less (C++11) owner_less<void> (C++17) owner_hash (C++26) owner_equal (C++26) enable_shared_from_this (C++11) bad_weak_ptr (C++11) default_delete (C++11) out_ptr_t (C++23) inout_ptr_t (C++23) Low level memory management operator new operator new[] operator delete operator delete[] get_new_handler (C++11) set_new_handler launder (C++17) bad_alloc bad_array_new_length (C++11) nothrow_t align_val_t (C++17) destroying_delete_t (C++20) new_handler nothrow Miscellaneous pointer_traits (C++11) to_address (C++20) addressof (C++11) align (C++11) assume_aligned (C++20) C Library malloc calloc realloc    aligned_alloc (C++17) free

 

std::allocator

Member functions

allocator::allocator

allocator::~allocator

allocator::address (until C++20)

allocator::allocate

allocator::allocate_at_least (C++23)

allocator::deallocate

allocator::max_size (until C++20)

allocator::construct (until C++20)

allocator::destroy (until C++20)

Non-member functions

operator==operator!= (until C++20)

 

constexpr std::allocation_result<T*, std::size_t>     allocate_at_least( std::size_t n );		(since C++23)

Allocates count * sizeof(T) bytes of uninitialized storage, where count is an unspecified integer value not less than n, by calling ::operator new (possibly with an additional std::align_val_t argument), but it is unspecified when and how this function is called.

Then, this function creates an array of type T[count] in the storage and starts its lifetime, but does not start lifetime of any of its elements.

In order to use this function in a constant expression, the allocated storage must be deallocated within the evaluation of the same expression.

Use of this function is ill-formed if T is an incomplete type.

Parameters

n

-

the lower bound of number of objects to allocate storage for

Return value

std::allocation_result<T*>{p, count}, where p points to the first element of an array of count objects of type T whose elements have not been constructed yet.

Exceptions

Throws std::bad_array_new_length if std::numeric_limits<std::size_t>::max() / sizeof(T) < n, or std::bad_alloc if allocation fails.

Notes

allocate_at_least is mainly provided for contiguous containers, e.g. std::vector and std::basic_string, in order to reduce reallocation by making their capacity match the actually allocated size when possible.

The "unspecified when and how" wording makes it possible to combine or optimize away heap allocations made by the standard library containers, even though such optimizations are disallowed for direct calls to ::operator new. For example, this is implemented by libc++ ([1] and [2]).

After calling allocate_at_least and before construction of elements, pointer arithmetic of T* is well-defined within the allocated array, but the behavior is undefined if elements are accessed.

Feature-test macro	Value	Std	Feature
__cpp_lib_allocate_at_least	202302L	(C++23)	allocate_at_least etc.

Example

Run this code

#include <memory>
#include <print>
 
int main()
{
    const std::size_t count{69};
    std::allocator<int> alloc;
    std::allocation_result res{alloc.allocate_at_least(count)};
    std::print("count: {}\n"
               "res.ptr: {}\n"
               "res.count: {}\n", count, res.ptr, res.count);
 
    /* construct, use, then destroy elements */
 
    alloc.deallocate(res.ptr, res.count);
}

Possible output:

count: 69
res.ptr: 0x555a486a0960
res.count: 96

See also

allocation_result (C++23)	records the address and the actual size of storage allocated by allocate_at_least (class template)
allocate_at_least [static] (C++23)	allocates storage at least as large as the requested size via an allocator (public static member function of std::allocator_traits<Alloc>)