SHARE
TWEET

Full documentation for static_vector

a guest Aug 24th, 2019 73 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
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy. OK, I Understand
Top