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

NAME
     std::basic_stringbuf::str - std::basic_stringbuf::str

Synopsis
	std::basic_string<CharT,     Traits,	 Allocator>	str()	  const;
     (until C++20)
	std::basic_string<CharT,    Traits,	Allocator>     str()	 const&;
     (since C++20)
	template<class SAlloc>
	std::basic_string<CharT,  Traits,  SAlloc> str( const SAlloc& a      (2)
     (since C++20)
	) const;
	std::basic_string<CharT, Traits, Allocator> str()  &&;		     (3)
     (since C++20)
	void str( const std::basic_string<CharT, Traits, Allocator>& s (1) (4)
	);
	template<class	SAlloc> 					     (5)
     (since C++20)
	void str( const std::basic_string<CharT, Traits, SAlloc>& s );
	void str( std::basic_string<CharT, Traits, Allocator>&& s  );	     (6)
     (since C++20)
	template<  class  StringViewLike >				     (7)
     (since C++26)
	void str( const StringViewLike& t );

	Gets and sets the underlying string.

	In the descriptions below, buf and mode are exposition-only data members
     of *this.

	1) Creates and returns a std::basic_string object containing a	copy  of
     this
	std::basic_stringbuf's	underlying  character  sequence.  For input-only
     streams, the
	returned string contains the characters from  the  range  [eback(),  eg-
     ptr()). For
	input/output  or  output-only  streams,  contains  the	characters  from
     pbase() to the
	last character in the sequence regardless of egptr() and epptr().

	The member character sequence in a buffer open for writing can be  over-
     allocated for
	efficiency  purposes.  In that case, only the initialized characters are
     returned:
	these characters are the ones that were obtained from the  string  argu-
     ment of the
	constructor,  the  string  argument  of the most recent call to a setter
     overload of
	str(), or from a write operation. A  typical  implementation  that  uses
     over-allocation
	maintains  a  high-watermark pointer to track the end of the initialized
     part of the
	buffer and this overload returns the  characters  from	pbase()  to  the
     high-watermark
	pointer.

	Equivalent	to	return	    std::basic_string<CharT,	 Traits,
     (since C++20)
	Allocator>(view(), get_allocator());.

	2) Same as (1), except that a is used to construct the returned std::ba-
     sic_string.
	Equivalent to return  std::basic_string<CharT,	Traits,  SAlloc>(view(),
     a);.
	This  overload	participates in overload resolution only if SAlloc meets
     the
	requirements of Allocator.
	3) Creates a std::basic_string object as if by move constructing it from
     *this's
	underlying character sequence in buf. buf may need  to	be  adjusted  to
     contain the
	same content as in (1) at first. After that, sets buf to empty and calls
	init_buf_ptrs(), then returns the std::basic_string object.
	4)  Replaces  the  underlying  character sequence as if by buf = s, then
     calls
	init_buf_ptrs().
	5) Same as (4), except the type of s's allocator is not Allocator.
	This   overload   participates	 in   overload	 resolution   only    if
     std::is_same_v<SAlloc,
	Allocator> is false.
	6)   Replaces	the  underlying  character  sequence  as  if  by  buf  =
     std::move(s), then
	calls init_buf_ptrs().
	7) Implicitly converts	t  to  a  string  view	sv  as	if  by	std::ba-
     sic_string_view<CharT,
	Traits>  sv  = t;, then replaces the underlying character sequence as if
     by buf = sv,
	then calls init_buf_ptrs().
	This overload participates in overload resolution only if
	std::is_convertible_v<const StringViewLike&,
			      std::basic_string_view<CharT, Traits>> is true.

Parameters
	s - a std::basic_string object holding	the  replacement  character  se-
     quence
	t  -  an  object (convertible to std::basic_string_view) holding the re-
     placement
	    character sequence
	a - allocator to use for all memory allocations of the returned std::ba-
     sic_string

Return value
	1-3) A std::basic_string object holding this buffer's underlying charac-
     ter sequence.
	4-7) (none)

Notes
	This	function    is	  typically    accessed     through	std::ba-
     sic_istringstream::str(),
	std::basic_ostringstream::str(), or std::basic_stringstream::str().

		Feature-test macro	    Value    Std		Feature
	__cpp_lib_sstream_from_string_view  202306L  (C++26)  Interfacing string
     streams with
							   std::string_view

Example
     // Run this code

      #include <iostream>
      #include <sstream>

      int main()
      {
	  int n;

	  std::istringstream in;  // could also use in("1 2")
	  in.rdbuf()->str("1 2"); // set the get area
	  in >> n;
	  std::cout << "after reading the first int from \"1 2\", the int is "
		    << n << ", str() = \"" << in.rdbuf()->str() << "\"\n"; // or
     in.str()

	  std::ostringstream out("1 2");
	  out << 3;
	  std::cout << "after writing the int '3' to output stream \"1 2\""
		    << ", str() = \"" << out.str() << "\"\n";

	  std::ostringstream ate("1 2", std::ios_base::ate); // C++11
	  ate << 3;
	  std::cout << "after writing the int '3' to append stream \"1 2\""
		    << ", str() = \"" << ate.str() << "\"\n";
      }

Output:
      after reading the first int from "1 2", the int is 1, str() = "1 2"
      after writing the int '3' to output stream "1 2", str() = "3 2"
      after writing the int '3' to append stream "1 2", str() = "1 23"

	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
			   1. overload (1) did not specify the content
	LWG 432 C++98	   of the  underlying  character  sequence	    both
     specified
			   2. overload (4) did not specify how the
			   input and output sequences are initialized
			   overload (4) set epptr() to point one past
	LWG  562 C++98	    the last underlying 			 epptr()
     can be set
			   character if bool(mode &  std::ios_base::out)  beyond
     that position
			   == true

See also
		gets or sets the contents of underlying string device object
	str	      (public	    member	 function	of	std::ba-
     sic_stringstream<CharT,Traits,Allocator>)

	view	obtains a view over the underlying character sequence
	(C++20) (public member function)

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