home | help 
std::basic_string_view(3)      C++ Standard Libary     std::basic_string_view(3)

NAME
     std::basic_string_view - std::basic_string_view

Synopsis
	Defined in header <string_view>
	template<

	    class CharT,			    (since C++17)
	    class Traits = std::char_traits<CharT>

	> class basic_string_view;

	The  class template basic_string_view describes an object that can refer
     to a
	constant contiguous sequence of CharT with the first element of the  se-
     quence at
	position zero.

	For a basic_string_view str, pointers, iterators, and references to ele-
     ments of str
	are invalidated when an operation invalidates a pointer in the range
	[str.data(), str.data() + str.size()).

	Every  specialization  of  std::basic_string_view is a TriviallyCopyable
     (since C++23)
	type.

	A typical implementation holds only two members: a pointer  to	constant
     CharT and a
	size.

	Several typedefs for common character types are provided:

	Defined in header <string_view>
	Type			    Definition
	std::string_view (C++17)    std::basic_string_view<char>
	std::wstring_view (C++17)   std::basic_string_view<wchar_t>
	std::u8string_view (C++20)  std::basic_string_view<char8_t>
	std::u16string_view (C++17) std::basic_string_view<char16_t>
	std::u32string_view (C++17) std::basic_string_view<char32_t>

Template parameters
	CharT  - character type
		 CharTraits  class  specifying	the  operations on the character
     type. Like for
	Traits - std::basic_string, Traits::char_type must name the same type as
     CharT or
		 the program is ill-formed.

	Nested types

	Nested type	       Definition
	traits_type	       Traits
	value_type	       CharT
	pointer 	       CharT*
	const_pointer	       const CharT*
	reference	       CharT&
	const_reference        const CharT&
			       implementation-defined  constant  LegacyRandomAc-
     cessIterator,

	const_iterator	       and LegacyContiguousIterator		  (until
     C++20)
			       ConstexprIterator, and contiguous_iterator (since
     C++20)

			       whose value_type is CharT
	iterator	       const_iterator
	const_reverse_iterator std::reverse_iterator<const_iterator>
	reverse_iterator       const_reverse_iterator
	size_type	       std::size_t
	difference_type        std::ptrdiff_t

	Note: iterator and const_iterator are the same type because string views
     are views
	into constant character sequences.

	All requirements on the iterator types of a Container applies to the it-
     erator and
	const_iterator types of basic_string_view as well.

Member functions
	      Constructors and assignment
	constructor	  constructs a basic_string_view
			  (public member function)
	operator=	  assigns a view
			  (public member function)

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

Element access
	operator[]	  accesses the specified character
			  (public member function)
	at		  accesses the specified character with bounds checking
			  (public member function)
	front		  accesses the first character
			  (public member function)
	back		  accesses the last character
			  (public member function)
	data		  returns a pointer to the first character of a view
			  (public member function)

Capacity
	size		  returns the number of characters
	length		  (public member function)
	max_size	  returns the maximum number of characters
			  (public member function)
	empty		  checks whether the view is empty
			  (public member function)

Modifiers
	remove_prefix	  shrinks the view by moving its start forward
			  (public member function)
	remove_suffix	  shrinks the view by moving its end backward
			  (public member function)
	swap		  swaps the contents
			  (public member function)

Operations
	copy		  copies characters
			  (public member function)
	substr		  returns a substring
			  (public member function)
	compare 	  compares two views
			  (public member function)
	starts_with	  checks if the string view starts with the given prefix
	(C++20) 	  (public member function)
	ends_with	  checks if the string view ends with the given suffix
	(C++20) 	  (public member function)
	contains	  checks if the string view contains the given substring
     or
	(C++23) 	  character
			  (public member function)
	find		  find characters in the view
			  (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_last_of	  find last occurrence of characters
			  (public member function)
	find_first_not_of find first absence 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 con-
     text
	[static]	  (public static member constant)

Non-member functions
	operator==
	operator!=
	operator<
	operator>
	operator<=
	operator>=
	operator<=>	   lexicographically compares two string views
	(C++17) 	   (function template)
	(removed in C++20)
	(removed in C++20)
	(removed in C++20)
	(removed in C++20)
	(removed in C++20)
	(C++20)

Input/output
	operator<<	   performs stream output on string views
	(C++17) 	   (function template)

Literals
	Defined in inline namespace std::literals::string_view_literals
	operator""sv	creates a string view of a character array literal
	(C++17) 	(function)

Helper classes
	std::hash<std::string_view>
	std::hash<std::wstring_view>
	std::hash<std::u8string_view>
	std::hash<std::u16string_view>
	std::hash<std::u32string_view> hash support for string views
	(C++17) 		       (class template specialization)
	(C++17)
	(C++20)
	(C++17)
	(C++17)

	Helper templates

	template< class CharT, class Traits >

	inline				constexpr			    bool
     (since
										     C++20)
	    ranges::enable_borrowed_range<std::basic_string_view<CharT, Traits>>
     =
	true;

	This   specialization	of   ranges::enable_borrowed_range   makes   ba-
     sic_string_view satisfy
	borrowed_range.

	template< class CharT, class Traits >

	inline				constexpr			    bool
     (since C++20)

	    ranges::enable_view<std::basic_string_view<CharT, Traits>> =
	true;

	This  specialization of ranges::enable_view makes basic_string_view sat-
     isfy view.

	  Deduction guides (since C++20)

Notes
	It is the programmer's responsibility to  ensure  that	std::string_view
     does not
	outlive the pointed-to character array:

      std::string_view good{"a string literal"};
	  // "Good" case: `good` points to a static array.
	  // String literals reside in persistent data storage.

      std::string_view bad{"a temporary string"s};
	  //  "Bad"  case:  `bad` holds a dangling pointer since the std::string
     temporary,
	  // created by std::operator""s, will be destroyed at the  end  of  the
     statement.

	Specializations of std::basic_string_view are already trivially copyable
     types in
	all  existing implementations, even before the formal requirement intro-
     duced in
	C++23.

	   Feature-test macro	   Value    Std        Feature
	__cpp_lib_string_view	  201606L (C++17) std::string_view
				  201803L (C++20) ConstexprIterator
	__cpp_lib_string_contains 202011L (C++23) contains

Example
     // Run this code

      #include <iostream>
      #include <string_view>

      int main()
      {
	  constexpr std::string_view unicode[]{"aaa", "aaa", "aaa", "aaa"};

	  for (int y{}, p{}; y != 6; ++y, p = ((p + 1) % 4))
	  {
	      for (int x{}; x != 16; ++x)
		  std::cout << unicode[p];
	      std::cout << '\n';
	  }
      }

Output:
      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

	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
			    only pointers, iterators,  and	  all  pointers,
     iterators, and
			    references				references
	LWG 3203 C++17	    returned from the member functions	to elements of
			    of						     ba-
     sic_string_view
			    basic_string_view might be		may  be  invali-
     dated
			    invalidated

See also
	basic_string	 stores and manipulates sequences of characters
			 (class template)
	span		 a non-owning view over a contiguous sequence of objects
	(C++20) 	 (class template)
	initializer_list  creates  a  temporary array in list-initialization and
     then
	(C++11) 	 references it
			 (class template)

http://cppreference.com 	   2024.06.10	       std::basic_string_view(3)
home | help