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

 

C++

Поддержка компилятором

Автономные и размещённые реализации

Язык

Стандартная библиотека

Заголовки стандартной библиотеки

Требования к именованию

Макросы тестирования функциональности (C++20)

Поддержка языка

Библиотека концептов (C++20)

Библиотека метапрограммирования (C++11)

Библиотека диагностики

Библиотека общих утилит

Библиотека строк

Библиотека контейнеров

Библиотека итераторов

Библиотека диапазонов (C++20)

Библиотека алгоритмов

Библиотека численных данных

Библиотека ввода/вывода

Библиотека локализаций

Регулярные выражения (C++11)

Атомарные операции (C++11)

Библиотека поддержки конкуренции (C++11)

Библиотека файловой системы (C++17)

Технические спецификации

Указатель символов

Внешние библиотеки

 

Строки

Строки с завершающим нулём

Однобайтовые строки

Многобайтовые строки

Широкие строки

Классы

basic_string

basic_string_view (C++17)

char_traits

 

std::basic_string

Функции-элементы basic_string::basic_string basic_string::~basic_string basic_string::operator= basic_string::assign basic_string::assign_range (C++23) basic_string::get_allocator Доступ к элементам basic_string::at basic_string::operator[] basic_string::front (DR*) basic_string::back (DR*) basic_string::data basic_string::c_str basic_string::operator  basic_string_view (C++17) Итераторы basic_string::beginbasic_string::cbegin (DR*) basic_string::endbasic_string::cend (DR*) basic_string::rbeginbasic_string::crbegin (DR*) basic_string::rendbasic_string::crend (DR*) Ёмкость basic_string::empty basic_string::sizebasic_string::length basic_string::max_size basic_string::reserve basic_string::capacity basic_string::shrink_to_fit (DR*) Операции basic_string::clear basic_string::insert basic_string::insert_range (C++23) basic_string::erase basic_string::push_back basic_string::pop_back (DR*) basic_string::append basic_string::append_range (C++23) basic_string::operator+= basic_string::compare basic_string::replace basic_string::replace_with_range (C++23) basic_string::substr basic_string::copy basic_string::resize basic_string::resize_and_overwrite (C++23)   basic_string::swap

Поиск basic_string::starts_with (C++20)   basic_string::ends_with (C++20) basic_string::contains (C++23) basic_string::find basic_string::rfind basic_string::find_first_of basic_string::find_first_not_of basic_string::find_last_of basic_string::find_last_not_of Константы basic_string::npos Правила вывода (C++17) Функции, не являющиеся элементами operator+ swap(std::basic_string) operator""s (C++14) erase(std::basic_string)erase_if(std::basic_string) (C++20)(C++20) Ввод/Вывод operator<<operator>> getline Сравнение operator==operator!=operator<operator>operator<=operator>=operator<=> (до C++20)(до C++20)(до C++20)(до C++20)(до C++20)(C++20) Числовые преобразования stoistolstoll (C++11)(C++11)(C++11) stoulstoull (C++11)(C++11) stofstodstold (C++11)(C++11)(C++11) to_string (C++11) to_wstring (C++11) Вспомогательные классы hash<std::string>hash<std::wstring>hash<std::u32string>hash<std::u16string>hash<std::u8string> (C++11)  (C++11)(C++11)(C++11)(C++20) hash<std::pmr::string>hash<std::pmr::wstring>hash<std::pmr::u32string>hash<std::pmr::u16string>hash<std::pmr::u8string> (C++17)(C++17)(C++17)(C++17)(C++20)

 

<tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody> <tbody class="t-dcl-rev t-dcl-rev-num "> </tbody><tbody> </tbody>

(1)

basic_string(); explicit basic_string( const Allocator& alloc );

(до C++17)

basic_string() noexcept(noexcept( Allocator() )) : basic_string( Allocator() ) {} explicit basic_string( const Allocator& alloc ) noexcept;

(начиная с C++17) (до C++20)

constexpr basic_string() noexcept(noexcept( Allocator() )) : basic_string( Allocator() ) {} constexpr explicit basic_string( const Allocator& alloc ) noexcept;

(начиная с C++20)

(2)

basic_string( size_type count, CharT ch, const Allocator& alloc = Allocator() );

(до C++20)

constexpr basic_string( size_type count, CharT ch, const Allocator& alloc = Allocator() );

(начиная с C++20)

(3)

basic_string( const basic_string& other, size_type pos, const Allocator& alloc = Allocator() );

(до C++20)

constexpr basic_string( const basic_string& other, size_type pos, const Allocator& alloc = Allocator() );

