basic_stringbuf man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

basic_stringbuf(3C++)		       -		 basic_stringbuf(3C++)

Standard C++ Library Copyright 1998, Rogue Wave Software, Inc.

NAME
       basic_stringbuf, stringbuf, wstringbuf

	- Associates the input or output sequence with a sequence of arbitrary
       characters.

SYNOPSIS
       #include <sstream>
       template<class charT, class traits = char_traits<charT>,
	class Allocator = allocator<charT> >
class basic_stringbuf
: public basic_streambuf<charT, traits>

DESCRIPTION
       The class basic_stringbuf is derived from basic_streambuf. Its  purpose
       is  to  associate the input or output sequence with a sequence of arbi‐
       trary characters. The sequence can be initialized from, or made	avail‐
       able  as,  an  object  of  class	 basic_string.	Each  object  of  type
       basic_stringbuf<charT,_traits,Allocator>	  controls    two    character
       sequences:

       ·    A character input sequence;

       ·    A character output sequence.

       Note: see basic_streambuf.

       The  two sequences are related to each other, but are manipulated sepa‐
       rately. This allows you to read and write characters at different posi‐
       tions  in  objects  of  type  basic_stringbuf_without  any conflict (as
       opposed to the basic_filebuf_objects, in which a joint file position is
       maintained).

INTERFACE
       template<class charT, class traits = char_traits<charT>,
	class allocator<charT> >
class basic_stringbuf
: public basic_streambuf<charT, traits> {

 public:

  typedef charT			       char_type;
  typedef typename traits::int_type    int_type;
  typedef typename traits::pos_type    pos_type;
  typedef typename traits::off_type    off_type;

  typedef basic_ios<charT, traits>     ios_type;
  typedef basic_string<charT, traits,
		       Allocator>      string_type;

  explicit basic_stringbuf(ios_base::openmode which =
			    (ios_base::in | ios_base::out));

  explicit basic_stringbuf(const string_type& str,
			   ios_base::openmode which =
			    (ios_base::in | ios_base::out));

  virtual ~basic_stringbuf();

  string_type str() const;
  void str(const string_type& str_arg);

protected:

  virtual int_type underflow();
  virtual int_type pbackfail(int_type c = traits::eof());
  virtual int_type overflow(int_type c = traits::eof());
  virtual basic_streambuf<charT,traits>*
   setbuf(char_type *s,streamsize n);

  virtual pos_type seekoff(off_type off,
			   ios_base::seekdir way,
			   ios_base::openmode which =
			   ios_base::in | ios_base::out);

  virtual pos_type seekpos(pos_type sp,
			   ios_base::openmode which =
			   ios_base::in | ios_base::out);

  virtual streamsize xsputn(const char_type* s,
			    streamsize n);

};

TYPES
       char_type

   The type char_type is a synonym for the template parameter charT.

ios_type

   The type ios_type is an instantiation of class basic_ios on type charT.

off_type

   The type off_type is a synonym of type traits::off_type.

pos_type

   The type pos_type is a synonym of type traits::pos_type.

string_type

   The	type  string_type  is  an  instantiation of class basic_string on type
   charT.

stringbuf

   The type stringbuf is an instantiation of  class  basic_stringbuf  on  type
   char:

   typedef basic_stringbuf<char> stringbuf;

traits_type

   The type traits_type is a synonym for the template parameter traits.

wstringbuf

   The	type  wstringbuf  is an instantiation of class basic_stringbuf on type
   wchar_t:

   typedef basic_stringbuf<wchar_t> wstringbuf;

CONSTRUCTORS
       explicit basic_stringbuf(ios_base::openmode which =
	       ios_base::in | ios_base::out);

   Constructs an object of class basic_stringbuf, initializing the base	 class
   with basic_streambuf(), and initializing the open mode with which.

explicit basic_stringbuf(const string_type& str,
	       ios_base::openmode which =
	       ios_base::in | ios_base::out);

   Constructs  an object of class basic_stringbuf, initializing the base class
   with basic_streambuf(), and initializing the	 open  mode  with  which.  The
   string  object  str is copied to the underlying buffer. If the opening mode
   is in, initializes the input sequence to point to the  first	 character  of
   the	buffer. If the opening mode is out, it initializes the output sequence
   to point to the first character of the buffer. If the opening mode is out |
   app,	 it  initializes the output sequence to point to the last character of
   the buffer.

DESTRUCTORS
virtual ~basic_stringbuf();

   Destroys an object of class basic_stringbuf.

MEMBER FUNCTIONS
       int_type
       overflow(int_type c = traits::eof() );

   If the output  sequence  has	 a  put	 position  available,  and  c  is  not
   traits::eof(), then this function writes c into it. If there is no position
   available, the function increases the size of the buffer by allocating more
   memory  and then writes c at the new current put position. If the operation
   fails,  the	function   returns   traits::eof().   Otherwise	  it   returns
   traits::not_eof(c).

int_type
pbackfail( int_type c = traits::eof() );

   Puts	 back  the  character  designated  by  c  into	the input sequence. If
   traits::eq_int_type(c,traits::eof()) returns true, the function  moves  the
   input  sequence one position backward. If the operation fails, the function
   returns traits::eof(). Otherwise it returns traits::not_eof(c).

