std::allocator<T>::allocate_at_least

[[nodiscard]] constexpr std::allocation_result<T*, std::size_t>
    allocate_at_least( std::size_t n );

Выделяет count * sizeof(T) байт неинициализированного хранилища, где count — неопределённое целое значение, не меньшее n, вызывая ::operator new (может быть передан дополнительный аргумент std::align_val_t), но не определено, когда и как эта функция вызывается.

Затем эта функция создаёт массив типа T[count] в хранилище и начинает его жизненный цикл, но не начинает жизненный цикл ни одного из его элементов.

Для использования этой функции в константном выражении выделенное хранилище должно быть освобождено в рамках оценки этого же выражения.

Использование этой функции некорректно, если T является неполным типом.

Параметры

Возвращаемое значение

std::allocation_result<T*>{p, count}, где p указывает на первый элемент массива из count объектов типа T, элементы которых ещё не были созданы.

Исключения

Бросает std::bad_array_new_length если std::numeric_limits<std::size_t>::max() / sizeof(T) < n, или std::bad_alloc если выделение памяти завершается неудачей.

Примечания

allocate_at_least в основном предоставляется для контейнеров с непрерывным хранилищем, например, std::vector и std::basic_string, для уменьшения перераспределения, делая их ёмкость соответствующей фактическому выделенному размеру, когда это возможно.

Формулировка «неопределено, когда и как» позволяет объединять или оптимизировать выделения памяти кучи, выполняемые контейнерами стандартной библиотеки, даже если такие оптимизации запрещены для прямых вызовов ::operator new. Например, это реализовано в libc++ ([1] и [2]).

После вызова allocate_at_least и перед созданием элементов арифметика указателей T* определена внутри выделенного массива, но поведение не определено, если к элементам обращаются.

Пример

См. также