(начиная с C++20)

constexpr basic_string( basic_string&& other, size_type pos, const Allocator& alloc = Allocator() );

(3)

(начиная с C++23)

(3)

basic_string( const basic_string& other, size_type pos, size_type count, const Allocator& alloc = Allocator() );

(до C++20)

constexpr basic_string( const basic_string& other, size_type pos, size_type count, const Allocator& alloc = Allocator() );

(начиная с C++20)

constexpr basic_string( basic_string&& other, size_type pos, size_type count, const Allocator& alloc = Allocator() );

(3)

(начиная с C++23)

(4)

basic_string( const CharT* s, size_type count, const Allocator& alloc = Allocator() );

(до C++20)

constexpr basic_string( const CharT* s, size_type count, const Allocator& alloc = Allocator() );

(начиная с C++20)

(5)

basic_string( const CharT* s, const Allocator& alloc = Allocator() );

(до C++20)

constexpr basic_string( const CharT* s, const Allocator& alloc = Allocator() );

(начиная с C++20)

(6)

template< class InputIt > basic_string( InputIt first, InputIt last, const Allocator& alloc = Allocator() );

(до C++20)

template< class InputIt > constexpr basic_string( InputIt first, InputIt last, const Allocator& alloc = Allocator() );

(начиная с C++20)

(7)

basic_string( const basic_string& other );

(до C++20)

constexpr basic_string( const basic_string& other );

(начиная с C++20)

(7)

basic_string( const basic_string& other, const Allocator& alloc );

(начиная с C++11) (до C++20)

constexpr basic_string( const basic_string& other, const Allocator& alloc );

(начиная с C++20)

(8)

basic_string( basic_string&& other ) noexcept;

(начиная с C++11) (до C++20)

constexpr basic_string( basic_string&& other ) noexcept;

(начиная с C++20)

(8)

basic_string( basic_string&& other, const Allocator& alloc );

(начиная с C++11) (до C++20)

constexpr basic_string( basic_string&& other, const Allocator& alloc );

(начиная с C++20)

(9)

basic_string( std::initializer_list<CharT> ilist, const Allocator& alloc = Allocator() );

(начиная с C++11) (до C++20)

constexpr basic_string( std::initializer_list<CharT> ilist, const Allocator& alloc = Allocator() );

(начиная с C++20)

(10)

template< class StringViewLike > explicit basic_string( const StringViewLike& t, const Allocator& alloc = Allocator() );

(начиная с C++17) (до C++20)

template< class StringViewLike > constexpr explicit basic_string( const StringViewLike& t, const Allocator& alloc = Allocator() );

(начиная с C++20)

(11)

template< class StringViewLike > basic_string( const StringViewLike& t, size_type pos, size_type n, const Allocator& alloc = Allocator() );

(начиная с C++17) (до C++20)

template< class StringViewLike > constexpr basic_string( const StringViewLike& t, size_type pos, size_type n, const Allocator& alloc = Allocator() );

(начиная с C++20)

basic_string( std::nullptr_t ) = delete;

(12)

(начиная с C++23)

template< container-compatible-range<CharT> R > constexpr basic_string( std::from_range_t, R&& rg, const Allocator& = Allocator());

(13)

(начиная с C++23)

Создаёт новую строку из различных источников данных и, при необходимости, с использованием предоставленного пользователем распределителя alloc.

1) Конструктор по умолчанию. Создаёт пустую строку (нулевой размер и неуказанная ёмкость). Если аллокатор не указан, аллокатор получается из экземпляра, созданного по умолчанию.

2) Создаёт строку из count копий символа ch. Этот конструктор не используется для вывода аргументов шаблонного класса, если выводимый тип Allocator не может считаться аллокатором. (начиная с C++17)

3) Создаёт строку из подстроки [pos, pos + count) из other. Если count == npos, если count не указано или если запрошенная подстрока выходит за конец строки, результирующая подстрока будет [pos, other.size()). Если other является ссылкой rvalue, она остаётся в допустимом, но неопределённом состоянии. (начиная с C++23)

4) Создаёт строку из первых count символов символьной строки, на которую указывает s. s может содержать нулевые символы. Длина строки равна count. Поведение не определено, если [s, s + count) не является допустимым диапазоном.

5) Создаёт строку, содержимое которой инициализируется копией символьной строки с нулевым завершением, на которую указывает s. Длина строки определяется первым нулевым символом. Поведение не определено, если [s, s + Traits::length(s)) не является допустимым диапазоном (например, если s нулевой указатель). Этот конструктор не используется для вывода аргументов шаблонного класса, если выводимый тип Allocator не может считаться аллокатором. (начиная с C++17)