pos_type
seekoff(off_type off, ios_base::seekdir way,
       ios_base::openmode which =
       ios_base::in | ios_base::out);

   If the open mode is in | out, this function alters the stream  position  of
   both	 the input and the output sequences. If the open mode is in, it alters
   the stream position of only the input sequence, and if it is out, it alters
   the	stream position of the output sequence. The new position is calculated
   by combining the two	 parameters  off  (displacement)  and  way  (reference
   point).  If	the current position of the sequence is invalid before reposi‐
   tioning,   the    operation	  fails	   and	  the	 return	   value    is
   pos_type(off_type(-1)).  Otherwise  the  function  returns  the current new
   position.

pos_type
seekpos(pos_type sp,ios_base::openmode which =
       ios_base::in | ios_base::out);

   If the open mode is in | out, seekpos() alters the stream position of  both
   the	input  and the output sequences. If the open mode is in, it alters the
   stream position of the input sequence only, and if the open mode is out, it
   alters  the	stream	position  of  the output sequence only. If the current
   position of the sequence is invalid	before	repositioning,	the  operation
   fails  and  the return value is pos_type(off_type(-1)). Otherwise the func‐
   tion returns the current new position.

basic_streambuf<;charT,traits>*
setbuf(char_type*s, streamsize n);

   A stringbuf maintains an underlying character array	for  storing  buffered
   characters.	 This  function gives you a way to resize or replace that buf‐
   fer, with certain restrictions.

   First of all, n must be greater than the number of characters currently  in
   the	buffer.	  If  n	 is too small, then setbuf has no effect and returns a
   null pointer to indicate failure.

   If n is large enough, then this function has one of two effects:

	-    If s is not a null pointer, then setbuf copies the buffered  con‐
	     tents  of	the stringbuf into the n character array starting at s
	     and installs s as the underlying  character  array	 used  by  the
	     stringbuf.	  s  replaces the old underlying array.	 In this case,
	     the function returns s on success or a null pointer  to  indicate
	     failure.

	     Note that the stringbuf now owns s and deletes it if a subsequent
	     call to setbuf replaces it or, failing that, when	the  stringbuf
	     is	 destroyed.   A	 program  should  not  itself delete a pointer
	     passed to setbuf if the call succeeds.   And  s  must  have  been
	     allocated from the heap using new.

	-    If	 s is a null pointer, then setbuf resizes the underlying char‐
	     acter array to n characters.  The function returns a  pointer  to
	     the  beginning  of the resized array if the operation is success‐
	     ful, or a null pointer if not.

string_type
str() const;

   Returns a string object of type string_type whose content is a copy of  the
   underlying buffer contents.

void
str(const string_type& str_arg);

   Clears  the underlying buffer and copies the string object str_arg into it.
   If the opening mode is in, initializes the input sequence to point  to  the
   first  character  of	 the  buffer. If the opening mode is out, the function
   initializes the output sequence to point to the first character of the buf‐
   fer.	 If  the opening mode is out | app, it initializes the output sequence
   to point to the last character of the buffer.

int_type
underflow();

   If the input sequence has a read position available, the  function  returns
   the	contents  of  this  position.  Otherwise  it tries to expand the input
   sequence to match the output sequence, and if possible returns the  content
   of the new current position. The function returns traits::eof() to indicate
   failure.

streamsize
xsputn(const char_type* s, streamsize n);

   Writes up to n characters to the output sequence.  The  characters  written
   are	obtained  from successive elements of the array whose first element is
   designated by s. The function returns the number of characters written.

EXAMPLE
       // stdlib/examples/manual/stringbuf.cpp
       //
       #include<iostream>
       #include<sstream>
       #include<string>

       void main ( )
       {
 using namespace std;

  // create a read/write string-stream object on tiny char
  // and attach it to an ostringstream object
 ostringstream out_1(ios_base::in | ios_base::out);

  // tie the istream object to the ostringstream object
 istream in_1(out_1.rdbuf());

  // output to out_1
 out_1 << "Here is the first output";

  // create a string object on tiny char
 string string_ex("l'heure est grave !");

  // open a read only string-stream object on tiny char
  // and initialize it
 istringstream in_2(string_ex);

  // output in_1 to the standard output
 cout << in_1.str() << endl;

  // output in_2 to the standard output
 cout << in_2.rdbuf() << endl;

  // reposition in_2 at the beginning
 in_2.seekg(0);

 stringbuf::pos_type pos;

  // get the current put position
  // equivalent to
  // out_1.tellp();
 pos = out_1.rdbuf()->pubseekoff(0,ios_base::cur,
				 ios_base::out);

  // append the content of stringbuffer
  // pointed to by in_2 to the one
  // pointed to by out_1
 out_1 << ' ' << in_2.rdbuf();

  // output in_1 to the standard output
 cout << in_1.str() << endl;

  // position the get sequence
  // equivalent to
  // in_1.seekg(pos);
 in_1.rdbuf()->pubseekpos(pos, ios_base::in);

  // output "l'heure est grave !"
 cout << in_1.rdbuf() << endl << endl;
}

SEE ALSO
       char_traits(3C++),   ios_base(3C++),   basic_ios(3C++),	 basic_stream‐
       buf(3C++),	 basic_string(3C++),	    basic_istringstream(3C++),
       basic_ostringstream(3C++), basic_stringstream(3C++)

       Working Paper for Draft Proposed International Standard for Information
       Systems--Programming Language C++, Section 27.7.1

STANDARDS CONFORMANCE
       ANSI X3J16/ISO WG21 Joint C++ Committee

Rogue Wave Software		  02 Apr 1998		 basic_stringbuf(3C++)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net