array::insert

## `array::insert`

Insert elements before the specified location.

### Synopsis

    array::iterator
    insert(
        array::const_iterator pos,
        value const& jv); (1)

    array::iterator
    insert(
        array::const_iterator pos,
        value&& jv); (2)

    array::iterator
    insert(
        array::const_iterator pos,
        std::size_t count,
        value const& jv); (3)

    template<
        class InputIt>
    array::iterator
    insert(
        array::const_iterator pos,
        InputIt first,
        InputIt last); (4)

    array::iterator
    insert(
        array::const_iterator pos,
        std::initializer_list< value_ref > init); (5)

### Description

- (1) and (2) insert a single new element before `pos`. (1) copy-constructs and (2) move-constructs the new element from `jv`.

- (3) inserts `count` copies of `jv` before `pos`.

- (4) the elements in the range `[first, last)` are inserted in order.

- (5) the elements of the initializer list `init` are inserted in order.

Inserted values will be constructed using the container’s associated `boost::container::pmr::memory_resource`.

| Overload (2) is equivalent to (1) if `*jv.storage() != *this->storage()`.

If the size of the array after insertion would have exceeded `capacity()`, a reallocation occurs first, and all iterators and references are invalidated. Otherwise, only the iterators and references from the insertion point forward are invalidated. All past-the-end iterators are also invalidated.

### Preconditions

`first` and `last` are not iterators into `*this`.

### Constraints

    ! std::is_convertible_v<InputIt, value>
    std::is_constructible_v<value, std::iterator_traits<InputIt>::reference>

### Complexity

- (1), (2) linear in `std::distance(pos, end())`.

- (3) linear in `count + std::distance(pos, end())`.

- (4) linear in `std::distance(first, last) + std::distance(pos, end())`.

- (5) linear in `init.size() + std::distance(pos, end())`.

### Exception Safety

(4) provides strong guarantee if `InputIt` satisfies LegacyForwardIterator, and basic guarantee otherwise. Other overloads provide strong guarantee. Calls to `memory_resource::allocate` may throw.

### Template Parameters

Type | Description
--- | ---
`InputIt` | a type satisfying the requirements of LegacyInputIterator.

### Return Value

An iterator to the first inserted value, or `pos` if no values were inserted.

### Parameters

Name | Description
--- | ---
`pos` | Iterator before which the new elements will be inserted. This may be the `end()` iterator.
`jv` | The value to insert. A copy will be made using container’s associated `boost::container::pmr::memory_resource`.
`count` | The number of copies to insert.
`first` | An input iterator pointing to the first element to insert, or pointing to the end of the range.
`last` | An input iterator pointing to the end of the range.
`init` | The initializer list to insert

Edit this page