6) Создаёт строку с содержимым диапазона [first, last).

Если InputIt целочисленный тип, эквивалентно перегрузке (2), как если бы basic_string(static_cast<size_type>(first), static_cast<value_type>(last), alloc).	(до C++11)
Этот конструктор участвует в разрешении перегрузки, только если InputIt соответствует LegacyInputIterator.	(начиная с C++11)

7) Конструктор копирования. Создаёт строку с копией содержимого other.

8) Конструктор перемещения. Создаёт строку с содержимым other, используя семантику перемещения. other остаётся в допустимом, но неопределённом состоянии.

9) Создаёт строку с содержимым списка инициализаторов ilist.

10) Неявно преобразует t в строковое представление sv, как если бы с помощью std::basic_string_view<CharT, Traits> sv = t;, затем Инициализирует строку содержимым sv, как будто с помощью basic_string(sv.data(), sv.size(), alloc).

Эта перегрузка участвует в разрешении перегрузки, только если std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> равно true и std::is_convertible_v<const StringViewLike&, const CharT*> равно false.

11) Неявно преобразует t в строковое представление sv, как если бы с помощью std::basic_string_view<CharT, Traits> sv = t;, затем Инициализирует строку поддиапазоном [pos, pos + n) из sv, как будто с помощью basic_string(sv.substr(pos, n), alloc).

Эта перегрузка участвует в разрешении перегрузки, только если std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> равно true.

12) std::basic_string не может быть создан из nullptr.

13) Создаёт строку со значениями, содержащимися в диапазоне rg.

Параметры

alloc	—	аллокатор, который будет использоваться для всех выделений памяти этой строки
count	—	размер результирующей строки
ch	—	значение для инициализации строки
pos	—	позиция первого символа, который будет включен
first, last	—	диапазон для копирования символов
s	—	указатель на массив символов, который будет использоваться в качестве источника для инициализации строки
other	—	другая строка, которая будет использоваться в качестве источника для инициализации строки
ilist	—	std::initializer_list для инициализации строки
t	—	объект (конвертируемый в std::basic_string_view) для инициализации строки
rg	—

Сложность

1) Константная.

2-4) Линейная по count.

5) Линейная по длине s.

6) Линейная по расстоянию между first и last.

7) Линейная по размеру other.

8) Константная. Если задан alloc и alloc != other.get_allocator(), то линейная.

9) Линейная по размеру ilist.

13) Линейная по размеру rg.

Исключения

3) std::out_of_range, если pos > other.size().

8) Ничего не генерирует, если alloc == str.get_allocator().

11) std::out_of_range, если pos находится вне диапазона.

Генерирует std::length_error, если длина создаваемой строки превышает max_size() (например, если count > max_size() для (2)). Вызовы Allocator::allocate могут генерировать исключение.

Если по какой-либо причине генерируется исключение, эта функция не имеет эффекта (строгая гарантия безопасности исключений).

Примечание

Инициализация строковым литералом, содержащим встроенные символы '\0', использует перегрузку (5), которая останавливается на первом нулевом символе. Этого можно избежать, указав другой конструктор или используя operator""s:

std::string s1 = "ab\0\0cd";   // s1 содержит "ab"
std::string s2{"ab\0\0cd", 6}; // s2 содержит "ab\0\0cd"
std::string s3 = "ab\0\0cd"s;  // s3 содержит "ab\0\0cd"

Макрос Тестирования функциональности	Значение	Стандарт	Функциональность
__cpp_lib_containers_ranges	202202L	(C++23)	Конструктор с тегами (13) для создания

Пример

Запустить этот код

#include <cassert>
#include <cctype>
#include <iomanip>
#include <iostream>
#include <iterator>
#include <string>

