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

出自cppreference.com
 
C++
 
字符串庫
 
std::basic_string
 
basic_string& assign( const basic_string& str );
(1) (C++20 起為 constexpr) 
basic_string& assign( basic_string&& str ) noexcept(/* 见下文 */);
(2) (C++11 起)
(C++20 起為 constexpr)		 
basic_string& assign( size_type count, CharT ch );
(3) (C++20 起為 constexpr) 
basic_string& assign( const CharT* s, size_type count );
(4) (C++20 起為 constexpr) 
basic_string& assign( const CharT* s );
(5) (C++20 起為 constexpr) 
template< class SV >
basic_string& assign( const SV& t );
(6) (C++17 起)
(C++20 起為 constexpr)		 
template< class SV >
basic_string& assign( const SV& t,
                      size_type pos, size_type count = npos);
(7) (C++17 起)
(C++20 起為 constexpr)
(8) 
basic_string& assign( const basic_string& str,
                      size_type pos, size_type count );
(C++14 前) 
basic_string& assign( const basic_string& str,
                      size_type pos, size_type count = npos);
(C++14 起)
(C++20 起為 constexpr)		 
template< class InputIt >
basic_string& assign( InputIt first, InputIt last );
(9) (C++20 起為 constexpr) 
basic_string& assign( std::initializer_list<CharT> ilist );
(10) (C++11 起)
(C++20 起為 constexpr)

替換字符串的內容。

1) 等價於 return *this = str;。
2) 等價於 return *this = std::move(str);。
3) 以字符 ch 的 count 個副本替換字符串的內容。
等價於 clear(); resize(n, c); return *this;。
4) 以範圍 [s, s + count) 中的字符的副本替換字符串的內容。
如果 [s, s + count) 不是有效範圍，那麼行為未定義。
5) 等價於 return assign(s, Traits::length(s));。
6,7) 以從 t 構造的字符串視圖 sv 中的字符替換字符串的內容。
  • 如果只提供了 t，那麼就會以 sv 中的所有字符進行替換。
  • 如果也提供了 pos：
    • 如果 count 是 npos，那麼就會以 sv 中從 pos 處開始的所有字符進行替換。
    • 否則會以 sv 中從 pos 處開始的 std::min(count, sv.size() - pos) 個字符進行替換。
這些重載只有在滿足以下所有條件時才會參與重載決議：
  • std::is_convertible_v<const SV&, std::basic_string_view<CharT, Traits>> 是 true。
  • std::is_convertible_v<const SV&, const CharT*> 是 false。
6) 等價於 std::basic_string_view<CharT, Traits> sv = t;
return assign(sv.data(), sv.size());。
7) 等價於 std::basic_string_view<CharT, Traits> sv = t;
return assign(sv.substr(pos, count));。
8) 以 str 中的字符替換字符串的內容。
  • 如果 count 是 npos，那麼就會以 str 中從 pos 處開始的所有字符進行替換。
  • 否則會以 str 中從 pos 處開始的 std::min(count, str.size() - pos) 個字符進行替換。
等價於 return assign(std::basic_string_view<CharT, Traits>
(str).substr(pos, count));。
(C++20 起)
9) 等價於 return assign(basic_string(first, last, get_allocator()));。

此重載只有在 InputIt 滿足老式輸入迭代器 (LegacyInputIterator) 的要求時才會參與重載決議。

(C++11 起)
10) 等價於 return assign(ilist.begin(), ilist.size());。

參數

str - 用作源以初始化字符的字符串
count - 產生的字符串大小
ch - 用以初始化字符串的字符的值
s - 指向用作源初始化字符串字符串的指針
t - 用以初始化字符串字符的對象（可轉換到 std::basic_string_view）
pos - 要取的首字符下標
first, last - 複製字符來源的範圍
ilist - 用以初始化字符串字符的 std::initializer_list

返回值

*this

異常

2)
noexcept 說明：  
noexcept(std::allocator_traits<Allocator>:: propagate_on_container_move_assignment::value || std::allocator_traits<Allocator>::is_always_equal::value)

如果操作會導致 size() 超出 max_size()，那麼就會拋出 std::length_error。

7) 如果 pos > sv.size() 是 true，那麼就會拋出 std::out_of_range。
8) 如果 pos > str.size() 是 true，那麼就會拋出 std::out_of_range。

如果因為任何原因拋出了異常，那麼此函數無效果（強異常安全保證）。

示例

運行此代碼
#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(std::string("C++ by ") + "example");
    std::cout << s << '\n'; // "C++ by example"
    
    // assign(const CharT* s, size_type count)
    s.assign("C-style string", 7);
    std::cout << s << '\n'; // "C-style"
    
    // assign(const CharT* s)
    s.assign("C-style\0string");
    std::cout << s << '\n'; // "C-style"
    
    char mutable_c_str[] = "C-style string";
    // assign(InputIt first, InputIt last)
    s.assign(std::begin(mutable_c_str), std::end(mutable_c_str) - 1);
    std::cout << s << '\n'; // "C-style string"
    
    // assign(std::initializer_list<CharT> ilist)
    s.assign({'C', '-', 's', 't', 'y', 'l', 'e'});
    std::cout << s << '\n'; // "C-style"
}

輸出： 

====
Exemplary == Exemplary
Exemplar
C++ by example
C-style
C-style
C-style string
C-style

缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告 應用於 出版時的行為 正確行為
LWG 847 C++98 沒有異常安全保證 添加強異常安全保證
LWG 2063 C++11 非正式註釋說可以通過交換實現重載 (2) 更正為要求移動賦值
LWG 2250 C++98 pos > str.size() 是 true 時重載 (8) 的行為未定義 此時始終會拋出異常
LWG 2579 C++98 重載 (1) 與複製賦值運算符的行為不同 它們的行為相同
LWG 2946 C++17 重載 (6) 在某些情況下會導致歧義 通過使之為模板避免

參閱

(C++23)
 賦值範圍內的字符到字符串
(公開成員函數) [編輯]
構造 basic_string
(公開成員函數) [編輯]
為字符串賦值
(公開成員函數) [編輯]