std::alloca...te_at_least(3)

🌸 NAME 🌸

std::allocator_traits::allocate_at_least — that’s the page title, bestie, and we’re in the C++ Standard Libary manual. This whole page is about std::allocator_traits::allocate_at_least, and it’s giving “niche allocator lore but make it cute.” 🎀

✨ Synopsis ✨

Since C++23 (the original synopsis literally has (since C++23), so we’re keeping that energy):

[[nodiscard]] static constexpr std::allocation_result<pointer,
size_type>
allocate_at_least( Alloc& a, size_type n );

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.

💖 Parameters 💖

• a — an allocator used for allocating storage.
• n — the lower bound of number of objects to allocate storage for.

🫶 Return value 🫶

• a.allocate_at_least(n) if it is well-formed.
• Otherwise, std::allocation_result<pointer, size_type>{a.allocate(n), n}.

🔥 Exceptions 🔥

Throws what and when the selected allocation function throws. No cap.

🧚 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.

⚠️ That undefined behavior bit is not a vibe. Respect the m bounds, bestie.

Feature-test macro, in all its spreadsheet glory:

• __cpp_lib_allocate_at_least — value 202302L — Std (C++23) — feature allocate_at_least etc.

😭 Example 😭

This section is incomplete.

Reason: no example.

Bestie, that’s the whole example section. It’s giving placeholder energy. 💀

🌈 See also 🌈

• allocate_at_least allocates uninitialized storage at least as large as requested (C++23)
• size (public member function of std::allocator<T>)

🏷️ Category 🏷️

• Todo no example

---

Cute sign-off: this page came from http://cppreference.com, dated 2024.06.10. Bye bestie — go allocate at least as much as you need. 💅✨