Init
This commit is contained in:
261
cppdraft/hive/capacity.md
Normal file
261
cppdraft/hive/capacity.md
Normal file
@@ -0,0 +1,261 @@
|
||||
[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*]
|
||||
Reference in New Issue
Block a user