Full documentation for static_vector

    /**
     * @brief Vector with stack storage.
     *
     * `static_vector` never allocates dynamic memory.  (The
     * `static_vector` object itself may still be placed on the heap
     * if the user prefers to.)  The elements are allocated as part of
     * the vector object itself.  This can be useful when dynamic
     * memory allocation is to be avoided.  As a result, there is a
     * compile-time determined limit on the size, supplied as the
     * template parameter `N`.  Internally, `static_vector` holds a
     * data member of type
     * `std::array<std::aligned_storage_t<sizeof(T), alignof(T)>, N>`.
     * The program is ill-formed if it attempts to instantiate
     * `static_vector<T, N>` where `N >
     * std::numeric_limits<std::ptrdiff_t>::%max()`.
     *
     * Functions without side effects and never trigger undefined
     * behavior or throw an exception are marked `[[nodiscard]]` and
     * `noexcept` (e.g., `size()` and `empty()`, but not `at()` or
     * `front()`), with the exception that `clear()` is marked
     * `noexcept`.  A function that potentially triggers undefined
     * behavior is not marked `noexcept`.
     *
     * The destruction of elements are in an unspecified order.  In
     * particular, the elements are not guaranteed to be destroyed in
     * the reverse order of construction.  The program is ill-formed
     * if it attempts to instantiate `static_vector<T, N>` where
     * `!std::%is_destructible_v<T>`.  The behavior is undefined if
     * the destruction of an element throws an exception.
     *
     * ### Relationship with `std::vector`
     *
     * All functionalities of `std::vector` are implemented, except
     * `capacity`, `reserve`, and `shrink_to_fit`.  `static_vector`
     * provides (not amortized) constant time insert and erase
     * operations at the end.
     *
     * Unlike `std::vector`, `static_vector` is SFINAE-friendly.
     * Instead of producing an instantiation error, the functions do
     * not participate in overload resolution unless certain
     * conditions are met.
     *
     * There is nothing special with `static_vector<bool, N>` &mdash;
     * it is a normal container type with normal semantics, unlike
     * `std::vector<bool, A>` which differs substantially from other
     * `std::vector`s.
     *
     * There are some extended functionalities in addition to those
     * provided in `std::vector`.  These functions are designated as
     * "extended functionality."  Every `insert` function that
     * potentially inserts more than one element has a corresponding
     * `insert_back` version.  The latter always inserts at the end,
     * so they can be used even if the element type cannot be moved.
     * These functions do not reuse the name `push_back` because the
     * one-parameter version will invalidate conventional usage like
     * `push_back({})`.  `pop_back` also has an overload that accepts
     * a size parameter and removes the specified number of elements
     * at the end.  This overload does not use a new name because it
     * does not change the meaning of conventional usage.  `assign`
     * has an overload that replaces the contents of the vector with a
     * specified number of value-initialized elements.  There is also
     * a `compare` function that performs three-way comparison.
     *
     * `static_vector` does not have any deduction guides.  The
     * template arguments of `static_vector` can be deduced only when
     * the copy constructor or the move constructor is called.
     *
     * ### Relationship with the standard container requirements
     *
     * For all types `T` such that `std::is_destructible_v<T>` and all
     * values `N` of type `std::size_t` such that `N <=
     * std::numeric_limits<std::ptrdiff_t>::%max()`, `static_vector<T,
     * N>` is a container with the following exceptions:
     *
     * - The move constructor calls the move constructor on each
     *   individual element.  Thus, it is of linear complexity, not
     *   constant.
     *
     * - `swap` calls `swap` on each individual element.  Thus, it is
     *   of linear complexity, not constant.  If swapping an element
     *   throws an exception, the exception is propagated.  An
     *   iterator that refers to element in one of the vectors still
     *   refers to an element in the same vector; see iterator
     *   invalidation rules for details.
     *
     * It is a reversible container and a contiguous container.  It
     * implements the operations in Table 85.  It is a sequence
     * container except that `emplace` and `insert` require
     * `std::is_move_constructible_v<T>`,
     * `std::is_move_assignable_v<T>`, and `std::is_swappable_v<T>`.
     * It implements the same operations in Table 88 as `std::vector`
     * does.
     *
     * `static_vector` does not use allocators.
     *
     * ### Iterator invalidation rules
     *
     * The underlying storage of `static_vector` is fixed; therefore,
     * during the lifetime of the vector, an iterator that originally
     * points to the `i`th element in the vector always points to the
     * `i`th element in the vector as long as the size of the vector
     * is greater than or equal to `i`, where indexing is zero-based
     * and the past-the-end iterator is considered to point to the
     * `size()`th element of the vector.  The iterator is invalidated
     * if an operation causes the size of the vector to be less than
     * `i`.  The iterator is re-validated if a later operation causes
     * the size of the vector to be greater than or equal to `i`
     * again.  For example:
     *
     * ```
     * static_vector<int, 5> vec{0, 1, 2};
     * auto i = vec.begin() + 1;
     * auto j = vec.end();
     *
     * vec.resize(2);
     * // i points to the element with value 1
     * // j is invalidated
     *
     * vec.resize(4);
     * // i points to the element with value 1
     * // j points to the last element (with value 0)
     *
     * vec.resize(1);
     * // i is the past-the-end iterator
     * // j is invalidated
     *
     * vec.insert(i, {1, 2, 3, 4});
     * // i points to the element with value 1
     * // j points to the element with value 3
     * ```
     *
     * The same applies to pointers and references.
     *
     * ### Exception safety guarantee
     *
     * The basic exception safety guarantee is always provided &mdash;
     * `static_vector` always destroys all objects it constructs.  The
     * nothrow exception safety guarantee is provided for `noexcept`
     * functions.
     *
     * Since `static_vector` is designed to be optimized for memory,
     * it tries not to allocate unnecessary memory.  In particular,
     * `static_vector` never allocates another `static_vector`.
     * Therefore, strong exception safety cannot be provided in some
     * situations.  For example, it is not possible for the copy
     * assignment operator to provide strong exception safety &mdash;
     * in order to recover the initial contents, a copy has to be
     * made.
     *
     * All functions have no effect on the vector if a length error is
     * detected, with the exception that the functions that accept an
     * iterator pair leave the vector in a partially modified state in
     * this case if the supplied iterators are not random access
     * iterators.  See the documentation of these functions for
     * details.
     *
     * The insertion functions, the `resize` function, and the `swap`
     * function have no effect on the vector if the initialization of
     * an element throws an exception.  The `emplace` and `insert`
     * functions leave the vector in a valid but otherwise unspecified
     * state if the move constructor, move assignment operator, or
     * `swap` on the elements throws an exception when the inserted
     * elements are being rotated to the desired position.
     *
     * The assignment operators and the `assign` function leave the
     * vector empty if the initialization of an element throws an
     * exception, with the exception that the iterator range version
     * of `assign` leaves the vector in a partially modified state in
     * this case if the supplied iterators are not random access
     * iterators.  See its documentation for details.
     *
     * @tparam T The element type.
     * @tparam N The maximum size of the vector.
     */