Guest User

Full documentation for static_vector

a guest
Aug 24th, 2019
77
Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
  1. /**
  2. * @brief Vector with stack storage.
  3. *
  4. * `static_vector` never allocates dynamic memory. (The
  5. * `static_vector` object itself may still be placed on the heap
  6. * if the user prefers to.) The elements are allocated as part of
  7. * the vector object itself. This can be useful when dynamic
  8. * memory allocation is to be avoided. As a result, there is a
  9. * compile-time determined limit on the size, supplied as the
  10. * template parameter `N`. Internally, `static_vector` holds a
  11. * data member of type
  12. * `std::array<std::aligned_storage_t<sizeof(T), alignof(T)>, N>`.
  13. * The program is ill-formed if it attempts to instantiate
  14. * `static_vector<T, N>` where `N >
  15. * std::numeric_limits<std::ptrdiff_t>::%max()`.
  16. *
  17. * Functions without side effects and never trigger undefined
  18. * behavior or throw an exception are marked `[[nodiscard]]` and
  19. * `noexcept` (e.g., `size()` and `empty()`, but not `at()` or
  20. * `front()`), with the exception that `clear()` is marked
  21. * `noexcept`. A function that potentially triggers undefined
  22. * behavior is not marked `noexcept`.
  23. *
  24. * The destruction of elements are in an unspecified order. In
  25. * particular, the elements are not guaranteed to be destroyed in
  26. * the reverse order of construction. The program is ill-formed
  27. * if it attempts to instantiate `static_vector<T, N>` where
  28. * `!std::%is_destructible_v<T>`. The behavior is undefined if
  29. * the destruction of an element throws an exception.
  30. *
  31. * ### Relationship with `std::vector`
  32. *
  33. * All functionalities of `std::vector` are implemented, except
  34. * `capacity`, `reserve`, and `shrink_to_fit`. `static_vector`
  35. * provides (not amortized) constant time insert and erase
  36. * operations at the end.
  37. *
  38. * Unlike `std::vector`, `static_vector` is SFINAE-friendly.
  39. * Instead of producing an instantiation error, the functions do
  40. * not participate in overload resolution unless certain
  41. * conditions are met.
  42. *
  43. * There is nothing special with `static_vector<bool, N>` &mdash;
  44. * it is a normal container type with normal semantics, unlike
  45. * `std::vector<bool, A>` which differs substantially from other
  46. * `std::vector`s.
  47. *
  48. * There are some extended functionalities in addition to those
  49. * provided in `std::vector`. These functions are designated as
  50. * "extended functionality." Every `insert` function that
  51. * potentially inserts more than one element has a corresponding
  52. * `insert_back` version. The latter always inserts at the end,
  53. * so they can be used even if the element type cannot be moved.
  54. * These functions do not reuse the name `push_back` because the
  55. * one-parameter version will invalidate conventional usage like
  56. * `push_back({})`. `pop_back` also has an overload that accepts
  57. * a size parameter and removes the specified number of elements
  58. * at the end. This overload does not use a new name because it
  59. * does not change the meaning of conventional usage. `assign`
  60. * has an overload that replaces the contents of the vector with a
  61. * specified number of value-initialized elements. There is also
  62. * a `compare` function that performs three-way comparison.
  63. *
  64. * `static_vector` does not have any deduction guides. The
  65. * template arguments of `static_vector` can be deduced only when
  66. * the copy constructor or the move constructor is called.
  67. *
  68. * ### Relationship with the standard container requirements
  69. *
  70. * For all types `T` such that `std::is_destructible_v<T>` and all
  71. * values `N` of type `std::size_t` such that `N <=
  72. * std::numeric_limits<std::ptrdiff_t>::%max()`, `static_vector<T,
  73. * N>` is a container with the following exceptions:
  74. *
  75. * - The move constructor calls the move constructor on each
  76. * individual element. Thus, it is of linear complexity, not
  77. * constant.
  78. *
  79. * - `swap` calls `swap` on each individual element. Thus, it is
  80. * of linear complexity, not constant. If swapping an element
  81. * throws an exception, the exception is propagated. An
  82. * iterator that refers to element in one of the vectors still
  83. * refers to an element in the same vector; see iterator
  84. * invalidation rules for details.
  85. *
  86. * It is a reversible container and a contiguous container. It
  87. * implements the operations in Table 85. It is a sequence
  88. * container except that `emplace` and `insert` require
  89. * `std::is_move_constructible_v<T>`,
  90. * `std::is_move_assignable_v<T>`, and `std::is_swappable_v<T>`.
  91. * It implements the same operations in Table 88 as `std::vector`
  92. * does.
  93. *
  94. * `static_vector` does not use allocators.
  95. *
  96. * ### Iterator invalidation rules
  97. *
  98. * The underlying storage of `static_vector` is fixed; therefore,
  99. * during the lifetime of the vector, an iterator that originally
  100. * points to the `i`th element in the vector always points to the
  101. * `i`th element in the vector as long as the size of the vector
  102. * is greater than or equal to `i`, where indexing is zero-based
  103. * and the past-the-end iterator is considered to point to the
  104. * `size()`th element of the vector. The iterator is invalidated
  105. * if an operation causes the size of the vector to be less than
  106. * `i`. The iterator is re-validated if a later operation causes
  107. * the size of the vector to be greater than or equal to `i`
  108. * again. For example:
  109. *
  110. * ```
  111. * static_vector<int, 5> vec{0, 1, 2};
  112. * auto i = vec.begin() + 1;
  113. * auto j = vec.end();
  114. *
  115. * vec.resize(2);
  116. * // i points to the element with value 1
  117. * // j is invalidated
  118. *
  119. * vec.resize(4);
  120. * // i points to the element with value 1
  121. * // j points to the last element (with value 0)
  122. *
  123. * vec.resize(1);
  124. * // i is the past-the-end iterator
  125. * // j is invalidated
  126. *
  127. * vec.insert(i, {1, 2, 3, 4});
  128. * // i points to the element with value 1
  129. * // j points to the element with value 3
  130. * ```
  131. *
  132. * The same applies to pointers and references.
  133. *
  134. * ### Exception safety guarantee
  135. *
  136. * The basic exception safety guarantee is always provided &mdash;
  137. * `static_vector` always destroys all objects it constructs. The
  138. * nothrow exception safety guarantee is provided for `noexcept`
  139. * functions.
  140. *
  141. * Since `static_vector` is designed to be optimized for memory,
  142. * it tries not to allocate unnecessary memory. In particular,
  143. * `static_vector` never allocates another `static_vector`.
  144. * Therefore, strong exception safety cannot be provided in some
  145. * situations. For example, it is not possible for the copy
  146. * assignment operator to provide strong exception safety &mdash;
  147. * in order to recover the initial contents, a copy has to be
  148. * made.
  149. *
  150. * All functions have no effect on the vector if a length error is
  151. * detected, with the exception that the functions that accept an
  152. * iterator pair leave the vector in a partially modified state in
  153. * this case if the supplied iterators are not random access
  154. * iterators. See the documentation of these functions for
  155. * details.
  156. *
  157. * The insertion functions, the `resize` function, and the `swap`
  158. * function have no effect on the vector if the initialization of
  159. * an element throws an exception. The `emplace` and `insert`
  160. * functions leave the vector in a valid but otherwise unspecified
  161. * state if the move constructor, move assignment operator, or
  162. * `swap` on the elements throws an exception when the inserted
  163. * elements are being rotated to the desired position.
  164. *
  165. * The assignment operators and the `assign` function leave the
  166. * vector empty if the initialization of an element throws an
  167. * exception, with the exception that the iterator range version
  168. * of `assign` leaves the vector in a partially modified state in
  169. * this case if the supplied iterators are not random access
  170. * iterators. See its documentation for details.
  171. *
  172. * @tparam T The element type.
  173. * @tparam N The maximum size of the vector.
  174. */
RAW Paste Data