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

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

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

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

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