cppdraft_translate/cppdraft/string/capacity.md

[string.capacity]

27 Strings library [strings]

27.4 String classes [string.classes]

27.4.3 Class template basic_string [basic.string]

27.4.3.5 Capacity [string.capacity]

🔗

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

1

#

Returns: A count of the number of char-like objects currently in the string.

2

#

Complexity: Constant time.

🔗

constexpr size_type max_size() const noexcept;

3

#

Returns: The largest possible number of char-like objects that can be stored in abasic_string.

4

#

Complexity: Constant time.

🔗

constexpr void resize(size_type n, charT c);

5

#

Effects: Alters the value of*this as follows:

• (5.1)

  Ifn <= size(), erases the last size() - n elements.

• (5.2)

  Ifn > size(), appends n - size() copies of c.

🔗

constexpr void resize(size_type n);

6

#

Effects: Equivalent to resize(n, charT()).

🔗

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

7

#

Let

• (7.1)

  o = size() before the call to resize_and_overwrite.

• (7.2)

  k be min(o, n).

• (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. The values in the range [p + k, p + n] may be indeterminate ([basic.indet]).

• (7.4)

  m be a value of type size_type or const size_type equal to n.

• (7.5)

  OP be the expression std​::​move(op)(p, m).

• (7.6)

  r = OP.

8

#

Mandates: OP has an integer-like type ([iterator.concept.winc]).

9

#

Preconditions:

• (9.1)

  OP does not throw an exception or modify p or m.

• (9.2)

  r ≥ 0.

• (9.3)

  r ≤ m.

• (9.4)

  After evaluating OP there are no indeterminate values in the range [p, p + r).

10

#

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

11

#

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.

🔗

constexpr size_type capacity() const noexcept;

12

#

Returns: The size of the allocated storage in the string.

13

#

Complexity: Constant time.

🔗

constexpr void reserve(size_type res_arg);

14

#

Effects: A directive that informs a basic_string of a planned change in size, so that the storage allocation can be managed accordingly.

Following a call toreserve,capacity() is greater or equal to the argument ofreserve if reallocation happens; and equal to the previous value ofcapacity() otherwise.

Reallocation happens at this point if and only if the current capacity is less than the argument of reserve.

15

#

Throws: length_error ifres_arg > max_size() or any exceptions thrown byallocator_traits ​::​allocate.

🔗

constexpr void shrink_to_fit();

16

#

Effects: shrink_to_fit is a non-binding request to reducecapacity() to size().

[Note 1:

The request is non-binding to allow latitude for implementation-specific optimizations.

— end note]

It does not increase capacity(), but may reduce capacity() by causing reallocation.

17

#

Complexity: If the size is not equal to the old capacity, linear in the size of the sequence; otherwise constant.

18

#

Remarks: Reallocation invalidates all the references, pointers, and iterators referring to the elements in the sequence, as well as the past-the-end iterator.

[Note 2:

If no reallocation happens, they remain valid.

— end note]

🔗

constexpr void clear() noexcept;

19

#

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

🔗

constexpr bool empty() const noexcept;

20

#

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