FreeBSD Manual Pages
std::basic_string(3) C++ Standard Libary std::basic_string(3) 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> (2) (since C++17) > using basic_string = std::basic_string<CharT, Traits, std::pmr::polymorphic_allocator<CharT>>; } The class template basic_string stores and manipulates sequences of character-like objects, which are non-array objects of TrivialType and StandardLay- outType. 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. 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()) , and *(s.begin() + s.size()) has value CharT() (a null terminator) (since C++11); or, equivalently, a pointer to s[0] can be passed to functions that expect a pointer to the first element of an array (until C++11) a null-terminated array (since C++11) of CharT. std::basic_string satisfies the requirements of AllocatorAwareCon- tainer (except that customized construct/destroy are not used for construction/destruc- tion of elements), SequenceContainer and ContiguousContainer (since C++17). If any of Traits::char_type and Allocator::char_type is different from CharT, the program is ill-formed. 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 Allocator::size_type (until C++11) size_type std::allocator_traits<Allocator>::size_type (since C++11) Allocator::difference_type (until C++11) difference_type std::allocator_traits<Allocator>::differ- ence_type (since C++11) reference value_type& const_reference const value_type& Allocator::pointer (until C++11) pointer std::allocator_traits<Allocator>::pointer (since C++11) Allocator::const_pointer (until C++11) const_pointer std::allocator_traits<Alloca- tor>::const_pointer (since C++11) LegacyRandomAccessIterator and (until C++20) LegacyContiguousIterator to value_type LegacyRandomAccessIterator, iterator contiguous_iterator, and ConstexprIterator to (since C++20) value_type LegacyRandomAccessIterator and (until C++20) LegacyContiguousIterator to const value_type LegacyRandomAccessIterator, const_iterator 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 inter- nal 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) assign_range assign a range of characters to a string (C++23) (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 (DR*) (public member function) back accesses the last character (DR*) (public member function) data returns a pointer to the first character of a string (public member function) returns a non-modifiable standard C char- acter 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 begin- ning 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 (DR*) (public member function) Modifiers clear clears the contents (public member function) insert inserts characters (public member function) insert_range inserts a range of characters (C++23) (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 (DR*) (public member function) append appends characters to the end (public member function) append_range appends a range of characters to the end (C++23) (public member function) operator+= appends characters to the end (public member function) replace replaces specified portion of a string (public member function) replace_with_range replaces specified portion of a string with a range of (C++23) characters (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 finds the first occurrence of the given substring (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) Operations 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) substr returns a substring (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 inte- ger (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::basic_string> hash support for strings (C++11) (class template specialization) 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. Feature-test macro Value Std Feature __cpp_lib_string_udls 201304L (C++14) User-defined literals for string types __cpp_lib_starts_ends_with 201711L (C++20) starts_with, ends_with __cpp_lib_constexpr_string 201907L (C++20) Constexpr for std::ba- sic_string __cpp_lib_char8_t 201907L (C++20) std::u8string __cpp_lib_erase_if 202002L (C++20) erase, erase_if __cpp_lib_string_contains 202011L (C++23) contains __cpp_lib_string_resize_and_overwrite 202110L (C++23) re- size_and_overwrite Member func- tions for __cpp_lib_containers_ranges 202202L (C++23) construction, insertion, and replacement that accept container com- patible range 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 Defect reports The following behavior-changing defect reports were applied retroac- tively to previously published C++ standards. DR Applied to Behavior as published Correct behavior contiguity of the storage for elements of LWG 530 C++98 basic_string required again was accidently made not required by LWG259 the behavior is undefined if any of the program is LWG 2994 C++98 Traits::char_type^[1] ill-formed in this (P1148R0) and Allocator::char_type is different from case CharT 1. The Traits::char_type case is fixed in P1148R0. See also basic_string_view read-only string view (C++17) (class template) External links C++ string handling Hidden category: * Pages with unreviewed LWG DR marker http://cppreference.com 2024.06.10 std::basic_string(3)
NAME | Synopsis | Template parameters | Member types | Member functions | Element access | Iterators | Capacity | Modifiers | Search | Operations | Constants | Non-member functions | Input/output | Numeric conversions | Literals | Helper classes | Notes | Example | Output: | See also | External links | Hidden category:
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::u16string&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>