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

NAME
     std::basic_streambuf - std::basic_streambuf

Synopsis
	Defined in header <streambuf>
	template<

	    class CharT,
	    class Traits = std::char_traits<CharT>

	> class basic_streambuf;

	The  class  basic_streambuf controls input and output to a character se-
     quence. It
	includes and provides access to

	 1. The controlled character sequence, also called the buffer, which may
     contain
	    input sequence (also called get area) for buffering the input opera-
     tions and/or
	    output sequence (also called put area) for buffering the output  op-
     erations.
	 2. The associated character sequence, also called source (for input) or
     sink (for
	    output).  This  may  be  an  entity  that is accessed through OS API
     (file, TCP
	    socket, serial port, other character device), or it may be an object
	    (std::vector, array, string literal), that can be interpreted  as  a
     character
	    source or sink.

	The  I/O  stream  objects  std::basic_istream and std::basic_ostream, as
     well as all
	objects derived from them (std::ofstream, std::stringstream,  etc),  are
     implemented
	entirely in terms of std::basic_streambuf.

	The  controlled  character  sequence  is an array of CharT which, at all
     times,
	represents a subsequence, or a "window" into  the  associated  character
     sequence. Its
	state is described by three pointers:

	 1.  The  beginning  pointer, always points at the lowest element of the
     buffer.
	 2. The next pointer, points at the element that is the  next  candidate
     for reading
	    or writing.
	 3. The end pointer, points one past the end of the buffer.

	A basic_streambuf object may support input (in which case the buffer de-
     scribed by
	the  beginning,  next, and end pointers is called get area), output (put
     area), or
	input and output  simultaneously.  In  latter  case,  six  pointers  are
     tracked, which may
	all  point to elements of the same character array or two individual ar-
     rays.

	If the next pointer is less than the end pointer  in  the  put	area,  a
     write position
	is available. The next pointer can be dereferenced and assigned to.

	If the next pointer is less than the end pointer in the get area, a read
     position is
	available. The next pointer can be dereferenced and read from.

	If the next pointer is greater than the beginning pointer in a get area,
     a putback
	position is available, and the next pointer may be decremented, derefer-
     enced, and
	assigned to, in order to put a character back into the get area.

	The character representation and encoding in the controlled sequence may
     be
	different from the character representations in the associated sequence,
     in which
	case  a  std::codecvt locale facet is typically used to perform the con-
     version. Common
	examples are UTF-8 (or other multibyte) files accessed through	std::wf-
     stream
	objects: the controlled sequence consists of wchar_t characters, but the
     associated
	sequence consists of bytes.

	Typical implementation of the std::basic_streambuf base class holds only
     the six
	CharT* pointers and a copy of std::locale as data members. In addition,
	implementations  may  keep cached copies of locale facets, which are in-
     validated
	whenever imbue() is  called.  The  concrete  buffers  such  as	std::ba-
     sic_filebuf or
	std::basic_stringbuf are derived from std::basic_streambuf.

	std-streambuf.svg

	Several typedefs for common character types are provided:

	Defined in header <streambuf>
	Type		Definition
	std::streambuf	std::basic_streambuf<char>
	std::wstreambuf std::basic_streambuf<wchar_t>

Member types
	Member type Definition
	char_type   CharT
	traits_type  Traits;  the  program is ill-formed if Traits::char_type is
     not
		    CharT.
	int_type    Traits::int_type
	pos_type    Traits::pos_type
	off_type    Traits::off_type

Member functions
	destructor	   destructs the basic_streambuf object
	[virtual]	   (virtual public member function)

Locales
	pubimbue	   invokes imbue()
			   (public member function)
	getloc		   obtains a copy of the associated locale
			   (public member function)

Positioning
	pubsetbuf	   invokes setbuf()
			   (public member function)
	pubseekoff	   invokes seekoff()
			   (public member function)
	pubseekpos	   invokes seekpos()
			   (public member function)
	pubsync 	   invokes sync()
			   (public member function)

Get area
			   obtains the number of characters  immediately  avail-
     able in the get
	in_avail	   area
			   (public member function)
			   advances the input sequence, then reads one character
     without
	snextc		   advancing again
			   (public member function)
	sbumpc		    reads  one character from the input sequence and ad-
     vances the
	stossc		   sequence
	(removed in C++17) (public member function)
			   reads one character from the input  sequence  without
     advancing the
	sgetc		   sequence
			   (public member function)
	sgetn		   invokes xsgetn()
			   (public member function)

Put area
			   writes one character to the put area and advances the
     next
	sputc		   pointer
			   (public member function)
	sputn		   invokes xsputn()
			   (public member function)

Putback
	sputbackc	   puts one character back in the input sequence
			   (public member function)
	sungetc 	    moves the next pointer in the input sequence back by
     one
			   (public member function)

Protected member functions
	constructor	   constructs a basic_streambuf object
			   (protected member function)
	operator=	   replaces a basic_streambuf object
	(C++11) 	   (protected member function)
	swap		   swaps two basic_streambuf objects
	(C++11) 	   (protected member function)

Locales
	imbue		   changes the associated locale
	[virtual]	   (virtual protected member function)

Positioning
	setbuf		   replaces the buffer with user-defined array, if  per-
     mitted
	[virtual]	   (virtual protected member function)
	seekoff 	    repositions  the next pointer in the input sequence,
     output
	[virtual]	   sequence, or both, using relative addressing
			   (virtual protected member function)
	seekpos 	   repositions the next pointer in the	input  sequence,
     output
	[virtual]	   sequence, or both using absolute addressing
			   (virtual protected member function)
	sync		    synchronizes the buffers with the associated charac-
     ter sequence
	[virtual]	   (virtual protected member function)

Get area
	showmanyc	   obtains the number of characters available for  input
     in the
	[virtual]	   associated input sequence, if known
			   (virtual protected member function)
	underflow	    reads  characters from the associated input sequence
     to the get
	[virtual]	   area
			   (virtual protected member function)
	uflow		   reads characters from the associated  input	sequence
     to the get
	[virtual]	   area and advances the next pointer
			   (virtual protected member function)
	xsgetn		   reads multiple characters from the input sequence
	[virtual]	   (virtual protected member function)
	eback		   returns a pointer to the beginning, current character
     and the end
	gptr		   of the get area
	egptr		   (protected member function)
	gbump		   advances the next pointer in the input sequence
			   (protected member function)
			   repositions	the beginning, next, and end pointers of
     the input
	setg		   sequence
			   (protected member function)

Put area
	xsputn		   writes multiple characters to the output sequence
	[virtual]	   (virtual protected member function)
	overflow	   writes characters to the associated	output	sequence
     from the put
	[virtual]	   area
			   (virtual protected member function)
	pbase		   returns a pointer to the beginning, current character
     and the end
	pptr		   of the put area
	epptr		   (protected member function)
	pbump		   advances the next pointer of the output sequence
			   (protected member function)
			   repositions	the beginning, next, and end pointers of
     the output
	setp		   sequence
			   (protected member function)

Putback
	pbackfail	   puts a character back into the input sequence, possi-
     bly modifying
	[virtual]	   the input sequence
			   (virtual protected member function)

See also
	     object type, capable of holding all information needed to control a
     C I/O
	FILE stream
	     (typedef)

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