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

NAME
     std::basic_string::substr - std::basic_string::substr

Synopsis
	basic_string  substr(  size_type  pos  =  0, size_type		  (until
     C++23)
	count = npos ) const;					      (constexpr
     since C++20)
	constexpr basic_string
	    substr(  size_type	pos  =	0,  size_type count =	  (1)	  (since
     C++23)
	npos ) const&;
	constexpr basic_string substr( size_type  pos  =  0,	     (2)  (since
     C++23)
	size_type count = npos ) &&;

	Returns  a  substring [pos, pos + count). If the requested substring ex-
     tends past the
	end of the string, i.e. the count is greater than size() - pos (e.g.  if
     count ==
	npos), the returned substring is [pos, size()).

	1) Equivalent to return basic_string(*this, pos, count);.
	2) Equivalent to return basic_string(std::move(*this), pos, count);.

Parameters
	pos   - position of the first character to include
	count - length of the substring

Return value
	String containing the substring [pos, pos + count) or [pos, size()).

Exceptions
	std::out_of_range if pos > size().

	If an exception is thrown for any reason, these functions have no effect
     (strong
	exception safety guarantee).

Complexity
	Linear in count.

Notes
	The allocator of the returned string is default-constructed: the new al-
     locator might
	not be a copy of get_allocator().

Example
     // Run this code

      #include <iostream>
      #include <string>

      int main()
      {
	  std::string a = "0123456789abcdefghij";

	  // count is npos, returns [pos, size())
	  std::string sub1 = a.substr(10);
	  std::cout << sub1 << '\n';

	  //  both  pos  and  pos + count are within bounds, returns [pos, pos +
     count)
	  std::string sub2 = a.substr(5, 3);
	  std::cout << sub2 << '\n';

	  // pos is within bounds, pos + count is not, returns [pos, size())
	  std::string sub4 = a.substr(a.size() - 3, 50);
	  // this is effectively equivalent to
	  // std::string sub4 = a.substr(17, 3);
	  // since a.size() == 20, pos == a.size() - 3 == 17, and a.size() - pos
     == 3

	  std::cout << sub4 << '\n';

	  try
	  {
	      // pos is out of bounds, throws
	      std::string sub5 = a.substr(a.size() + 3, 50);
	      std::cout << sub5 << '\n';
	  }
	  catch (const std::out_of_range& ex)
	  {
	      std::cout << ex.what() << '\n';
	  }
      }

Possible output:
      abcdefghij
      567
      hij
      basic_string::substr: __pos (which is 23) > this->size() (which is 20)

	Defect reports

	The following behavior-changing defect	reports  were  applied	retroac-
     tively to
	previously published C++ standards.

	  DR	Applied to	  Behavior as published 	     Correct be-
     havior
	LWG  847 C++98	    there was no exception safety	added strong ex-
     ception safety
			   guarantee			       guarantee

See also
	copy	 copies characters
		 (public member function)
	size	 returns the number of characters
	length	 (public member function)
	find	 finds the first occurrence of the given substring
		 (public member function)
	npos	 special value. The exact meaning depends on the context
	[static] (public static member constant)
	substr	 returns a substring
		 (public	member	      function	      of	std::ba-
     sic_string_view<CharT,Traits>)

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