stringbuf.h File Reference

The dynamic stringt buffer helper object. More...

Go to the source code of this file.

Compounds
struct	sbStrBObject
	The dynamic string buffer object. More...
Defines
#define	__LIB3195_STRINGBUF_H_INCLUDED__   1
#define	sbSTRBCHECKVALIDOBJECT(x)   {assert(x != NULL); assert(x->OID == OIDsbStrB);}
Typedefs
typedef sbStrBObject	sbStrBObj
Functions
sbStrBObj *	sbStrBConstruct (void)
	Construct a sbStrB object.
void	sbStrBDestruct (sbStrBObj *pThis)
	Destruct the string buffer object.
srRetVal	sbStrBAppendChar (sbStrBObj *pThis, char c)
	Append a character to an existing string.
char *	sbStrBFinish (sbStrBObj *pThis)
	Finish the string buffer.
srRetVal	sbStrBAppendStr (sbStrBObj *pThis, char *psz)
	Append a string to the buffer.
void	sbStrBSetAllocIncrement (sbStrBObj *pThis, int iNewIncrement)
	Set a new allocation incremet.
srRetVal	sbStrBAppendInt (sbStrBObj *pThis, int i)
	Append an integer to the string.

---

Detailed Description

The dynamic stringt buffer helper object.

The string buffer object is a slim string handler. It implements a dynamically growing string and can be used whereever data needs to be appended to a string AND it is not known how large the resulting structure is. If you know the string size or can retrieve it quickly, you should NOT use the string buffer object - because it has some overhead not associated with direct string manipulations.

This object is used to grow a string. For performance reasons, the termination byte is only written after the caller indicates the string is completed.

Author:

Rainer Gerhards <rgerhards@adiscon.com>

Date:

2003-08-08 Initial version begun.

Copyright 2002-2003 Rainer Gerhards and Adiscon GmbH. All Rights Reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of Adiscon GmbH or Rainer Gerhards nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---

Function Documentation

srRetVal sbStrBAppendChar (  sbStrBObj *  pThis, char  c )

Append a character to an existing string. If necessary, the method expands the string buffer. Parameters: c  Character to append to string.

srRetVal sbStrBAppendInt (  sbStrBObj *  pThis, int  i )

Append an integer to the string. No special formatting is done.

srRetVal sbStrBAppendStr (  sbStrBObj *  pThis, char *  psz )

Append a string to the buffer. Parameters: psz  pointer to string to be appended. Must not be NULL.

char* sbStrBFinish (  sbStrBObj *  pThis  )

Finish the string buffer. That means, the string is returned to the caller and then the string buffer is destroyed. The caller is reponsible for freeing the returned string pointer. After calling this method, the string buffer object is destroyed and thus the provided handle (pThis) can no longer be used. Return values: pointer  to terminated string. May be NULL (empty string) and MUST be free()ed by caller.

void sbStrBSetAllocIncrement (  sbStrBObj *  pThis, int  iNewIncrement )

Set a new allocation incremet. This will influence the allocation the next time the string will be expanded. It can be set and changed at any time. If done immediately after custructing the StrB object, this will also be the inital allocation. Parameters: iNewIncrement  The new increment size Note: It is possible to use a very low increment, e.g. 1 byte. This can generate a considerable overhead. We highly advise not to use an increment below 32 bytes, except if you are very well aware why you are doing it ;)

---