git.sur5r.net Git - cc65/blob - src/common/strbuf.h

   1 /*****************************************************************************/
   2 /*                                                                           */
   3 /*                                 strbuf.h                                  */
   4 /*                                                                           */
   5 /*                       Variable sized string buffers                       */
   6 /*                                                                           */
   7 /*                                                                           */
   8 /*                                                                           */
   9 /* (C) 2001-2004 Ullrich von Bassewitz                                       */
  10 /*               Römerstrasse 52                                             */
  11 /*               D-70794 Filderstadt                                         */
  12 /* EMail:        uz@cc65.org                                                 */
  13 /*                                                                           */
  14 /*                                                                           */
  15 /* This software is provided 'as-is', without any expressed or implied       */
  16 /* warranty.  In no event will the authors be held liable for any damages    */
  17 /* arising from the use of this software.                                    */
  18 /*                                                                           */
  19 /* Permission is granted to anyone to use this software for any purpose,     */
  20 /* including commercial applications, and to alter it and redistribute it    */
  21 /* freely, subject to the following restrictions:                            */
  22 /*                                                                           */
  23 /* 1. The origin of this software must not be misrepresented; you must not   */
  24 /*    claim that you wrote the original software. If you use this software   */
  25 /*    in a product, an acknowledgment in the product documentation would be  */
  26 /*    appreciated but is not required.                                       */
  27 /* 2. Altered source versions must be plainly marked as such, and must not   */
  28 /*    be misrepresented as being the original software.                      */
  29 /* 3. This notice may not be removed or altered from any source              */
  30 /*    distribution.                                                          */
  31 /*                                                                           */
  32 /*****************************************************************************/
  33
  34
  35
  36 #ifndef STRBUF_H
  37 #define STRBUF_H
  38
  39
  40
  41 #include <stdarg.h>
  42 #include <string.h>
  43
  44 /* common */
  45 #include "attrib.h"
  46 #include "check.h"
  47 #include "inline.h"
  48
  49
  50
  51 /*****************************************************************************/
  52 /*                                   Data                                    */
  53 /*****************************************************************************/
  54
  55
  56
  57 typedef struct StrBuf StrBuf;
  58 struct StrBuf {
  59     unsigned    Allocated;              /* Size of allocated memory */
  60     unsigned    Len;                    /* Length of the string */
  61     unsigned    Index;                  /* Used for reading (Get and friends) */
  62     char*       Buf;                    /* Pointer to buffer */
  63 };
  64
  65 /* An empty string buf */
  66 extern const StrBuf EmptyStrBuf;
  67
  68 /* Initializer for static string bufs */
  69 #define STATIC_STRBUF_INITIALIZER       { 0, 0, 0, 0 }
  70
  71 /* Initializer for auto string bufs */
  72 #define AUTO_STRBUF_INITIALIZER         EmptyStrBuf
  73
  74
  75
  76 /*****************************************************************************/
  77 /*                                   Code                                    */
  78 /*****************************************************************************/
  79
  80
  81
  82 StrBuf* InitStrBuf (StrBuf* B);
  83 /* Initialize a string buffer */
  84
  85 void DoneStrBuf (StrBuf* B);
  86 /* Free the data of a string buffer (but not the struct itself) */
  87
  88 StrBuf* NewStrBuf (void);
  89 /* Allocate, initialize and return a new StrBuf */
  90
  91 void FreeStrBuf (StrBuf* B);
  92 /* Free a string buffer */
  93
  94 void SB_Realloc (StrBuf* B, unsigned NewSize);
  95 /* Reallocate the string buffer space, make sure at least NewSize bytes are
  96  * available.
  97  */
  98
  99 #if defined(HAVE_INLINE)
 100 INLINE unsigned SB_GetLen (const StrBuf* B)
 101 /* Return the length of the buffer contents */
 102 {
 103     return B->Len;
 104 }
 105 #else
 106 #  define SB_GetLen(B)  (B)->Len
 107 #endif
 108
 109 #if defined(HAVE_INLINE)
 110 INLINE unsigned SB_GetIndex (const StrBuf* B)
 111 /* Return the user index of the string buffer */
 112 {
 113     return B->Index;
 114 }
 115 #else
 116 #  define SB_GetIndex(B)  (B)->Index
 117 #endif
 118
 119 #if defined(HAVE_INLINE)
 120 INLINE const char* SB_GetConstBuf (const StrBuf* B)
 121 /* Return a buffer pointer */
 122 {
 123     return B->Buf;
 124 }
 125 #else
 126 #  define SB_GetConstBuf(B)     (B)->Buf
 127 #endif
 128
 129 #if defined(HAVE_INLINE)
 130 INLINE char* SB_GetBuf (StrBuf* B)
 131 /* Return a buffer pointer */
 132 {
 133     return B->Buf;
 134 }
 135 #else
 136 #  define SB_GetBuf(B)     (B)->Buf
 137 #endif
 138
 139 #if defined(HAVE_INLINE)
 140 INLINE char SB_At (const StrBuf* B, unsigned Index)
 141 /* Get a character from the buffer */
 142 {
 143     PRECONDITION (Index < B->Len);
 144     return B->Buf[Index];
 145 }
 146 #else
 147 char SB_At (const StrBuf* B, unsigned Index);
 148 /* Get a character from the buffer */
 149 #endif
 150
 151 #if defined(HAVE_INLINE)
 152 INLINE char SB_AtUnchecked (const StrBuf* B, unsigned Index)
 153 /* Get a character from the buffer */
 154 {
 155     return B->Buf[Index];
 156 }
 157 #else
 158 #  define SB_AtUnchecked(B, Index)      ((B)->Buf[Index])
 159 #endif
 160
 161 #if defined(HAVE_INLINE)
 162 INLINE int SB_IsEmpty (const StrBuf* B)
 163 /* Return true if the string buffer is empty */
 164 {
 165     return (B->Len == 0);
 166 }
 167 #else
 168 #  define SB_IsEmpty(B) ((B)->Len == 0)
 169 #endif
 170
 171 #if defined(HAVE_INLINE)
 172 INLINE int SB_NotEmpty (const StrBuf* B)
 173 /* Return true if the string buffer is not empty */
 174 {
 175     return (B->Len > 0);
 176 }
 177 #else
 178 #  define SB_NotEmpty(B) ((B)->Len > 0)
 179 #endif
 180
 181 #if defined(HAVE_INLINE)
 182 INLINE void SB_Clear (StrBuf* B)
 183 /* Clear the string buffer (make it empty) */
 184 {
 185     B->Len = B->Index = 0;
 186 }
 187 #else
 188 #  define SB_Clear(B)   ((B)->Len = (B)->Index = 0)
 189 #endif
 190
 191 #if defined(HAVE_INLINE)
 192 INLINE void SB_Reset (StrBuf* B)
 193 /* Reset the string buffer index to zero */
 194 {
 195     B->Index = 0;
 196 }
 197 #else
 198 #  define SB_Reset(B)   ((B)->Index = 0)
 199 #endif
 200
 201 #if defined(HAVE_INLINE)
 202 INLINE char SB_Get (StrBuf* B)
 203 /* Return the next character from the string incrementing Index. Returns NUL
 204  * if the end of the string is reached.
 205  */
 206 {
 207     return (B->Index < B->Len)? B->Buf[B->Index++] : '\0';
 208 }
 209 #else
 210 #  define SB_Get(B)     (((B)->Index < (B)->Len)? (B)->Buf[(B)->Index++] : '\0')
 211 #endif
 212
 213 #if defined(HAVE_INLINE)
 214 INLINE char SB_Peek (const StrBuf* B)
 215 /* Look at the next character from the string without incrementing Index.
 216  * Returns NUL if the end of the string is reached.
 217  */
 218 {
 219     return (B->Index < B->Len)? B->Buf[B->Index] : '\0';
 220 }
 221 #else
 222 #  define SB_Peek(B)     (((B)->Index < (B)->Len)? (B)->Buf[(B)->Index] : '\0')
 223 #endif
 224
 225 #if defined(HAVE_INLINE)
 226 INLINE char SB_LookAt (const StrBuf* B, unsigned Index)
 227 /* Look at a specific character from the string. Returns NUL if the given
 228  * index is greater than the size of the string.
 229  */
 230 {
 231     return (Index < B->Len)? B->Buf[Index] : '\0';
 232 }
 233 #else
 234 #  define SB_LookAt(B,Index)     (((Index) < (B)->Len)? (B)->Buf[(Index)] : '\0')
 235 #endif
 236
 237 #if defined(HAVE_INLINE)
 238 INLINE char SB_LookAtLast (const StrBuf* B)
 239 /* Look at the last character from the string. Returns NUL if the string buffer
 240  * is empty.
 241  */
 242 {
 243     return (B->Len > 0)? B->Buf[B->Len-1] : '\0';
 244 }
 245 #else
 246 #  define SB_LookAtLast(B)      (((B)->Len > 0)? (B)->Buf[(B)->Len-1] : '\0')
 247 #endif
 248
 249 #if defined(HAVE_INLINE)
 250 INLINE void SB_Skip (StrBuf* B)
 251 /* Skip the next character in the string buffer if this is possible. */
 252 {
 253     if (B->Index < B->Len) {
 254         ++B->Index;
 255     }
 256 }
 257 #else
 258 #  define SB_Skip(B)     do { if ((B)->Index < (B)->Len) ++(B)->Index; } while (0)
 259 #endif
 260
 261 void SB_Drop (StrBuf* B, unsigned Count);
 262 /* Drop characters from the end of the string. */
 263
 264 void SB_Terminate (StrBuf* B);
 265 /* Zero terminate the given string buffer. NOTE: The terminating zero is not
 266  * accounted for in B->Len, if you want that, you have to use AppendChar!
 267  */
 268
 269 void SB_CopyBuf (StrBuf* Target, const char* Buf, unsigned Size);
 270 /* Copy Buf to Target, discarding the old contents of Target */
 271
 272 #if defined(HAVE_INLINE)
 273 INLINE void SB_CopyStr (StrBuf* Target, const char* S)
 274 /* Copy S to Target, discarding the old contents of Target */
 275 {
 276     SB_CopyBuf (Target, S, strlen (S));
 277 }
 278 #else
 279 void SB_CopyStr (StrBuf* Target, const char* S);
 280 /* Copy S to Target, discarding the old contents of Target */
 281 #endif
 282
 283 #if defined(HAVE_INLINE)
 284 INLINE void SB_Copy (StrBuf* Target, const StrBuf* Source)
 285 /* Copy Source to Target, discarding the old contents of Target */
 286 {
 287     SB_CopyBuf (Target, Source->Buf, Source->Len);
 288     Target->Index = Source->Index;
 289 }
 290 #else
 291 void SB_Copy (StrBuf* Target, const StrBuf* Source);
 292 /* Copy Source to Target, discarding the old contents of Target */
 293 #endif
 294
 295 void SB_AppendChar (StrBuf* B, int C);
 296 /* Append a character to a string buffer */
 297
 298 void SB_AppendBuf (StrBuf* B, const char* S, unsigned Size);
 299 /* Append a character buffer to the end of the string buffer */
 300
 301 #if defined(HAVE_INLINE)
 302 INLINE void SB_AppendStr (StrBuf* B, const char* S)
 303 /* Append a string to the end of the string buffer */
 304 {
 305     SB_AppendBuf (B, S, strlen (S));
 306 }
 307 #else
 308 void SB_AppendStr (StrBuf* B, const char* S);
 309 /* Append a string to the end of the string buffer */
 310 #endif
 311
 312 #if defined(HAVE_INLINE)
 313 INLINE void SB_Append (StrBuf* Target, const StrBuf* Source)
 314 /* Append the contents of Source to Target */
 315 {
 316     SB_AppendBuf (Target, Source->Buf, Source->Len);
 317 }
 318 #else
 319 void SB_Append (StrBuf* Target, const StrBuf* Source);
 320 /* Append the contents of Source to Target */
 321 #endif
 322
 323 #if defined(HAVE_INLINE)
 324 INLINE void SB_Cut (StrBuf* B, unsigned Len)
 325 /* Cut the contents of B at the given length. If the current length of the
 326  * buffer is smaller than Len, nothing will happen.
 327  */
 328 {
 329     if (Len < B->Len) {
 330         B->Len = Len;
 331     }
 332 }
 333 #else
 334 void SB_Cut (StrBuf* B, unsigned Len);
 335 /* Cut the contents of B at the given length. If the current length of the
 336  * buffer is smaller than Len, nothing will happen.
 337  */
 338 #endif
 339
 340 void SB_Slice (StrBuf* Target, const StrBuf* Source, unsigned Start, unsigned Len);
 341 /* Copy a slice from Source into Target. The current contents of Target are
 342  * destroyed. If Start is greater than the length of Source, or if Len
 343  * characters aren't available, the result will be a buffer with less than Len
 344  * bytes.
 345  */
 346
 347 void SB_Move (StrBuf* Target, StrBuf* Source);
 348 /* Move the complete contents of Source to target. This will delete the old
 349  * contents of Target, and Source will be empty after the call.
 350  */
 351
 352 int SB_Compare (const StrBuf* S1, const StrBuf* S2);
 353 /* Do a lexical compare of S1 and S2. See strcmp for result codes. */
 354
 355 void SB_VPrintf (StrBuf* S, const char* Format, va_list ap);
 356 /* printf function with S as target. The function is safe, which means that
 357  * the current contents of S are discarded, and are allocated again with
 358  * a matching size for the output. The function will call FAIL when problems
 359  * are detected (anything that let xsnprintf return -1).
 360  */
 361
 362 void SB_Printf (StrBuf* S, const char* Format, ...);
 363 /* vprintf function with S as target. The function is safe, which means that
 364  * the current contents of S are discarded, and are allocated again with
 365  * a matching size for the output. The function will call FAIL when problems
 366  * are detected (anything that let xsnprintf return -1).
 367  */
 368
 369
 370
 371 /* End of strbuf.h */
 372
 373 #endif
 374
 375
 376