int main()
{
    std::cout << "1) string(); ";
    std::string s1;
    assert(s1.empty() && (s1.length() == 0) && (s1.size() == 0));
    std::cout << "s1.capacity(): " << s1.capacity() << '\n'; // не указано
    
    std::cout << "2) string(size_type count, CharT ch): ";
    std::string s2(4, '=');
    std::cout << std::quoted(s2) << '\n'; // "===="
    
    std::cout << "3) string(const string& other, size_type pos, size_type count): ";
    std::string const other3("Образец");
    std::string s3(other3, 0, other3.length() - 1);
    std::cout << std::quoted(s3) << '\n'; // "Образец"
    
    std::cout << "4) string(const string& other, size_type pos): ";
    std::string const other4("Mutatis Mutandis");
    std::string s4(other4, 8);
    std::cout << std::quoted(s4) << '\n'; // "Mutandis", то есть [8, 16)
    
    std::cout << "5) string(CharT const* s, size_type count): ";
    std::string s5("C-style", 7);
    std::cout << std::quoted(s5) << '\n'; // "C-style", то есть [0, 7)
    
    std::cout << "6) string(CharT const* s): ";
    std::string s6("строка\0в стиле С");
    std::cout << std::quoted(s6) << '\n'; // "строка"
    
    std::cout << "7) string(InputIt first, InputIt last): ";
    char mutable_c_str[] = "another C-style string";
    std::string s7(std::begin(mutable_c_str) + 8, std::end(mutable_c_str) - 1);
    std::cout << std::quoted(s7) << '\n'; // "другая строка в стиле C"
    
    std::cout << "8) string(string&): ";
    std::string const other8("Образец");
    std::string s8(other8);
    std::cout << std::quoted(s8) << '\n'; // "Образец"
    
    std::cout << "9) string(string&&): ";
    std::string s9(std::string("С++ на ") + std::string("примере"));
    std::cout << std::quoted(s9) << '\n'; // "С++ на примере"
    
    std::cout << "a) string(std::initializer_list<CharT>): ";
    std::string sa({'C', '-', 's', 't', 'y', 'l', 'e'});
    std::cout << std::quoted(sa) << '\n'; // "C-style"
    
    // до C++11 разрешение перегрузки выбирает string(InputIt first, InputIt last)
    // [с InputIt = int], которая ведёт себя *как если бы*
    // string(size_type count, CharT ch).
    // После C++11 конструктор InputIt отключен для целочисленных типов и вызывается:
    std::cout << "b) string(size_type count, CharT ch) вызвана: ";
    std::string sb(3, std::toupper('a'));
    std::cout << std::quoted(sb) << '\n'; // "AAA"
    
    //  std::string sc(nullptr); // До C++23: генерирует std::logic_error
                                 // Начиная с C++23: не компилируется,
                                 // смотрите перегрузку (12)
//  std::string sc(0); // То же, что и выше, поскольку литерал 0 является
                       // константой нулевого указателя

    auto const range = {0x43, 43, 43};
#ifdef __cpp_lib_containers_ranges
    std::string sc(std::from_range, range); // тегированный конструктор (13)
    std::cout << "c) string(std::from_range, range) вызвана: ";
#else
    std::string sc(range.begin(), range.end()); // возврат к перегрузке (7)
    std::cout << "c) string(range.begin(), range.end()) вызвана: ";
#endif
    std::cout << std::quoted(sc) << '\n'; // "C++"
}

Возможный вывод:

1) string(); s1.capacity(): 15
2) string(size_type count, CharT ch): "===="
3) string(const string& other, size_type pos, size_type count): "Образец"
4) string(const string& other, size_type pos): "Mutandis"
5) string(CharT const* s, size_type count): "C-style"
6) string(CharT const* s): "строка"
7) string(InputIt first, InputIt last): "C-style string"
8) string(string&): "Образец"
9) string(string&&): "С++ на примере"
a) string(std::initializer_list<CharT>): "C-style"
b) string(size_type count, CharT ch) вызвана: "AAA"
c) string(std::from_range, range) вызвана: "C++"

Отчёты о дефектах

Следующие изменения поведения были применены с обратной силой к ранее опубликованным стандартам C++:

Номер	Применён	Поведение в стандарте	Корректное поведение
LWG 301	C++98	перегрузка (6) не использовала параметр alloc, если InputIt являлся целочисленным типом	использует этот параметр
LWG 847	C++98	не было никаких гарантий безопасности исключений	добавлена надёжная гарантия безопасности исключений
LWG 2193	C++11	конструктор по умолчанию является явным	сделан неявным
LWG 2583	C++98	нет возможности предоставить аллокатор для basic_string(str, pos)	существует конструктор basic_string(str, pos, alloc)
LWG 2946	C++17	перегрузка (10) в некоторых случаях вызывает неоднозначность	исправлено, сделав её шаблоном
LWG 3076	C++17	два конструктора могут вызвать неоднозначность при выводе аргументов шаблонного класса	ограничено

See also

assign	присваивает символы строке (public функция-элемент)
operator=	присваивает значения строке (public функция-элемент)
to_string (C++11)	преобразует целое значение или значение с плавающей запятой в string (функция)
to_wstring (C++11)	преобразует целое значение или значение с плавающей запятой в wstring (функция)
(конструктор) (C++17)	конструирует basic_string_view (public функция-элемент std::basic_string_view<CharT,Traits>)