std::string insert() method
- since C++20
- since C++17
- since C++14
- since C++11
- until C++11
// (1) Non const version only
constexpr basic_string& insert( size_type index, size_type count, CharT ch );
// (2) Non const version only
constexpr basic_string& insert( size_type index, const CharT* s );
// (3) Non const version only
constexpr basic_string& insert( size_type index, const CharT* s, size_type count );
// (4) Non const version only
constexpr basic_string& insert( size_type index, const basic_string& str );
// (5) Non const version only
constexpr basic_string& insert( size_type index, const basic_string& str,
size_type index_str, size_type count = npos );
// (6) Non const version only
constexpr iterator insert( const_iterator pos, CharT ch );
// (7) Non const version only
constexpr iterator insert( const_iterator pos, size_type count, CharT ch );
// (8) Non const version only
template< class InputIt >
constexpr iterator insert( const_iterator pos, InputIt first, InputIt last );
// (9) Non const version only
constexpr iterator insert( const_iterator pos, std::initializer_list<CharT> ilist );
// (10) Non const version only
template< class StringViewLike >
constexpr basic_string& insert( size_type pos, const StringViewLike& t );
// (11) Non const version only
template< class StringViewLike >
constexpr basic_string& insert( size_type index, const StringViewLike& t,
size_type index_str, size_type count = npos );
// (1) Non const version only
basic_string& insert( size_type index, size_type count, CharT ch );
// (2) Non const version only
basic_string& insert( size_type index, const CharT* s );
// (3) Non const version only
basic_string& insert( size_type index, const CharT* s, size_type count );
// (4) Non const version only
basic_string& insert( size_type index, const basic_string& str );
// (5) Non const version only
basic_string& insert( size_type index, const basic_string& str,
size_type index_str, size_type count = npos );
// (6) Non const version only
iterator insert( const_iterator pos, CharT ch );
// (7) Non const version only
iterator insert( const_iterator pos, size_type count, CharT ch );
// (8) Non const version only
template< class InputIt >
iterator insert( const_iterator pos, InputIt first, InputIt last );
// (9) Non const version only
iterator insert( const_iterator pos, std::initializer_list<CharT> ilist );
// (10) Non const version only
template< class StringViewLike >
basic_string& insert( size_type pos, const StringViewLike& t );
// (11) Non const version only
template< class StringViewLike >
basic_string& insert( size_type index, const StringViewLike& t,
size_type index_str, size_type count = npos );
// (1) Non const version only
basic_string& insert( size_type index, size_type count, CharT ch );
// (2) Non const version only
basic_string& insert( size_type index, const CharT* s );
// (3) Non const version only
basic_string& insert( size_type index, const CharT* s, size_type count );
// (4) Non const version only
basic_string& insert( size_type index, const basic_string& str );
// (5) Non const version only
basic_string& insert( size_type index, const basic_string& str,
size_type index_str, size_type count = npos );
// (6) Non const version only
iterator insert( const_iterator pos, CharT ch );
// (7) Non const version only
iterator insert( const_iterator pos, size_type count, CharT ch );
// (8) Non const version only
template< class InputIt >
iterator insert( const_iterator pos, InputIt first, InputIt last );
// (9) Non const version only
iterator insert( const_iterator pos, std::initializer_list<CharT> ilist );
// (1) Non const version only
basic_string& insert( size_type index, size_type count, CharT ch );
// (2) Non const version only
basic_string& insert( size_type index, const CharT* s );
// (3) Non const version only
basic_string& insert( size_type index, const CharT* s, size_type count );
// (4) Non const version only
basic_string& insert( size_type index, const basic_string& str );
// (5) Non const version only
basic_string& insert( size_type index, const basic_string& str,
size_type index_str, size_type count );
// (6) Non const version only
iterator insert( const_iterator pos, CharT ch );
// (7) Non const version only
iterator insert( const_iterator pos, size_type count, CharT ch );
// (8) Non const version only
template< class InputIt >
iterator insert( const_iterator pos, InputIt first, InputIt last );
// (9) Non const version only
iterator insert( const_iterator pos, std::initializer_list<CharT> ilist );
// (1) Non const version only
basic_string& insert( size_type index, size_type count, CharT ch );
// (2) Non const version only
basic_string& insert( size_type index, const CharT* s );
// (3) Non const version only
basic_string& insert( size_type index, const CharT* s, size_type count );
// (4) Non const version only
basic_string& insert( size_type index, const basic_string& str );
// (5) Non const version only
basic_string& insert( size_type index, const basic_string& str,
size_type index_str, size_type count );
// (6) Non const version only
iterator insert( iterator pos, CharT ch );
// (7) Non const version only
void insert( iterator pos, size_type count, CharT ch );
// (8) Non const version only
template< class InputIt >
void insert( iterator pos, InputIt first, InputIt last );
// (9) Non const version only
iterator insert( const_iterator pos, std::initializer_list<CharT> ilist );
Inserts characters into the string.
-
(1) Inserts
count
copies of characterch
at the positionindex
. -
(2) Inserts null-terminated character string pointed to by
s
at the position index.
The length of the string is determined by the first null character usingTraits::length(s)
. -
(3) Inserts the characters in the range [ s, s + count ) at the position
index
.
The range can contain null characters. -
(4) Inserts string
str
at the positionindex
. -
(5) Inserts a string, obtained by
str.substr(index_str, count)
at the positionindex
. -
(6) Inserts character
ch
before the character pointed bypos
. -
(7) Inserts
count
copies of characterch
before the element (if any) pointed bypos
. -
(8) Inserts characters from the range [ first, last ) before the element (if any) pointed by
pos
.
This overload does not participate in overload resolution ifInputIt
does not satisfyLegacyInputIterator
. (since C++11) -
(9) Inserts elements from initializer list
ilist
before the element (if any) pointed bypos
. -
(10) Implicitly converts
t
to a string viewsv
as if bystd::basic_string_view<CharT, Traits> sv = t;
, then inserts the elements fromsv
before the element (if any) pointed bypos
, as if byinsert(pos, sv.data(), sv.size())
.Overload ResolutionThis overload participates in overload resolution only if
std::is_convertible_v<const StringViewLike&, std::basic_string_view<CharT, Traits>>
istrue
andstd::is_convertible_v<const StringViewLike&, const CharT*>
isfalse
. -
(11) Implicitly converts
t
to a string viewsv
as if bystd::basic_string_view<CharT, Traits> sv = t;
, then inserts, before the element (if any) pointed bypos
, the characters from the subview [ index_str, index_str + count ) ofsv
.
If the requested subview lasts past the end ofsv
, or ifcount == npos
, the resulting subview is [ index_str, sv.size() ).
Ifindex_str > sv.size()
, or ifindex > size()
,std::out_of_range
is thrown.Overload ResolutionThis overload participates in overload resolution only if
std::is_convertible_v<const StringViewLike&, std::basic_string_view<CharT, Traits>>
istrue
andstd::is_convertible_v<const StringViewLike&, const CharT*>
isfalse
.
Parameters
index
- position at which the content will be insertedpos
- iterator before which the characters will be insertedch
- character to insertcount
- number of characters to inserts
- pointer to the character string to insertstr
- string to insertfirst
,last
- range defining characters to insertindex_str
- position of the first character in the stringstr
to insertilist
-std::initializer_list
to insert the characters fromt
- object (convertible tostd::basic_string_view
) to insert the characters from
Type requirements
- (8) -
T
(container's element type) must meet the requirements ofLegacyInputIterator
.
Return value
- (1-5, 10-11)
*this
- (6-9)
An iterator which refers to the copy of the first inserted character.
pos
if no characters were inserted (count == 0
orfirst == last
orilist.size() == 0
).
Complexity
This section requires improvement. You can help by editing this doc page.
Exceptions
- (1-4, 10) Throws
std::out_of_range
ifindex > size()
. - (5) Throws
std::out_of_range
ifindex > size()
or ifindex_str > str.size()
. - (11) Throws
std::out_of_range
ifindex > size()
or ifindex_str > sv.size()
.
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 and may throw any exceptions thrown by Allocator::allocate()
.
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 index_str, 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);
}
Hover to see the original license.