[#BloombergLP-bslalg-ArrayPrimitives-insert-0ad]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bslalg.adoc[bslalg]::xref:BloombergLP/bslalg/ArrayPrimitives.adoc[ArrayPrimitives]::insert
:relfileprefix: ../../../
:mrdocs:

`insert` overloads

== Synopses

Declared in `&lt;bslalg&lowbar;arrayprimitives&period;h&gt;`

Insert the specified `value` into the array of `allocator&lowbar;traits&lt;ALLOCATOR&gt;&colon;&colon;value&lowbar;type` objects at the specified `toBegin` location, shifting forward the elements from `toBegin` to the specified `toEnd` location by one position&period; `value` is left in a valid but unspecified state&period; If a (copy or move) constructor or a (copy or move) assignment operator throws an exception, then any elements created after `toEnd` are destroyed and the elements in the range `&lsqb;toBegin &period;&period; toEnd )&rsqb;` are left in a valid but unspecified state&period; The behavior is undefined unless `toBegin` refers to sufficient space to hold at least `toEnd &hyphen; toBegin &plus; 1` elements&period;


[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;class ALLOCATOR&gt;
static
void
xref:BloombergLP/bslalg/ArrayPrimitives/insert-04.adoc[insert](
    bsl::allocator&lowbar;traits&lt;ALLOCATOR&gt;::pointer toBegin,
    bsl::allocator&lowbar;traits&lt;ALLOCATOR&gt;::pointer toEnd,
    xref:BloombergLP/bslmf/MovableRef.adoc[bslmf::MovableRef&lt;bsl::allocator&lowbar;traits&lt;ALLOCATOR&gt;::value&lowbar;type&gt;] value,
    ALLOCATOR allocator);
----

[.small]#xref:BloombergLP/bslalg/ArrayPrimitives/insert-04.adoc[_» more&period;&period;&period;_]#

Insert the specified `value` into the array of the (template parameter) type `TARGET&lowbar;TYPE` at the specified `toBegin` address, shifting the elements from `toBegin` to the specified `toEnd` address by one position towards larger addresses&period; `value` is left in a valid but unspecified state&period; If a (copy or move) constructor or a (copy or move) assignment operator throws an exception, then any elements created after `toEnd` are destroyed and the elements in the range `&lsqb;toBegin &period;&period; toEnd )&rsqb;` are left in a valid but unspecified state&period; The behavior is undefined unless `toBegin` refers to sufficient space to hold at least `toEnd &hyphen; toBegin &plus; 1` elements&period;


[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;class TARGET&lowbar;TYPE&gt;
static
void
xref:BloombergLP/bslalg/ArrayPrimitives/insert-0d.adoc[insert](
    TARGET&lowbar;TYPE* toBegin,
    TARGET&lowbar;TYPE* toEnd,
    xref:BloombergLP/bslmf/MovableRef.adoc[bslmf::MovableRef&lt;TARGET&lowbar;TYPE&gt;] value,
    xref:BloombergLP/bslma/Allocator.adoc[bslma::Allocator]* allocator);
----

[.small]#xref:BloombergLP/bslalg/ArrayPrimitives/insert-0d.adoc[_» more&period;&period;&period;_]#

Insert the specified `numElements` copies of the specified `value` into the array of type `allocator&lowbar;traits&lt;ALLOCATOR&gt;&colon;&colon;value&lowbar;type` starting at the specified `toBegin` location, shifting forward the elements from `toBegin` to the specified `toEnd` location by `numElements` positions&period; If a (copy or move) constructor or a (copy or move) assignment operator throws an exception, any elements created after `toEnd` are destroyed and the elements in the range `&lsqb;toBegin &period;&period; toEnd)&rsqb;` are left in a valid but unspecified state&period; The behavior is undefined unless `toBegin` refers to space sufficient to hold at least `toEnd &hyphen; toBegin &plus; numElements` elements&period;


[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;class ALLOCATOR&gt;
static
void
xref:BloombergLP/bslalg/ArrayPrimitives/insert-09.adoc[insert](
    bsl::allocator&lowbar;traits&lt;ALLOCATOR&gt;::pointer toBegin,
    bsl::allocator&lowbar;traits&lt;ALLOCATOR&gt;::pointer toEnd,
    bsl::allocator&lowbar;traits&lt;ALLOCATOR&gt;::value&lowbar;type const& value,
    xref:BloombergLP/bslalg/ArrayPrimitives/size_type.adoc[size&lowbar;type] numElements,
    ALLOCATOR allocator);
----

[.small]#xref:BloombergLP/bslalg/ArrayPrimitives/insert-09.adoc[_» more&period;&period;&period;_]#

Insert the specified `numElements` copies of the specified `value` into the array of (template parameter) `TARGET&lowbar;TYPE` starting at the specified `toBegin` address and ending immediately before the specified `toEnd` address, shifting the elements in the array by `numElements` positions towards larger addresses&period; The behavior is undefined unless the destination array contains at least `numElements` uninitialized elements after `toEnd`&period; If a copy constructor or assignment operator for `TARGET&lowbar;TYPE` throws an exception, then any elements created after `toEnd` are destroyed and the elements in the range `&lsqb; toBegin, toEnd )&rsqb;` will have unspecified, but valid, values&period;


[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;class TARGET&lowbar;TYPE&gt;
static
void
xref:BloombergLP/bslalg/ArrayPrimitives/insert-0ab.adoc[insert](
    TARGET&lowbar;TYPE* toBegin,
    TARGET&lowbar;TYPE* toEnd,
    TARGET&lowbar;TYPE const& value,
    xref:BloombergLP/bslalg/ArrayPrimitives/size_type.adoc[size&lowbar;type] numElements,
    xref:BloombergLP/bslma/Allocator.adoc[bslma::Allocator]* allocator);
----

[.small]#xref:BloombergLP/bslalg/ArrayPrimitives/insert-0ab.adoc[_» more&period;&period;&period;_]#

Same as the preceding `insert` overload, taking pointer iterators&period;


[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;
    class ALLOCATOR,
    class SOURCE&lowbar;TYPE&gt;
static
void
xref:BloombergLP/bslalg/ArrayPrimitives/insert-0e.adoc[insert](
    bsl::allocator&lowbar;traits&lt;ALLOCATOR&gt;::pointer toBegin,
    bsl::allocator&lowbar;traits&lt;ALLOCATOR&gt;::pointer toEnd,
    SOURCE&lowbar;TYPE* fromBegin,
    SOURCE&lowbar;TYPE* fromEnd,
    xref:BloombergLP/bslalg/ArrayPrimitives/size_type.adoc[size&lowbar;type] numElements,
    ALLOCATOR allocator);
----

[.small]#xref:BloombergLP/bslalg/ArrayPrimitives/insert-0e.adoc[_» more&period;&period;&period;_]#

Same as the preceding overload, taking pointer iterators&period;


[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;
    class TARGET&lowbar;TYPE,
    class SOURCE&lowbar;TYPE&gt;
static
void
xref:BloombergLP/bslalg/ArrayPrimitives/insert-0c.adoc[insert](
    TARGET&lowbar;TYPE* toBegin,
    TARGET&lowbar;TYPE* toEnd,
    SOURCE&lowbar;TYPE* fromBegin,
    SOURCE&lowbar;TYPE* fromEnd,
    xref:BloombergLP/bslalg/ArrayPrimitives/size_type.adoc[size&lowbar;type] numElements,
    xref:BloombergLP/bslma/Allocator.adoc[bslma::Allocator]* allocator);
----

[.small]#xref:BloombergLP/bslalg/ArrayPrimitives/insert-0c.adoc[_» more&period;&period;&period;_]#

TBD&colon; improve comment Insert the specified `numElements` from the range starting at the specified `fromBegin` of (template parameter) `FWD&lowbar;ITER` type (or template parameter `SOURCE&lowbar;TYPE &ast;`) and ending immediately before the specified `fromEnd` sentinels or iterators of (template parameter) `SENTINEL` type (or template parameter `SOURCE&lowbar;TYPE &ast;`), into the array of elements of type given by the `allocator&lowbar;traits` class template for (template parameter) `ALLOCATOR`, starting at the specified `toBegin` address, shifting forward the elements in the array by `numElements` positions&period; The behavior is undefined unless the destination array contains `numElements` uninitialized elements after `toEnd`, `numElements` is the distance between `fromBegin` and `fromEnd`, and the input array and the destination array do not overlap&period; If a copy constructor or assignment operator throws an exception, then any elements created after `toEnd` are destroyed and the elements in the range `&lsqb; toBegin, toEnd )&rsqb;` will have valid but unspecified values&period;


[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;
    class ALLOCATOR,
    class FWD&lowbar;ITER,
    class SENTINEL&gt;
static
void
xref:BloombergLP/bslalg/ArrayPrimitives/insert-0f.adoc[insert](
    bsl::allocator&lowbar;traits&lt;ALLOCATOR&gt;::pointer toBegin,
    bsl::allocator&lowbar;traits&lt;ALLOCATOR&gt;::pointer toEnd,
    FWD&lowbar;ITER fromBegin,
    SENTINEL fromEnd,
    xref:BloombergLP/bslalg/ArrayPrimitives/size_type.adoc[size&lowbar;type] numElements,
    ALLOCATOR allocator);
----

[.small]#xref:BloombergLP/bslalg/ArrayPrimitives/insert-0f.adoc[_» more&period;&period;&period;_]#

Insert, into the array at the specified `toBegin` location, the specified `numElements` from the range starting at the specified `fromBegin` iterators of the (template parameter) `FWD&lowbar;ITER` type (or the (template parameter) `SOURCE&lowbar;TYPE &ast;`) and ending immediately before the specified `fromEnd` sentinels or iterators of the (template parameter) `SENTINEL` type (or the (template parameter) `SOURCE&lowbar;TYPE &ast;`), into the array of elements of the parameterized `TARGET&lowbar;TYPE` starting at the specified `toBegin` address and ending immediately before the specified `toEnd` address, shifting the elements in the array by `numElements` positions towards larger addresses&period; The behavior is undefined unless the destination array contains `numElements` uninitialized elements after `toEnd`, `numElements` is the distance between `fromBegin` and `fromEnd`, and the input array and the destination array do not overlap&period; If a copy constructor or assignment operator for `TARGET&lowbar;TYPE` throws an exception, then any elements created after `toEnd` are destroyed and the elements in the range `&lsqb; toBegin, toEnd )&rsqb;` will have unspecified, but valid, values&period;


[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;
    class TARGET&lowbar;TYPE,
    class FWD&lowbar;ITER,
    class SENTINEL&gt;
static
void
xref:BloombergLP/bslalg/ArrayPrimitives/insert-06.adoc[insert](
    TARGET&lowbar;TYPE* toBegin,
    TARGET&lowbar;TYPE* toEnd,
    FWD&lowbar;ITER fromBegin,
    SENTINEL fromEnd,
    xref:BloombergLP/bslalg/ArrayPrimitives/size_type.adoc[size&lowbar;type] numElements,
    xref:BloombergLP/bslma/Allocator.adoc[bslma::Allocator]* allocator);
----

[.small]#xref:BloombergLP/bslalg/ArrayPrimitives/insert-06.adoc[_» more&period;&period;&period;_]#


[.small]#Created with https://www.mrdocs.com[MrDocs]#
