[hive.capacity]

# 23 Containers library [[containers]](./#containers)

## 23.3 Sequence containers [[sequences]](sequences#hive.capacity)

### 23.3.9 Class template hive [[hive]](hive#capacity)

#### 23.3.9.3 Capacity [hive.capacity]

[🔗](#lib:capacity,hive)

`size_type capacity() const noexcept;
`

[1](#1)

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

*Returns*: The total number of elements that *this can hold
without requiring allocation of more element blocks[.](#1.sentence-1)

[2](#2)

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

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

[🔗](#lib:reserve,hive)

`void reserve(size_type n);
`

[3](#3)

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

*Effects*: If n <= capacity() is true, there are no effects[.](#3.sentence-1)

Otherwise increases capacity() by allocating reserved blocks[.](#3.sentence-2)

[4](#4)

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

*Postconditions*: capacity() >= n is true[.](#4.sentence-1)

[5](#5)

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

*Throws*: length_error if n > max_size(),
as well as any exceptions thrown by the allocator[.](#5.sentence-1)

[6](#6)

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

*Complexity*: It does not change the size of the sequence and
takes at most linear time in the number of reserved blocks allocated[.](#6.sentence-1)

[7](#7)

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

*Remarks*: All references, pointers, and iterators referring to elements in *this,
as well as the past-the-end iterator, remain valid[.](#7.sentence-1)

[🔗](#lib:shrink_to_fit,hive)

`void shrink_to_fit();
`

[8](#8)

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

*Preconditions*: T is *Cpp17MoveInsertable* into hive[.](#8.sentence-1)

[9](#9)

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

*Effects*: shrink_to_fit is a non-binding request
to reduce capacity() to be closer to size()[.](#9.sentence-1)

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

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

— *end note*]

It does not increase capacity(), but may reduce capacity()[.](#9.sentence-3)

It may reallocate elements[.](#9.sentence-4)

If capacity() is already equal to size(), there are no effects[.](#9.sentence-5)

If an exception is thrown during allocation of a new element block,capacity() may be reduced and reallocation may occur[.](#9.sentence-6)

Otherwise if an exception is thrown, the effects are unspecified[.](#9.sentence-7)

[10](#10)

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

*Complexity*: If reallocation happens, linear in the size of the sequence[.](#10.sentence-1)

[11](#11)

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

*Remarks*: If reallocation happens,
the order of the elements in *this may change and
all references, pointers, and iterators
referring to the elements in *this,
as well as the past-the-end iterator, are invalidated[.](#11.sentence-1)

[🔗](#lib:trim_capacity,hive)

`void trim_capacity() noexcept;
void trim_capacity(size_type n) noexcept;
`

[12](#12)

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

*Effects*: For the first overload, all reserved blocks are deallocated, andcapacity() is reduced accordingly[.](#12.sentence-1)

For the second overload, capacity() is reduced to no less than n[.](#12.sentence-2)

[13](#13)

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

*Complexity*: Linear in the number of reserved blocks deallocated[.](#13.sentence-1)

[14](#14)

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

*Remarks*: All references, pointers, and iterators referring to elements in *this,
as well as the past-the-end iterator, remain valid[.](#14.sentence-1)

[🔗](#lib:block_capacity_limits,hive)

`constexpr hive_limits block_capacity_limits() const noexcept;
`

[15](#15)

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

*Returns*: *current-limits*[.](#15.sentence-1)

[16](#16)

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

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

[🔗](#lib:block_capacity_default_limits,hive)

`static constexpr hive_limits block_capacity_default_limits() noexcept;
`

[17](#17)

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

*Returns*: A hive_limits struct
with the min and max members set to
the implementation's default limits[.](#17.sentence-1)

[18](#18)

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

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

[🔗](#lib:block_capacity_hard_limits,hive)

`static constexpr hive_limits block_capacity_hard_limits() noexcept;
`

[19](#19)

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

*Returns*: A hive_limits struct
with the min and max members set to
the implementation's hard limits[.](#19.sentence-1)

[20](#20)

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

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

[🔗](#lib:reshape,hive)

`void reshape(hive_limits block_limits);
`

[21](#21)

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

*Preconditions*: T is *Cpp17MoveInsertable* into hive[.](#21.sentence-1)

[22](#22)

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

*Effects*: For any active blocks not within the bounds of block_limits,
the elements within those active blocks are reallocated
to new or existing element blocks which are within the bounds[.](#22.sentence-1)

Any element blocks not within the bounds of block_limits are deallocated[.](#22.sentence-2)

If an exception is thrown during allocation of a new element block,capacity() may be reduced,
reallocation may occur, and*current-limits* may be assigned
a value other than block_limits[.](#22.sentence-3)

Otherwise block_limits is assigned to *current-limits*[.](#22.sentence-4)

If any other exception is thrown the effects are unspecified[.](#22.sentence-5)

[23](#23)

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

*Postconditions*: size() is unchanged[.](#23.sentence-1)

[24](#24)

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

*Complexity*: Linear in the number of element blocks in *this[.](#24.sentence-1)

If reallocation happens, also linear in the number of elements reallocated[.](#24.sentence-2)

[25](#25)

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

*Remarks*: This operation may change capacity()[.](#25.sentence-1)

If reallocation happens, the order of the elements in *this may change[.](#25.sentence-2)

Reallocation invalidates all references, pointers, and iterators
referring to the elements in *this,
as well as the past-the-end iterator[.](#25.sentence-3)

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

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

— *end note*]