NAME¶

std::basic_string - std::basic_string

Synopsis¶

Defined in header <string>
template<

class CharT,
class Traits = std::char_traits<CharT>, (1)
class Allocator = std::allocator<CharT>

> class basic_string;
namespace pmr {

template <class CharT, class Traits = std::char_traits<CharT>>
using basic_string = std::basic_string< CharT, Traits, (2) (since C++17)
std::pmr::polymorphic_allocator<CharT> >;

}

The class template basic_string stores and manipulates sequences of char-like
objects, which are non-array objects of trivial standard-layout type. The class is
dependent neither on the character type nor on the nature of operations on that
type. The definitions of the operations are supplied via the Traits template
parameter - a specialization of std::char_traits or a compatible traits class.
Traits::char_type and CharT must name the same type; otherwise the program is
ill-formed.

The elements of a basic_string are stored contiguously, that is, for a basic_string
s, &*(s.begin() + n) == &*s.begin() + n for any n in [0, s.size()), or,
equivalently, a pointer to s[0] can be passed to functions that expect a pointer to
the first element of a
null-terminated
(since C++11)CharT[] array.

std::basic_string satisfies the requirements of AllocatorAwareContainer (except that
customized construct/destroy are not used for construction/destruction of elements),
SequenceContainer
and ContiguousContainer
(since C++17)

Member functions of std::basic_string are constexpr: it is possible to
create and use std::string objects in the evaluation of a constant
expression.
(since C++20)
However, std::string objects generally cannot be constexpr, because
any dynamically allocated storage must be released in the same
evaluation of constant expression.

Several typedefs for common character types are provided:

Defined in header <string>
Type Definition
std::string std::basic_string<char>
std::wstring std::basic_string<wchar_t>
std::u8string (C++20) std::basic_string<char8_t>
std::u16string (C++11) std::basic_string<char16_t>
std::u32string (C++11) std::basic_string<char32_t>
std::pmr::string (C++17) std::pmr::basic_string<char>
std::pmr::wstring (C++17) std::pmr::basic_string<wchar_t>
std::pmr::u8string (C++20) std::pmr::basic_string<char8_t>
std::pmr::u16string (C++17) std::pmr::basic_string<char16_t>
std::pmr::u32string (C++17) std::pmr::basic_string<char32_t>

Template parameters¶

CharT - character type
Traits - traits class specifying the operations on the character type
Allocator - Allocator type used to allocate internal storage

Member types¶

Member type Definition
traits_type Traits
value_type CharT
allocator_type Allocator
size_type Allocator::size_type (until C++11)
std::allocator_traits<Allocator>::size_type (since C++11)
Allocator::difference_type (until
difference_type C++11)
std::allocator_traits<Allocator>::difference_type (since
C++11)
reference value_type&
const_reference const value_type&
pointer Allocator::pointer (until C++11)
std::allocator_traits<Allocator>::pointer (since C++11)
const_pointer Allocator::const_pointer (until C++11)
std::allocator_traits<Allocator>::const_pointer (since C++11)
LegacyRandomAccessIterator and (until C++20)
LegacyContiguousIterator to value_type
iterator LegacyRandomAccessIterator,
contiguous_iterator, and ConstexprIterator to (since C++20)
value_type
LegacyRandomAccessIterator and (until C++20)
LegacyContiguousIterator to const value_type
const_iterator LegacyRandomAccessIterator,
contiguous_iterator, and ConstexprIterator to (since C++20)
const value_type
reverse_iterator std::reverse_iterator<iterator>
const_reverse_iterator std::reverse_iterator<const_iterator>

Member functions¶

constructor constructs a basic_string
(public member function)
destroys the string, deallocating internal storage if
destructor used
(public member function)
operator= assigns values to the string
(public member function)
assign assign characters to a string
(public member function)
get_allocator returns the associated allocator
(public member function)

Element access¶

at accesses the specified character with bounds checking
(public member function)
operator[] accesses the specified character
(public member function)
front accesses the first character
(C++11) (public member function)
back accesses the last character
(C++11) (public member function)
data returns a pointer to the first character of a string
(public member function)
returns a non-modifiable standard C character array
c_str version of the string
(public member function)
operator basic_string_view returns a non-modifiable string_view into the entire
(C++17) string
(public member function)

Iterators¶

begin returns an iterator to the beginning
cbegin (public member function)
(C++11)
end returns an iterator to the end
cend (public member function)
(C++11)
rbegin returns a reverse iterator to the beginning
crbegin (public member function)
(C++11)
rend returns a reverse iterator to the end
crend (public member function)
(C++11)

