1 /*! \file stringbuf.h 2 * \brief The dynamic stringt buffer helper object. 3 * 4 * The string buffer object is a slim string handler. It implements 5 * a dynamically growing string and can be used whereever data needs 6 * to be appended to a string AND it is not known how large the 7 * resulting structure is. If you know the string size or can 8 * retrieve it quickly, you should NOT use the string buffer 9 * object - because it has some overhead not associated with direct 10 * string manipulations. 11 * 12 * This object is used to grow a string. For performance reasons, 13 * the termination \0 byte is only written after the caller 14 * indicates the string is completed. 15 * 16 * \author Rainer Gerhards <rgerhards@adiscon.com> 17 * \date 2003-08-08 18 * Initial version begun. 19 * 20 * Copyright 2002-2014 21 * Rainer Gerhards and Adiscon GmbH. All Rights Reserved. 22 * 23 * Redistribution and use in source and binary forms, with or without 24 * modification, are permitted provided that the following conditions are 25 * met: 26 * 27 * * Redistributions of source code must retain the above copyright 28 * notice, this list of conditions and the following disclaimer. 29 * 30 * * Redistributions in binary form must reproduce the above copyright 31 * notice, this list of conditions and the following disclaimer in 32 * the documentation and/or other materials provided with the 33 * distribution. 34 * 35 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 36 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 37 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 38 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 39 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 40 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 41 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 42 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 43 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 44 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 45 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 46 */ 47 #ifndef __LIB3195_STRINGBUF_H_INCLUDED__ 48 #define __LIB3195_STRINGBUF_H_INCLUDED__ 1 49 50 #define sbSTRBCHECKVALIDOBJECT(x) {assert(x != NULL); assert(x->OID == OIDsbStrB);} 51 52 53 /** 54 * The dynamic string buffer object. 55 * 56 */ 57 struct sbStrBObject 58 { 59 srObjID OID; /**< object ID */ 60 char *pBuf; /**< pointer to the string buffer, may be NULL if string is empty */ 61 int iBufSize; /**< current maximum size of the string buffer */ 62 int iBufPtr; /**< pointer (index) of next character position to be written to. */ 63 int iAllocIncrement; /**< the amount of bytes the string should be expanded if it needs to */ 64 }; 65 typedef struct sbStrBObject sbStrBObj; 66 67 68 /** 69 * Construct a sbStrB object. 70 */ 71 sbStrBObj *sbStrBConstruct(void); 72 73 /** 74 * Destruct the string buffer object. 75 */ 76 void sbStrBDestruct(sbStrBObj *pThis); 77 78 /** 79 * Append a character to an existing string. If necessary, the 80 * method expands the string buffer. 81 * 82 * \param c Character to append to string. 83 */ 84 srRetVal sbStrBAppendChar(sbStrBObj *pThis, char c); 85 86 /** 87 * Finish the string buffer. That means, the string 88 * is returned to the caller and then the string 89 * buffer is destroyed. The caller is reponsible for 90 * freeing the returned string pointer. 91 * 92 * After calling this method, the string buffer object 93 * is destroyed and thus the provided handle (pThis) 94 * can no longer be used. 95 * 96 * \retval pointer to \0 terminated string. May be NULL 97 * (empty string) and MUST be free()ed by caller. 98 */ 99 char* sbStrBFinish(sbStrBObj *pThis); 100 101 /** 102 * Append a string to the buffer. 103 * 104 * \param psz pointer to string to be appended. Must not be NULL. 105 */ 106 srRetVal sbStrBAppendStr(sbStrBObj *pThis, char* psz); 107 108 /** 109 * Set a new allocation incremet. This will influence 110 * the allocation the next time the string will be expanded. 111 * It can be set and changed at any time. If done immediately 112 * after custructing the StrB object, this will also be 113 * the inital allocation. 114 * 115 * \param iNewIncrement The new increment size 116 * 117 * \note It is possible to use a very low increment, e.g. 1 byte. 118 * This can generate a considerable overhead. We highly 119 * advise not to use an increment below 32 bytes, except 120 * if you are very well aware why you are doing it ;) 121 */ 122 void sbStrBSetAllocIncrement(sbStrBObj *pThis, int iNewIncrement); 123 124 /** 125 * Append an integer to the string. No special formatting is 126 * done. 127 */ 128 srRetVal sbStrBAppendInt(sbStrBObj *pThis, int i); 129 130 131 #endif 132