1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
/*! \file stringbuf.h
* \brief 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 \0 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.
*/
#ifndef __LIB3195_STRINGBUF_H_INCLUDED__
#define __LIB3195_STRINGBUF_H_INCLUDED__ 1
#define sbSTRBCHECKVALIDOBJECT(x) {assert(x != NULL); assert(x->OID == OIDsbStrB);}
/**
* The dynamic string buffer object.
*
*/
struct sbStrBObject
{
srObjID OID; /**< object ID */
char *pBuf; /**< pointer to the string buffer, may be NULL if string is empty */
int iBufSize; /**< current maximum size of the string buffer */
int iBufPtr; /**< pointer (index) of next character position to be written to. */
int iAllocIncrement; /**< the amount of bytes the string should be expanded if it needs to */
};
typedef struct sbStrBObject sbStrBObj;
/**
* Construct a sbStrB object.
*/
sbStrBObj *sbStrBConstruct(void);
/**
* Destruct the string buffer object.
*/
void sbStrBDestruct(sbStrBObj *pThis);
/**
* Append a character to an existing string. If necessary, the
* method expands the string buffer.
*
* \param c Character to append to string.
*/
srRetVal sbStrBAppendChar(sbStrBObj *pThis, char c);
/**
* 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.
*
* \retval pointer to \0 terminated string. May be NULL
* (empty string) and MUST be free()ed by caller.
*/
char* sbStrBFinish(sbStrBObj *pThis);
/**
* Append a string to the buffer.
*
* \param psz pointer to string to be appended. Must not be NULL.
*/
srRetVal sbStrBAppendStr(sbStrBObj *pThis, char* psz);
/**
* 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.
*
* \param 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 ;)
*/
void sbStrBSetAllocIncrement(sbStrBObj *pThis, int iNewIncrement);
/**
* Append an integer to the string. No special formatting is
* done.
*/
srRetVal sbStrBAppendInt(sbStrBObj *pThis, int i);
#endif
|
