Namespaces
Variants
Actions

std::basic_string<CharT,Traits,Allocator>::assign

From cppreference.com
< cpp‎ | string‎ | basic string
 
C++
 
Strings library
 
std::basic_string
 
basic_string& assign( const basic_string& str );
 (1) (constexpr since C++20)
basic_string& assign( basic_string&& str ) noexcept(/* see below */);
 (2) (since C++11)
(constexpr since C++20)
basic_string& assign( size_type count, CharT ch );
 (3) (constexpr since C++20)
basic_string& assign( const CharT* s, size_type count );
 (4) (constexpr since C++20)
basic_string& assign( const CharT* s );
 (5) (constexpr since C++20)
template< class SV >
basic_string& assign( const SV& t );
 (6) (since C++17)
(constexpr since C++20)
template< class SV >

basic_string& assign( const SV& t,

                      size_type pos, size_type count = npos);
 (7) (since C++17)
(constexpr since C++20)
(8)
basic_string& assign( const basic_string& str,
                      size_type pos, size_type count );
 (until C++14)
basic_string& assign( const basic_string& str,
                      size_type pos, size_type count = npos);
 (since C++14)
(constexpr since C++20)
template< class InputIt >
basic_string& assign( InputIt first, InputIt last );
 (9) (constexpr since C++20)
basic_string& assign( std::initializer_list<CharT> ilist );
 (10) (since C++11)
(constexpr since C++20)

Replaces the contents of the string.

1) Equivalent to return *this = str;.
2) Equivalent to return *this = std::move(str);.
3) Replaces the contents with count copies of character ch.
Equivalent to clear(); resize(n, c); return *this;.
4) Replaces the contents with copies of the characters in the range [s, s + count).
If [s, s + count) is not a valid range, the behavior is undefined.
5) Equivalent to return assign(s, Traits::length(s));.
6,7) Replaces the contents with characters in a string view sv constructed from t.
  • If only t is provided, replaces the contents with all characters in sv.
  • If pos is also provided:
    • If count is npos, replaces the contents with all characters in sv starting from pos.
    • Otherwise, replaces the contents with the std::min(count, sv.size() - pos) characters in sv starting from pos.
These overloads participate in overload resolution only if all following conditions are satisfied:
6) Equivalent to std::basic_string_view<CharT, Traits> sv = t;
return assign(sv.data(), sv.size());.
7) Equivalent to std::basic_string_view<CharT, Traits> sv = t;
return assign(sv.substr(pos, count));.
8) Replaces the contents with characters in str.
  • If count is npos, replaces the contents with all characters in str starting from pos.
  • Otherwise, replaces the contents with the std::min(count, str.size() - pos) characters in str starting from pos.
Equivalent to return assign(std::basic_string_view<CharT, Traits>
                  (str).substr(pos, count));.
 (since C++20)
9) Equivalent to return assign(basic_string(first, last, get_allocator()));.

This overload participates in overload resolution only if InputIt satisfies the requirements of LegacyInputIterator.

(since C++11)
10) Equivalent to return assign(ilist.begin(), ilist.size());.

Contents

[edit] Parameters

str - string to be used as source to initialize the characters with
count - size of the resulting string
ch - value to initialize characters of the string with
s - pointer to a character string to use as source to initialize the string with
t - object (convertible to std::basic_string_view) to initialize the characters of the string with
pos - index of the first character to take
first, last - range to copy the characters from
ilist - std::initializer_list to initialize the characters of the string with

[edit] Return value

*this

[edit] Exceptions

2)
noexcept specification:  
noexcept(std::allocator_traits<Allocator>::

             propagate_on_container_move_assignment::value ||

         std::allocator_traits<Allocator>::is_always_equal::value)

If the operation would cause size() to exceed max_size(), throws std::length_error.

7) If pos > sv.size() is true, throws std::out_of_range.
8) If pos > str.size() is true, throws std::out_of_range.

If an exception is thrown for any reason, this function has no effect (strong exception safety guarantee).

[edit] Example

Run this code
#include <iostream>
#include <iterator>
#include <string>
 
int main()
{
    std::string s;
    // assign(size_type count, CharT ch)
    s.assign(4, '=');
    std::cout << s << '\n'; // "===="
 
    std::string const c("Exemplary");
    // assign(const basic_string& str)
    s.assign(c);
    std::cout << c << " == " << s << '\n'; // "Exemplary == Exemplary"
 
    // assign(const basic_string& str, size_type pos, size_type count)
    s.assign(c, 0, c.length() - 1);
    std::cout << s << '\n'; // "Exemplar";
 
    // assign(basic_string&& str)
    s.assign(