std::basic_string (3) - Linux Manuals

std::basic_string: std::basic_string

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::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 CharT[] array. (since C++11)

std::basic_string satisfies the requirements of AllocatorAwareContainer, SequenceContainer
and ContiguousContainer
(since C++17)
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)

difference_type Allocator::difference_type (until C++11)
                       std::allocator_traits<Allocator>::difference_type (since C++11)

reference Allocator::reference (until C++11)
                       value_type& (since C++11)

const_reference Allocator::const_reference (until C++11)
                       const value_type& (since C++11)

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)

iterator LegacyRandomAccessIterator
const_iterator Constant LegacyRandomAccessIterator
reverse_iterator std::reverse_iterator<iterator>
const_reverse_iterator std::reverse_iterator<const_iterator>

Member functions

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

Element access

                           accesses the specified character with bounds checking
at (public member function)
                           accesses the specified character
operator[] (public member function)

front accesses the first character
                           (public member function)
(C++11)

back accesses the last character
                           (public member function)
(C++11)
                           returns a pointer to the first character of a string
data (public member function)
                           returns a non-modifiable standard C character array version of the string
c_str (public member function)

operator_basic_string_view returns a non-modifiable string_view into the entire string
                           (public member function)
(C++17)

Iterators

begin
cbegin returns an iterator to the beginning
                           (public member function)

(C++11)

end_
cend returns an iterator to the end
                           (public member function)

(C++11)

rbegin
crbegin returns a reverse iterator to the beginning
                           (public member function)

(C++11)

rend
crend returns a reverse iterator to the end
                           (public member function)

(C++11)

Capacity

                           checks whether the string is empty
empty (public member function)
                           returns the number of characters
size (public member function)
length
                           returns the maximum number of characters
max_size (public member function)
                           reserves storage
reserve (public member function)
                           returns the number of characters that can be held in currently allocated storage
capacity (public member function)

shrink_to_fit reduces memory usage by freeing unused memory
                           (public member function)
(C++11)

Operations

                           clears the contents
clear (public member function)
                           inserts characters
insert (public member function)
                           removes characters
erase (public member function)
                           appends a character to the end
push_back (public member function)

pop_back removes the last character
                           (public member function)
(C++11)
                           appends characters to the end
append (public member function)
                           appends characters to the end
operator+= (public member function)
                           compares two strings
compare (public member function)

starts_with checks if the string starts with the given prefix
                           (public member function)
(C++20)

ends_with checks if the string ends with the given suffix
                           (public member function)
(C++20)
                           replaces specified portion of a string
replace (public member function)
                           returns a substring
substr (public member function)
                           copies characters
copy (public member function)
                           changes the number of characters stored
resize (public member function)
                           swaps the contents
swap (public member function)

Search

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

Constants

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

Non-member functions

                             concatenates two strings or a string and a char
operator+ (function template)

operator==
operator!= lexicographically compares two strings
operator< (function template)
operator>
operator<=
operator>=
                             specializes the std::swap algorithm
std::swap(std::basic_string) (function template)

erase(std::basic_string) Erases all elements satisfying specific criteria
erase_if(std::basic_string) (function template)

(C++20)

Input/output

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

Numeric conversions

stoi
stol
stoll converts a string to a signed integer
                             (function)
(C++11)
(C++11)
(C++11)

stoul
stoull converts a string to an unsigned integer
                             (function)
(C++11)
(C++11)

stof
stod
stold converts a string to a floating point value
                             (function)
(C++11)
(C++11)
(C++11)

to_string converts an integral or floating point value to string
                             (function)
(C++11)

to_wstring converts an integral or floating point value to wstring
                             (function)
(C++11)

Literals

Defined in inline namespace std::literals::string_literals

operator""s Converts a character array literal to basic_string
            (function)
(C++14)

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
                               (class template specialization)
(C++11)
(C++20)
(C++11)
(C++11)
(C++11)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)

Deduction_guides(since C++17)