home | help 
std::basic_...ic_stringbuf(3)  C++ Standard Libary std::basic_...ic_stringbuf(3)

NAME
     std::basic_stringbuf::basic_stringbuf - std::basic_stringbuf::basic_string-
     buf

Synopsis
	explicit basic_stringbuf( std::ios_base::openmode which =
				      std::ios_base::in 		       |
     (until C++11)
	std::ios_base::out );
	explicit    basic_stringbuf(	std::ios_base::openmode     which     );
     (since C++11)
	basic_stringbuf()
	    :  basic_stringbuf(  std::ios_base::in  | std::ios_base::out     (2)
     (since C++11)
	) {}
	explicit

	    basic_stringbuf( const std::basic_string<CharT, Traits,
	Allocator>& s,							  (3)
			     std::ios_base::openmode which =

				 std::ios_base::in |
	std::ios_base::out );
	explicit basic_stringbuf( std::basic_string<CharT, Traits,
	Allocator>&& s,

				  std::ios_base::openmode  which  =	     (4)
     (since C++20)

				      std::ios_base::in |
	std::ios_base::out );
	basic_stringbuf(  std::ios_base::openmode  which,  const	     (5)
     (since C++20)
	Allocator& a );
	explicit basic_stringbuf( const Allocator& a )
	    : basic_stringbuf(	std::ios_base::in  |			     (6)
     (since C++20)
	std::ios_base::out, a ) {}
	template< class SAlloc >

	explicit basic_stringbuf( const std::basic_string<CharT,
	Traits,  SAlloc>&  s,						     (7)
     (since C++20)
				  std::ios_base::openmode which =

				      std::ios_base::in |
	std::ios_base::out );					      (1)
	template< class SAlloc >

	basic_stringbuf( const std::basic_string<CharT, Traits,
	SAlloc>&  s,							     (8)
     (since C++20)

			 std::ios_base::openmode which, const
	Allocator& a );
	template< class SAlloc >

	basic_stringbuf( const std::basic_string<CharT, Traits,
	SAlloc>&   s,							     (9)
     (since C++20)
			 const Allocator& a )

	    : basic_stringbuf( s, std::ios_base::in |
	std::ios_base::out, a ) {}
	template< class StringViewLike >

	explicit basic_stringbuf( const StringViewLike& t,
				  std::ios_base::openmode which  =	    (10)
     (since C++26)

				      std::ios_base::in |
	std::ios_base::out );
	template< class StringViewLike >

	basic_stringbuf(  const  StringViewLike& t,			    (11)
     (since C++26)

			 std::ios_base::openmode which, const
	Allocator& a );
	template< class StringViewLike >
	basic_stringbuf( const StringViewLike& t, const Allocator&  a	    (12)
     (since C++26)
	);
	basic_stringbuf(  basic_stringbuf&&  rhs );			    (13)
     (since C++11)
	basic_stringbuf( basic_stringbuf&& rhs, const Allocator& a  );	    (14)
     (since C++20)
	basic_stringbuf(  const  basic_stringbuf& rhs ) = delete;	    (15)
     (since C++11)

	The std::basic_streambuf base and the exposition-only data  members  buf
     and mode are
	initialized as follows.

	After initializing these subobjects, overloads (3-12) initialize the in-
     put and
	output sequences as if by calling init_buf_ptrs().

	 Overload		std::basic_streambuf			     buf
     mode
			    base
	(1)							       which
					    implementation-defined
     std::ios_base::in |
	(2)				    (see below)
								       std::ios_base::out
	(3)				    s
	(4)				    std::move(s)	       which
	(5)
					    a
     std::ios_base::in |
	(6)
		   default-initialized
     std::ios_base::out
	(7)				    s			       which
	(8)
					    {s, 			      a}
     std::ios_base::in |
	(9)
								       std::ios_base::out
	(10)				    {sv, Allocator()}	       which
	(11)
					    {sv,			      a}
     std::ios_base::in |
	(12)
								       std::ios_base::out
	(13)	   rhs			    std::move(rhs).str()
	(14)	   (copy constructed)	     {std::move(rhs).str(),    rhs.mode
					    a}

	1,2) Overload
	(1)
	(until C++11)
	(2)
	(since C++11) is the default constructor. It  is  implementation-defined
     whether the
	sequence  pointers  (eback(), gptr(), egptr(), pbase(), pptr(), epptr())
     are
	initialized to null pointers.
	5,6) When the construction is complete, str.empty() is true.
	7)  This  overload  participates  in   overload   resolution   only   if
     std::is_same_v<SAlloc,
	Allocator> is false.
	10-12) Implicitly converts t to a string view sv as if by
	std::basic_string_view<CharT,  Traits> sv = t;, then it is used as above
     in the
	table.
	These overloads participate in overload resolution only if
	std::is_convertible_v<const StringViewLike&,
			      std::basic_string_view<CharT, Traits>> is true.
	13,14) Overload (13) is the move constructor. It  is  implementation-de-
     fined whether
	the six sequence pointers in *this obtain the values which rhs had.
	When the construction is complete, rhs is empty but usable, and
	  * Let rhs_p refer to the state of rhs just prior to this construction,
     the
	    following expressions will evaluate to true:

	  * str() == rhs_p.str()
	  * getloc() == rhs_p.getloc()
	  * gptr() - eback() == rhs_p.gptr() - rhs_p.eback()
	  * egptr() - eback() == rhs_p.egptr() - rhs_p.eback()
	  * pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()
	  * epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase()
	  *  Let  rhs_a  refer to the state of rhs just after this construction,
     the following
	    expressions will evaluate to true:

	  * !eback() || eback() != rhs_a.eback()
	  * !gptr() || gptr() != rhs_a.gptr()
	  * !egptr() || egptr() != rhs_a.egptr()
	  * !pbase() || pbase() != rhs_a.pbase()
	  * !pptr() || pptr() != rhs_a.pptr()
	  * !epptr() || epptr() != rhs_a.epptr()
	15) The copy constructor is deleted; std::basic_stringbuf is  not  Copy-
     Constructible.

