[ новости /+++ | форум | теги | ]

NAME
     ssbuf - buffer class for for character arrays

SYNOPSIS
     #include <strstream.h> // includes <iostream.h>
     class strstreambuf : public streambuf {
     public:
               strstreambuf();
               strstreambuf(int n);
               strstreambuf(void* (*a)(long), void (*f)(void*));
               strstreambuf(char* _s, int, char* _strt=0);
               ~strstreambuf();

          void    freeze_unlocked(int = 1);
          void    freeze(int = 1);
          char*   str_unlocked();
          char*   str();
     virtual int     doallocate();
     virtual int     overflow(int);
     virtual int     underflow();
     virtual streambuf* setbuf(char*, int);
     virtual streampos seekoff(streamoff, unsafe_ios::seek_dir, int);
     };

DESCRIPTION
     The strstreambuf class is  a  specialization  of  streambufs
     using  a char array (string) as the source or destination of
     characters.  Characters are fetched (input) from  the  array
     and consumed by (written to) the array.  The basic streambuf
     operations  are   as   described   in   sbufprot(3C++)   and
     sbufpub(3C++).   The  get  and  put  pointers point into the
     attached  array,  and  moving  the  get   or   put   pointer
     corresponds to incrementing or decrementing a char*.

     To make streambuf multi-threaded safe (MT  safe),  that  is,
     able  to  work  correctly  in  a multi-threaded environment,
     locks have been used in  each  public  member  function.  An
     alternative set of public member functions without locks has
     been introduced for  use  in  single  threaded  applications
     where  performance is critical. These member functions share
     the same name as the original function with the addition  of
     the  suffix:  _unlocked.  Other  than  being  MT unsafe, the
     member functions have  identical  functionality.   For  more
     information,  see  the  C++  4.1  Library  Reference Manual,
     Chapter 5, "Using libC in a Multithreaded Environment."

     A strstreambuf may be used in one of two modes:  dynamic  or
     static.   In  dynamic mode, the array is automatically allo-
     cated and expanded as needed to accomodate  strings  of  any
     length.   When  more  space is needed, a new reserve area is
     allocated and the data from the old array is copied  to  it;
     the  old  array  is  then  deleted.  In static mode, a user-
     supplied fixed array is  used,  which  cannot  be  moved  or
     changed  to a new buffer; it will never be deleted automati-
     cally.  A dynamic strstreambuf may be frozen, that is,  made
     non-expandable.  A frozen or static strstreambuf may be con-
     verted to a char* for use in expressions which need  C-style
     strings.   A  frozen  dynamic  strstreambuf may be unfrozen:
     made expandable again.

  Constructors
     strstreambuf()
          Constructs an empty,  dynamic,  unfrozen  strstreambuf.
          Space for the string will be allocated automatically as
          needed.  If you know that some minimum number of  char-
          acters  will  be inserted, you should either create the
          buffer with the strstream(int) constructor or use  set-
          buf()  (see  below),  to  avoid repeated allocation and
          deallocation of small arrays.

     strstreambuf(n)
          Constructs an empty,  dynamic,  unfrozen  strstreambuf,
          with an initial buffer size of at least n bytes.

     strstreambuf(alloc, del)
          Constructs an empty,  dynamic,  unfrozen  strstreambuf.
          Space for the string will be allocated automatically as
          needed.  Rather than using new and delete, the supplied
          functions alloc and del will be called.  Function alloc
          must take a long parameter,  the  number  of  bytes  to
          allocate;  it  must  return  a pointer to the allocated
          space (of type void*), or zero on failure.  If alloc is
          null,  new  will  be  used.   Function  del must take a
          parameter of type void*, which will be a pointer  value
          acquired  from  alloc; its return type is void.  If del
          is null, delete will be used.  You must take care  when
          using  this constructor that alloc and del are compati-
          ble.

     strstreambuf(ptr, len, putp)
          Constructs  a  static  strstreambuf  using  the  buffer
          pointed  to  by  ptr.   If  len is positive and putp is
          null, len bytes starting at ptr are used.  If  putp  is
          not null, len is ignored, and the initial get area will
          run from ptr to putp.  If len is zero, ptr  is  assumed
          to  point  to a null-terminated string, and the area up
          to but not including the null byte will be used for the
          buffer.   If  len is negative, the buffer is assumed to
          be of unlimited length;  quite  obviously,  this  is  a
          potentially  dangerous  mode.   The get pointer will be
          initially set to ptr.  The put  pointer  will  be  ini-
          tially  set  to  putp.  If putp is null, stores will be
          treated as errors.  Examples:
          strstreambuf greeting("Hello, world!", 0, 0);
               Creates a buffer consisting of the supplied  text.
               The data may not be over-written or expanded.
          char *hi = "Hello, world!";
          strstreambuf greeting(hi, 0, hi+7);
               Creates a buffer consisting of the supplied  text.
               The data may be over-written from `w' through `!',
               but not expanded.
          char *hi = "Hello, world!";
          strstreambuf greeting(hi, 5, hi);
               Creates a buffer consisting of the supplied  text.
               The  "Hello"  portion  of  the data may be read or
               overwritten;  the  remainder  of  the  buffer   is
               inaccesable.

  Member functions
     ssbuf.freeze(i)
          If i is non-zero, freezes the dynamic buffer; if  zero,
          it  unfreezes  the buffer.  Freezing prevents automatic
          deletion of the buffer, even when the  strstreambuf  is
          destroyed.   It  also  prevents expansion of the buffer
          beyond its current size.  You would want  to  freeze  a
          buffer  to  permit taking a pointer to it which remains
          reliable until the buffer is explicitly unfrozen.  Once
          unfrozen,   a   dynamic  buffer  may  be  automatically
          expanded and deleted.  Freezing  is  irrelevant  for  a
          static buffer, since it is never automatically expanded
          or  deleted.  Freezing  does  not  null-terminate   the
          buffer.

     char* p = ssbuf.str()
          Freezes ssbuf and returns a pointer to the beginning of
          the buffer.  If ssbuf is in dynamic mode but the buffer
          is empty, the returned pointer might be null.

     streambuf* sbp = ssbuf.setbuf(ptr, len)
          If ptr is not null, the request is ignored; it  is  not
          possible to replace the buffer of any static or dynamic
          strstreambuf.  If ptr is null,  the  value  of  len  is
          saved,  and the next dynamic mode allocation will be at
          least len bytes.  (This applies only to the next  allo-
          cation; the value of len is then discarded.)  You would
          want to use this function to  force  a  suitably  large
          allocation  when  a  buffer  was  going to be expanded,
          avoiding potentially many small allocation and  deallo-
          cation sequences.

SEE ALSO
     ios.intro(3C++), ios(3C++), sbufprot(3C++), sbufpub(3C++),
     strstream(3C++),

     C++ 4.1 Library Reference Manual:

             Chapter 4, "The Iostream Library",

             Chapter 5, "Using libC in a Multithreaded Environment."

Партнёры:

Хостинг: