std::basic_string<CharT,Traits,Allocator>:: insert
basic_string
&
insert
(
size_type index, size_type count, CharT ch
)
;
|
(1) | (constexpr since C++20) |
basic_string
&
insert
(
size_type index,
const
CharT
*
s
)
;
|
(2) | (constexpr since C++20) |
basic_string
&
insert
(
size_type index,
const
CharT
*
s, size_type count
)
;
|
(3) | (constexpr since C++20) |
basic_string
&
insert
(
size_type index,
const
basic_string
&
str
)
;
|
(4) | (constexpr since C++20) |
(5) | ||
basic_string
&
insert
(
size_type index,
const
basic_string
&
str,
size_type s_index, size_type count ) ; |
(until C++14) | |
basic_string
&
insert
(
size_type index,
const
basic_string
&
str,
size_type s_index, size_type count = npos ) ; |
(since C++14)
(constexpr since C++20) |
|
(6) | ||
iterator insert
(
iterator pos, CharT ch
)
;
|
(until C++11) | |
iterator insert
(
const_iterator pos, CharT ch
)
;
|
(since C++11)
(constexpr since C++20) |
|
(7) | ||
void
insert
(
iterator pos, size_type count, CharT ch
)
;
|
(until C++11) | |
iterator insert
(
const_iterator pos, size_type count, CharT ch
)
;
|
(since C++11)
(constexpr since C++20) |
|
(8) | ||
template
<
class
InputIt
>
void insert ( iterator pos, InputIt first, InputIt last ) ; |
(until C++11) | |
template
<
class
InputIt
>
iterator insert ( const_iterator pos, InputIt first, InputIt last ) ; |
(since C++11)
(constexpr since C++20) |
|
iterator insert
(
const_iterator pos,
std::
initializer_list
<
CharT
>
ilist
)
;
|
(9) |
(since C++11)
(constexpr since C++20) |
template
<
class
StringViewLike
>
basic_string & insert ( size_type index, const StringViewLike & t ) ; |
(10) |
(since C++17)
(constexpr since C++20) |
template
<
class
StringViewLike
>
basic_string
&
insert
(
size_type index,
const
StringViewLike
&
t,
|
(11) |
(since C++17)
(constexpr since C++20) |
Inserts characters into the string.
[
s
,
s
+
count
)
at the position
index
. The range can contain null characters.
[
first
,
last
)
before the element (if any) pointed by
pos
, as if by
insert
(
pos
-
begin
(
)
, basic_string
(
first, last, get_allocator
(
)
)
)
.
This overload does not participate in overload resolution if
|
(since C++11) |
std:: basic_string_view < CharT, Traits >> is true and std:: is_convertible_v < const StringViewLike & , const CharT * > is false .
[
t_index
,
t_index
+
count
)
of
sv
.
-
If the requested subview lasts past the end of
sv
, or if
count
==
npos
, the resulting subview is
[
t_index,
sv. size ( ))
. - If t_index > sv. size ( ) , or if index > size ( ) , std::out_of_range is thrown.
std:: basic_string_view < CharT, Traits >> is true and std:: is_convertible_v < const StringViewLike & , const CharT * > is false .
If pos is not a valid iterator on * this , the behavior is undefined.
Parameters
index | - | position at which the content will be inserted |
pos | - | iterator before which the characters will be inserted |
ch | - | character to insert |
count | - | number of characters to insert |
s | - | pointer to the character string to insert |
str | - | string to insert |
first, last | - | range defining characters to insert |
s_index | - | position of the first character in str to insert |
ilist | - | std::initializer_list to insert the characters from |
t | - | object (convertible to std::basic_string_view ) to insert the characters from |
t_index | - | position of the first character in t to insert |
Type requirements | ||
-
InputIt
must meet the requirements of
LegacyInputIterator
.
|
Return value
Exceptions
In all cases, throws std::length_error if size ( ) + ins_count > max_size ( ) where ins_count is the number of characters that will be inserted.
In all cases, if std:: allocator_traits < Allocator > :: allocate throws an exception, it is rethrown. |
(since C++20) |
If an exception is thrown for any reason, this function has no effect ( strong exception safety guarantee ).
Example
#include <cassert> #include <iterator> #include <string> using namespace std::string_literals; int main() { std::string s = "xmplr"; // insert(size_type index, size_type count, char ch) s.insert(0, 1, 'E'); assert("Exmplr" == s); // insert(size_type index, const char* s) s.insert(2, "e"); assert("Exemplr" == s); // insert(size_type index, string const& str) s.insert(6, "a"s); assert("Exemplar" == s); // insert(size_type index, string const& str, // size_type s_index, size_type count) s.insert(8, " is an example string."s, 0, 14); assert("Exemplar is an example" == s); // insert(const_iterator pos, char ch) s.insert(s.cbegin() + s.find_first_of('n') + 1, ':'); assert("Exemplar is an: example" == s); // insert(const_iterator pos, size_type count, char ch) s.insert(s.cbegin() + s.find_first_of(':') + 1, 2, '='); assert("Exemplar is an:== example" == s); // insert(const_iterator pos, InputIt first, InputIt last) { std::string seq = " string"; s.insert(s.begin() + s.find_last_of('e') + 1, std::begin(seq), std::end(seq)); assert("Exemplar is an:== example string" == s); } // insert(const_iterator pos, std::initializer_list<char>) s.insert(s.cbegin() + s.find_first_of('g') + 1, {'.'}); assert("Exemplar is an:== example string." == s); }
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
LWG 7 | C++98 | overload (8) referred to a non-existing overload | refers to overload (4) correctly |
LWG 847 | C++98 | there was no exception safety guarantee | added strong exception safety guarantee |
LWG 2946 | C++17 | overload (10) caused ambiguity in some cases | avoided by making it a template |
See also
(C++23)
|
inserts a range of characters
(public member function) |
appends characters to the end
(public member function) |
|
appends a character to the end
(public member function) |