CKTIS / C++
std::basic_string::reserve — capacidade e tamanho
`reserve(n)` prepara espaço para elementos futuros sem alterar quantos existem. `resize(n)` altera esse número tanto em cadeias de caracteres como em vetores.
Versão: ISO C++23; implementation support may vary
Sintaxe
ISO C++23 member declarations (excerpts):
// <string>, in std::basic_string<CharT, Traits, Allocator>
constexpr void reserve(size_type n);
void reserve(); // Deprecated since C++20
constexpr void resize(size_type n);
constexpr void resize(size_type n, CharT c);
// <vector>, in std::vector<T, Allocator>
constexpr void reserve(size_type n);
constexpr void resize(size_type n);
constexpr void resize(size_type n, const T& value);std::basic_string::reserve é declarado em <string> e está disponível em std::string. Em C++23, após uma chamada bem-sucedida a s.reserve(n), verifica-se capacity() >= n, mas size() e o conteúdo mantêm-se. n é a capacidade total mínima, não o número de caracteres adicionais. Se n <= capacity(), não há realocação e a capacidade mantém-se. Caso contrário, o armazenamento é realocado e a capacidade pode ficar acima de n.
std::vector::reserve(n), em <vector>, segue a mesma regra de capacidade sem criar elementos. A realocação invalida os ponteiros, referências e iteradores existentes para os elementos, assim como o iterador de fim. Um vetor garante que as inserções seguintes não provocam realocação enquanto nenhuma inserção fizer ultrapassar a capacidade. Não pressuponhas essa garantia para operações que modificam cadeias de caracteres.
Usa resize(n) quando precisares de exatamente n elementos: ao diminuir o tamanho, remove os elementos finais; ao aumentá-lo, acrescenta novos elementos. As sobrecargas s.resize(n, c) e v.resize(n, value) preenchem as novas posições com o valor indicado. A capacidade não utilizada não alarga o intervalo de índices dos elementos: escreve num elemento apenas se i < size(). Numa cadeia, s[s.size()] refere-se ao terminador nulo, não a um carácter adicional da cadeia.
std::basic_string::reserve(n) lança std::length_error se n > max_size() e pode propagar uma exceção do alocador, como std::bad_alloc. Se for lançada uma exceção, a cadeia não se altera. A sobrecarga distinta s.reserve() sem argumentos é um pedido não vinculativo de redução da capacidade. Esta sobrecarga está formalmente marcada como obsoleta desde C++20, mas ainda está presente em C++23. Usa s.shrink_to_fit() para fazer esse pedido; a redução não é garantida.
Exemplos
#include <iostream>
#include <string>
#include <vector>
int main() {
std::string s = "hi";
std::vector<int> v{1, 2};
s.reserve(64);
v.reserve(64);
std::cout << std::boolalpha;
std::cout << "string reserve: " << static_cast<unsigned int>(s.size()) << ' '
<< (s.capacity() >= 64) << ' ' << s << '\n';
std::cout << "vector reserve: " << static_cast<unsigned int>(v.size()) << ' '
<< (v.capacity() >= 64) << ' ' << v[0] << ' ' << v[1] << '\n';
s.resize(4, '!');
v.resize(4, 9);
std::cout << "string resize: " << static_cast<unsigned int>(s.size())
<< ' ' << s << '\n';
std::cout << "vector resize: " << static_cast<unsigned int>(v.size())
<< ' ' << v[2] << ' ' << v[3] << '\n';
}Resultado
string reserve: 2 true hi vector reserve: 2 true 1 2 string resize: 4 hi!! vector resize: 4 9 9
Depois de `reserve(64)`, ambos os contentores continuam a ter dois elementos. O programa verifica apenas o limite inferior da capacidade; é `resize` que acrescenta dois elementos a cada contentor.
Lições relacionadas
- C++ · Lição 5 · Avançado · Versão: 3
Fontes
- C++23 working draft N4950 — [string.capacity], [string.require], [string.access], [vector.capacity], [depr.string.capacity]
- C++ working draft — Capacity [string.capacity]
- C++ working draft — Capacity [vector.capacity]
- C++ working draft — General requirements [string.require]
- P2870R0 — Remove basic_string::reserve() From C++26