[#bsl-basic_string-0faf-insert-060]
= xref:bsl.adoc[bsl]::xref:bsl/basic_string-0faf.adoc[basic_string]::insert
:relfileprefix: ../../
:mrdocs:

Insert characters into this string.

== Synopsis

Declared in `<bslstl_string.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
xref:bsl/basic_string-0faf/iterator.adoc[iterator]
insert(
    xref:bsl/basic_string-0faf/const_iterator.adoc[const_iterator] position,
    std::initializer_list<CHAR_TYPE> values);
----

== Description

Insert at the specified `position` in this string each `CHAR_TYPE` object in the specified `values` initializer list, and return an iterator to the first newly‐inserted character. If an exception is thrown (other than by the copy constructor, move constructor, assignment operator, and move assignment operator of `CHAR_TYPE`), `*this` is unaffected. The behavior is undefined unless `position` is an iterator in the range `[begin() .. end()]` (both endpoints included).

== Return Value

iterator referring to the first inserted character

== Parameters

[cols="1,4"]
|===
| Name| Description
| *position*
| starting index
| *values*
| initializer list of characters
|===


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