std::basic_string

Defined in header <string> 
template< 
    class CharT, 
    class Traits = std::char_traits<CharT>, 
    class Allocator = std::allocator<CharT>
> class basic_string;
 (1) 
namespace pmr {
    template <class CharT, class Traits = std::char_traits<CharT>>
    using basic_string = std::basic_string< CharT, Traits,
                                            std::polymorphic_allocator<CharT>>
}
 (2) (since C++17)

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
(public member function)
(destructor)
 destroys the string, deallocating internal storage if used
(public member function)
assigns values to the string
(public member function)
assign characters to a string
(public member function)
returns the associated allocator
(public member function)
Element access
accesses the specified character with bounds checking
(public member function)
accesses the specified character
(public member function)
(C++11)
 accesses the first character
(public member function)
(C++11)
 accesses the last character
(public member function)
returns a pointer to the first character of a string
(public member function)
returns a non-modifiable standard C character array version of the string
(public member function)
(C++17)
 returns a non-modifiable string_view into the entire string
(public member function)
Iterators
(C++11)
 returns an iterator to the beginning
(public member function)
(C++11)
 returns an iterator to the end
(public member function)
(C++11)
 returns a reverse iterator to the beginning
(public member function)
(C++11)
 returns a reverse iterator to the end
(public member function)
Capacity
checks whether the string is empty
(public member function)
returns the number of characters
(public member function)
returns the maximum number of characters
(public member function)
reserves storage
(public member function)
returns the number of characters that can be held in currently allocated storage
(public member function)
(C++11)
 reduces memory usage by freeing unused memory
(public member function)
Operations
clears the contents
(public member function)
inserts characters
(public member function)
removes characters
(public member function)
appends a character to the end
(public member function)
(C++11)
 removes the last character
(public member function)
appends characters to the end
(public member function)
appends characters to the end
(public member function)
compares two strings
(public member function)
(C++20)
 checks if the string starts with the given prefix
(public member function)
(C++20)
 checks if the string ends with the given suffix
(public member function)
replaces specified portion of a string
(public member function)
returns a substring
(public member function)
copies characters
(public member function)
changes the number of characters stored
(public member function)
swaps the contents
(public member function)
find characters in the string
(public member function)
find the last occurrence of a substring
(public member function)
find first occurrence of characters
(public member function)
find first absence of characters
(public member function)
find last occurrence of characters
(public member function)
find last absence of characters
(public member function)

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

Non-member functions

concatenates two strings or a string and a char
(function template)
lexicographically compares two strings
(function template)
specializes the std::swap algorithm
(function template)
(C++20)
 Erases all elements satisfying specific criteria
(function template)
Input/output
performs stream input and output on strings
(function template)
read data from an I/O stream into a string
(function template)
Numeric conversions
(C++11)(C++11)(C++11)
 converts a string to a signed integer
(function)
(C++11)(C++11)
 converts a string to an unsigned integer
(function)
(C++11)(C++11)(C++11)
 converts a string to a floating point value
(function)
(C++11)
 converts an integral or floating point value to string
(function)
(C++11)
 converts an integral or floating point value to wstring
(function)

Literals

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

Helper classes

(C++11)(C++20)(C++11)(C++11)(C++11)(C++20)(C++20)(C++20)(C++20)(C++20)
 hash support for strings
(class template specialization)

Deduction guides(since C++17)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/cpp/string/basic_string