Capacity¶

empty checks whether the string is empty
(public member function)
size returns the number of characters
length (public member function)
max_size returns the maximum number of characters
(public member function)
reserve reserves storage
(public member function)
returns the number of characters that can be held in
capacity currently allocated storage
(public member function)
shrink_to_fit reduces memory usage by freeing unused memory
(C++11) (public member function)

Operations¶

clear clears the contents
(public member function)
insert inserts characters
(public member function)
erase removes characters
(public member function)
push_back appends a character to the end
(public member function)
pop_back removes the last character
(C++11) (public member function)
append appends characters to the end
(public member function)
operator+= appends characters to the end
(public member function)
compare compares two strings
(public member function)
starts_with checks if the string starts with the given prefix
(C++20) (public member function)
ends_with checks if the string ends with the given suffix
(C++20) (public member function)
contains checks if the string contains the given substring or
(C++23) character
(public member function)
replace replaces specified portion of a string
(public member function)
substr returns a substring
(public member function)
copy copies characters
(public member function)
resize changes the number of characters stored
(public member function)
changes the number of characters stored and possibly
resize_and_overwrite overwrites indeterminate contents via user-provided
(C++23) operation
(public member function)
swap swaps the contents
(public member function)

Search¶

find find characters in the string
(public member function)
rfind find the last occurrence of a substring
(public member function)
find_first_of find first occurrence of characters
(public member function)
find_first_not_of find first absence of characters
(public member function)
find_last_of find last occurrence of characters
(public member function)
find_last_not_of find last absence of characters
(public member function)

Constants¶

npos special value. The exact meaning depends on the context
[static] (public static member constant)

Non-member functions¶

operator+ concatenates two strings or a string and a char
(function template)
operator==
operator!=
operator<
operator>
operator<=
operator>= lexicographically compares two strings
operator<=> (function template)
(removed in C++20)
(removed in C++20)
(removed in C++20)
(removed in C++20)
(removed in C++20)
(C++20)
std::swap(std::basic_string) specializes the std::swap algorithm
(function template)
erase(std::basic_string) Erases all elements satisfying specific criteria
erase_if(std::basic_string) (function template)
(C++20)

Input/output¶

operator<< performs stream input and output on strings
operator>> (function template)
getline read data from an I/O stream into a string
(function template)

Numeric conversions¶

stoi
stol
stoll converts a string to a signed integer
(C++11) (function)
(C++11)
(C++11)
stoul
stoull converts a string to an unsigned integer
(C++11) (function)
(C++11)
stof
stod
stold converts a string to a floating point value
(C++11) (function)
(C++11)
(C++11)
to_string converts an integral or floating point value to string
(C++11) (function)
to_wstring converts an integral or floating point value to wstring
(C++11) (function)

Literals¶

Defined in inline namespace std::literals::string_literals
operator""s Converts a character array literal to basic_string
(C++14) (function)

Helper classes¶

std::hash<std::string>
std::hash<std::u8string>
std::hash<std::u16string>
std::hash<std::u32string>
std::hash<std::wstring>
std::hash<std::pmr::string>
std::hash<std::pmr::u8string>
std::hash<std::pmr::u16string>
std::hash<std::pmr::u32string>
std::hash<std::pmr::wstring> hash support for strings
(C++11) (class template specialization)
(C++20)
(C++11)
(C++11)
(C++11)
(C++17)
(C++20)
(C++17)
(C++17)
(C++17)

Deduction guides (since C++17)

Notes¶

Although it is required that customized construct or destroy is used when
constructing or destroying elements of std::basic_string until C++23, all
implementations only used the default mechanism. The requirement is corrected by
P1072R10 to match existing practice.

Example¶

// Run this code

#include <iostream>
#include <string>

int main()
{
using namespace std::literals;

// Creating a string from const char*
std::string str1 = "hello";

// Creating a string using string literal
auto str2 = "world"s;

// Concatenating strings
std::string str3 = str1 + " " + str2;

// Print out the result
std::cout << str3 << '\n';

std::string::size_type pos = str3.find(" ");
str1 = str3.substr(pos + 1); // the part after the space
str2 = str3.substr(0, pos); // the part till the space

std::cout << str1 << ' ' << str2 << '\n';

// Accessing an element using subscript operator[]
std::cout << str1[0] << '\n';
str1[0] = 'W';
std::cout << str1 << '\n';
}

Output:¶

hello world
world hello
w
World

See also¶

basic_string_view read-only string view
(C++17) (class template)