Parameters
	s     - a std::basic_string used to initialize the buffer
	t      -  an object (convertible to std::basic_string_view) used to ini-
     tialize the
		buffer
	a     - another  allocator  used  to  construct  the  internal	std::ba-
     sic_string
	rhs   - another basic_stringbuf
		specifies  stream  open  mode. It is bitmask type, the following
     constants are
		defined:

		Constant	  Explanation
		app		  seek to the end of stream before each write
	which - binary		  open in binary mode
		in		  open for reading
		out		  open for writing
		trunc		  discard the contents of the stream when  open-
     ing
		ate		   seek  to  the end of stream immediately after
     open
		noreplace (C++23) open in exclusive mode

Notes
	Typically called by the constructor of std::basic_stringstream.

	The level of support for the open modes other than std::ios_base::in and
	std::ios_base::out varies among implementations. C++11 explicitly speci-
     fies the
	support for std::ios_base::ate in str() and in this constructor, but
	std::ios_base::app, std::ios_base::trunc, and std::ios_base::binary have
     different
	effects on different implementations.

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

Example
	Demonstrates calling the constructor of std::basic_stringbuf directly:

     // Run this code

      #include <iostream>
      #include <sstream>

      int main()
      {
	  // default constructor (mode = in | out)
	  std::stringbuf buf1;
	  buf1.sputc('1');
	  std::cout << &buf1 << '\n';

	  // string constructor in at-end mode (C++11)
	  std::stringbuf buf2("test", std::ios_base::in
				    | std::ios_base::out
				    | std::ios_base::ate);
	  buf2.sputc('1');
	  std::cout << &buf2 << '\n';

	  // append mode test (results differ among compilers)
	  std::stringbuf buf3("test", std::ios_base::in
				    | std::ios_base::out
				    | std::ios_base::app);
	  buf3.sputc('1');
	  buf3.pubseekpos(1);
	  buf3.sputc('2');
	  std::cout << &buf3 << '\n';
      }

Output:
      1
      test1
      est12 (Sun Studio) 2st1 (GCC)

	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
			   1. overload (1) allocated no array  object	 1.  re-
     moved the
	LWG  432  C++98      2. overload (3) did not specify how the	 limita-
     tion
			   input				       2. speci-
     fied
			       and output sequences are initialized
			   overload (3) set epptr() to point one past
	LWG 562 C++98	   the last  underlying 			 epptr()
     can be set
			   character  if  bool(which  & 		  beyond
     that position
			   std::ios_base::out) == true
	P0935R0 C++11	   the default constructor was explicit        made  im-
     plicit

See also
		      constructs the string stream
	constructor   (public member function of
		      std::basic_stringstream<CharT,Traits,Allocator>)

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