home | help 
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 StandardLayout-
     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.

	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  AllocatorAwareContainer
     (except that
	customized  construct/destroy  are not used for construction/destruction
     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			    (un-
     til 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>::difference_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<Allocator>::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	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)
	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 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
	(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 sub-
     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)

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 suf-
     fix
	(C++20) 		   (public member function)
	contains		    checks if the string contains the given sub-
     string 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 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::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 cor-
     rected by
	P1072R10 to match existing practice.

		 Feature-test macro	       Value	Std		 Feature
	__cpp_lib_string_udls		       201304L (C++14) User-defined lit-
     erals 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::basic_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) resize_and_over-
     write
							      Member   functions
     for
	__cpp_lib_containers_ranges	       202202L (C++23) construction, in-
     sertion, and
							      replacement   that
     accept
							      container compati-
     ble 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		    Cor-
     rect behavior
			     contiguity of the storage for elements of
	LWG  530    C++98	basic_string				     re-
     quired 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. a 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)
home | help