.\" to invoke 'tbl', 'eqn', 'pic' in the proper order .\" '\" tep .\" .\" @(#)ssbuf.3 1.2 92/12/01 SMI; .\" .TH SSBUF 3CC4 "18 June 1998" .\" .SH NAME ssbuf \- buffer class for for character arrays .SH SYNOPSIS .LP .nf .ft B #include \fI// includes \fB .sp .5v 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); }; .ft R .fi .\" .SH DESCRIPTION .LP The \fBstrstreambuf\fR class is a specialization of \fBstreambuf\fRs using a \fBchar\fR 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 \fBstreambuf\fR operations are as described in .BR sbufprot "(3CC4) and" .BR sbufpub (3CC4). The get and put pointers point into the attached array, and moving the get or put pointer corresponds to incrementing or decrementing a \fBchar*\fR. .LP 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 .IR "C++ 4.1 Library Reference Manual, Chapter 5, "Using \fIlibC\fR in a Multithreaded Environment." .LP A .B strstreambuf may be used in one of two modes: \fIdynamic\fR or \fIstatic\fR. In dynamic mode, the array is automatically allocated 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 automatically. A dynamic \fBstrstreambuf\fR may be \fIfrozen\fR, that is, made non-expandable. A frozen or static \fBstrstreambuf\fR may be converted to a \fBchar*\fR for use in expressions which need C-style strings. A frozen dynamic \fBstrstreambuf\fR may be \fIunfrozen\fR: made expandable again. .\" .SS "Constructors" .TP .B "strstreambuf()" Constructs an empty, dynamic, unfrozen \fBstrstreambuf\fR. Space for the string will be allocated automatically as needed. If you know that some minimum number of characters will be inserted, you should either create the buffer with the \fBstrstream(int)\fR constructor or use \fBsetbuf()\fR (see below), to avoid repeated allocation and deallocation of small arrays. .TP .B "strstreambuf(n)" Constructs an empty, dynamic, unfrozen \fBstrstreambuf\fR, with an initial buffer size of at least \fBn\fR bytes. .TP .B "strstreambuf(alloc, del)" Constructs an empty, dynamic, unfrozen \fBstrstreambuf\fR. Space for the string will be allocated automatically as needed. Rather than using \fBnew\fR and \fBdelete\fR, the supplied functions \fBalloc\fR and \fBdel\fR will be called. Function \fBalloc\fR must take a \fBlong\fR parameter, the number of bytes to allocate; it must return a pointer to the allocated space (of type \fBvoid*\fR), or zero on failure. If \fBalloc\fR is null, \fBnew\fR will be used. Function \fBdel\fR must take a parameter of type \fBvoid*\fR, which will be a pointer value acquired from \fBalloc\fR; its return type is \fBvoid\fR. If \fBdel\fR is null, \fBdelete\fR will be used. You must take care when using this constructor that \fBalloc\fR and \fBdel\fR are compatible. .TP .B "strstreambuf(ptr, len, putp)" Constructs a static \fBstrstreambuf\fR using the buffer pointed to by \fBptr\fR. If \fBlen\fR is positive and \fBputp\fR is null, \fBlen\fR bytes starting at \fBptr\fR are used. If \fBputp\fR is not null, \fBlen\fR is ignored, and the initial get area will run from \fBptr\fR to \fBputp\fR. If \fBlen\fR is zero, \fBptr\fR 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 \fBlen\fR 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 \fBptr\fR. The put pointer will be initially set to \fBputp\fR. If \fBputp\fR is null, stores will be treated as errors. Examples: .in +.5i .ti -.5i \fBstrstreambuf greeting("Hello, world!", 0, 0);\fR .br Creates a buffer consisting of the supplied text. The data may not be over-written or expanded. .ti -.5i \fBchar *hi = "Hello, world!";\fR .ti -.5i \fBstrstreambuf greeting(hi, 0, hi+7);\fR .br Creates a buffer consisting of the supplied text. The data may be over-written from `w' through `!', but not expanded. .ti -.5i \fBchar *hi = "Hello, world!";\fR .ti -.5i \fBstrstreambuf greeting(hi, 5, hi);\fR .br 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. .in +.5i .\" .SS "Member functions" .TP .B "ssbuf.freeze(i)" If \fBi\fR is non-zero, freezes the dynamic buffer; if zero, it unfreezes the buffer. Freezing prevents automatic deletion of the buffer, even when the \fBstrstreambuf\fR 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. .TP .B "char* p = ssbuf.str()" Freezes \fBssbuf\fR and returns a pointer to the beginning of the buffer. If \fBssbuf\fR is in dynamic mode but the buffer is empty, the returned pointer might be null. .TP .B "streambuf* sbp = ssbuf.setbuf(ptr, len)" If \fBptr\fR is not null, the request is ignored; it is not possible to replace the buffer of any static or dynamic \fBstrstreambuf\fR. If \fBptr\fR is null, the value of \fBlen\fR is saved, and the next dynamic mode allocation will be at least \fBlen\fR bytes. (This applies only to the next allocation; the value of \fBlen\fR 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 deallocation sequences. .\" .SH "SEE ALSO" .LP .na .BR ios.intro (3CC4), .BR ios (3CC4), .BR sbufprot (3CC4), .BR sbufpub (3CC4), .BR strstream (3CC4), .TP .I C++ Library Reference .TP Chapter 3, "The Classic \fIiostream\fR Library", .TP Chapter 4, "Using Classic \fIiostream\fR in a Multithreaded Environment." .\" .TZ ????