cppdraft_translate/cppdraft/string/capacity.md

[string.capacity]

# 27 Strings library [[strings]](./#strings)

## 27.4 String classes [[string.classes]](string.classes#string.capacity)

### 27.4.3 Class template basic_string [[basic.string]](basic.string#string.capacity)

#### 27.4.3.5 Capacity [string.capacity]

[🔗](#lib:size,basic_string)

`constexpr size_type size() const noexcept;
constexpr size_type length() const noexcept;
`

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2872)

*Returns*: A count of the number of char-like objects currently in the string[.](#1.sentence-1)

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2876)

*Complexity*: Constant time[.](#2.sentence-1)

[🔗](#lib:max_size,basic_string)

`constexpr size_type max_size() const noexcept;
`

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2887)

*Returns*: The largest possible number of char-like objects that can be stored in abasic_string[.](#3.sentence-1)

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2892)

*Complexity*: Constant time[.](#4.sentence-1)

[🔗](#lib:resize,basic_string)

`constexpr void resize(size_type n, charT c);
`

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2903)

*Effects*: Alters the value of*this as follows:

- [(5.1)](#5.1)

  Ifn <= size(),
erases the last size() - n elements[.](#5.1.sentence-1)

- [(5.2)](#5.2)

  Ifn > size(),
appends n - size() copies of c[.](#5.2.sentence-1)

[🔗](#lib:resize,basic_string_)

`constexpr void resize(size_type n);
`

[6](#6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2926)

*Effects*: Equivalent to resize(n, charT())[.](#6.sentence-1)

[🔗](#lib:resize_and_overwrite,basic_string)

`template<class Operation> constexpr void resize_and_overwrite(size_type n, Operation op);
`

[7](#7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2937)

Let

- [(7.1)](#7.1)

  o = size() before the call to resize_and_overwrite[.](#7.1.sentence-1)

- [(7.2)](#7.2)

  k be min(o, n)[.](#7.2.sentence-1)

- [(7.3)](#7.3)

  p be a value of type charT* or charT* const,
such that the range [p, p + n] is valid andthis->compare(0, k, p, k) == 0 is true before the call[.](#7.3.sentence-1)
  The values in the range [p + k, p + n] may be indeterminate ([[basic.indet]](basic.indet "6.8.5 Indeterminate and erroneous values"))[.](#7.3.sentence-2)

- [(7.4)](#7.4)

  m be a value of type size_type or const size_type equal to n[.](#7.4.sentence-1)

- [(7.5)](#7.5)

  *OP* be the expression std​::​move(op)(p, m)[.](#7.5.sentence-1)

- [(7.6)](#7.6)

  r = *OP*[.](#7.6.sentence-1)

[8](#8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2958)

*Mandates*: *OP* has an integer-like type ([[iterator.concept.winc]](iterator.concept.winc "24.3.4.4 Concept weakly_­incrementable"))[.](#8.sentence-1)

[9](#9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2962)

*Preconditions*: 

- [(9.1)](#9.1)

  *OP* does not throw an exception or modify p or m[.](#9.1.sentence-1)

- [(9.2)](#9.2)

  r ≥ 0[.](#9.2.sentence-1)

- [(9.3)](#9.3)

  r ≤ m[.](#9.3.sentence-1)

- [(9.4)](#9.4)

  After evaluating *OP* there are no indeterminate values in the range [p, p + r)[.](#9.4.sentence-1)

[10](#10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2976)

*Effects*: Evaluates *OP*,
replaces the contents of *this with [p, p + r), and
invalidates all pointers and references to the range [p, p + n][.](#10.sentence-1)

[11](#11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2982)

*Recommended practice*: Implementations should avoid unnecessary copies and allocations
by, for example, making p a pointer into internal storage and
by restoring *(p + r) to charT() after evaluating *OP*[.](#11.sentence-1)

[🔗](#lib:capacity,basic_string)

`constexpr size_type capacity() const noexcept;
`

[12](#12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2995)

*Returns*: The size of the allocated storage in the string[.](#12.sentence-1)

[13](#13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L2999)

*Complexity*: Constant time[.](#13.sentence-1)

[🔗](#lib:reserve,basic_string)

`constexpr void reserve(size_type res_arg);
`

[14](#14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L3010)

*Effects*: A directive that informs a basic_string of a planned change in size,
so that the storage allocation can be managed accordingly[.](#14.sentence-1)

Following a call toreserve,capacity() is greater or equal to the argument ofreserve if reallocation happens; and
equal to the previous value ofcapacity() otherwise[.](#14.sentence-2)

Reallocation happens at this point if and only if
the current capacity is less than the argument of reserve[.](#14.sentence-3)

[15](#15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L3026)

*Throws*: length_error ifres_arg > max_size() or any exceptions thrown byallocator_traits <Allocator>​::​allocate[.](#15.sentence-1)

[🔗](#lib:shrink_to_fit,basic_string)

`constexpr void shrink_to_fit();
`

[16](#16)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L3040)

*Effects*: shrink_to_fit is a non-binding request to reducecapacity() to size()[.](#16.sentence-1)

[*Note [1](#note-1)*:

The request is non-binding to
allow latitude for implementation-specific optimizations[.](#16.sentence-2)

— *end note*]

It does not increase capacity(), but may reduce capacity() by causing reallocation[.](#16.sentence-3)

[17](#17)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L3051)

*Complexity*: If the size is not equal to the old capacity,
linear in the size of the sequence;
otherwise constant[.](#17.sentence-1)

[18](#18)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L3057)

*Remarks*: Reallocation invalidates all the references, pointers, and iterators
referring to the elements in the sequence, as well as the past-the-end iterator[.](#18.sentence-1)

[*Note [2](#note-2)*:

If no reallocation happens, they remain valid[.](#18.sentence-2)

— *end note*]

[🔗](#lib:clear,basic_string)

`constexpr void clear() noexcept;
`

[19](#19)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L3072)

*Effects*: Equivalent to: erase(begin(), end());

[🔗](#lib:empty,basic_string)

`constexpr bool empty() const noexcept;
`

[20](#20)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/strings.tex#L3083)

*Effects*: Equivalent to:return size() == 0;