Difference between revisions of "cpp/memory/allocator traits/allocate at least"
m (FTM needs to be updated after P2652R2 (?) |
D41D8CD98F (Talk | contribs) (- nodiscard) |
||
| (5 intermediate revisions by 4 users not shown) | |||
| Line 2: | Line 2: | ||
{{cpp/memory/allocator_traits/navbar}} | {{cpp/memory/allocator_traits/navbar}} | ||
{{ddcl|since=c++23| | {{ddcl|since=c++23| | ||
| − | + | static constexpr std::allocation_result<pointer, size_type> | |
allocate_at_least( Alloc& a, size_type n ); | allocate_at_least( Alloc& a, size_type n ); | ||
}} | }} | ||
| Line 8: | Line 8: | ||
{{tt|allocate_at_least}} calls {{c|a.allocate_at_least(n)}} and returns its result if the call is well-formed, otherwise, it is equivalent to {{c|return {a.allocate(n), n};}}. | {{tt|allocate_at_least}} calls {{c|a.allocate_at_least(n)}} and returns its result if the call is well-formed, otherwise, it is equivalent to {{c|return {a.allocate(n), n};}}. | ||
| − | {{tt|allocator_at_least}} tries to allocate a storage for at least {{ | + | {{tt|allocator_at_least}} tries to allocate a storage for at least {{c|n}} {{tt|value_type}} objects, and provides a fallback mechanism that allocates a storage for exact {{c|n}} objects. |
===Parameters=== | ===Parameters=== | ||
| Line 27: | Line 27: | ||
The {{tt|allocate_at_least}} member function of {{named req|Allocator}} types are mainly provided for contiguous containers, e.g. {{lc|std::vector}} and {{lc|std::basic_string}}, in order to reduce reallocation by making their capacity match the actually allocated size when possible. Because {{tt|allocate_at_least}} provides a fallback mechanism, it can be directly used where appropriate. | The {{tt|allocate_at_least}} member function of {{named req|Allocator}} types are mainly provided for contiguous containers, e.g. {{lc|std::vector}} and {{lc|std::basic_string}}, in order to reduce reallocation by making their capacity match the actually allocated size when possible. Because {{tt|allocate_at_least}} provides a fallback mechanism, it can be directly used where appropriate. | ||
| − | Given an allocator object {{ | + | Given an allocator object {{c|a}} of type {{tt|Alloc}}, let {{c|result}} denote the value returned from {{c|std::allocator_traits<Alloc>::allocate_at_least(a, n)}}, the storage should be deallocated by {{c|a.deallocate(result.ptr, m)}} (typically called via {{c|std::allocator_traits<Alloc>::deallocate(a, result.ptr, m)}}) in order to avoid memory leak. |
| − | The argument {{ | + | The argument {{c|m}} used in deallocation must be not less than {{c|n}} and not greater than {{c|result.count}}, otherwise, the behavior is undefined. Note that {{c|n}} is always equal to {{c|result.count}} if the allocator does not provide {{tt|allocate_at_least}}, which means that {{c|m}} is required to be equal to {{c|n}}. |
| − | {{feature test macro|__cpp_lib_allocate_at_least|std=C++23|value= | + | {{feature test macro|__cpp_lib_allocate_at_least|std=C++23|value=202302L|{{ttt|allocate_at_least}} etc.}} |
===Example=== | ===Example=== | ||
Latest revision as of 02:03, 1 July 2024
| static constexpr std::allocation_result<pointer, size_type> allocate_at_least( Alloc& a, size_type n ); |
(since C++23) | |
allocate_at_least calls a.allocate_at_least(n) and returns its result if the call is well-formed, otherwise, it is equivalent to return {a.allocate(n), n};.
allocator_at_least tries to allocate a storage for at least n value_type objects, and provides a fallback mechanism that allocates a storage for exact n objects.
Contents |
[edit] Parameters
| a | - | an allocator used for allocating storage |
| n | - | the lower bound of number of objects to allocate storage for |
[edit] Return value
a.allocate_at_least(n) if it is well-formed.
Otherwise, std::allocation_result<pointer, size_type>{a.allocate(n), n}.
[edit] Exceptions
Throws what and when the selected allocation function throws.
[edit] Notes
The allocate_at_least member function of Allocator types are 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. Because allocate_at_least provides a fallback mechanism, it can be directly used where appropriate.
Given an allocator object a of type Alloc, let result denote the value returned from std::allocator_traits<Alloc>::allocate_at_least(a, n), the storage should be deallocated by a.deallocate(result.ptr, m) (typically called via std::allocator_traits<Alloc>::deallocate(a, result.ptr, m)) in order to avoid memory leak.
The argument m used in deallocation must be not less than n and not greater than result.count, otherwise, the behavior is undefined. Note that n is always equal to result.count if the allocator does not provide allocate_at_least, which means that m is required to be equal to n.
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_allocate_at_least |
202302L | (C++23) | allocate_at_least etc.
|
[edit] Example
| This section is incomplete Reason: no example |
[edit] See also
| (C++23) |
allocates uninitialized storage at least as large as requested size (public member function of std::allocator<T>)
|
