Back to index

libcitadel  8.12
Functions
Create/Destroy StrBufs
Stringbuffer, A class for manipulating strings with dynamic buffers
Collaboration diagram for Create/Destroy StrBufs:

Functions

static int IncreaseBuf (StrBuf *Buf, int KeepOriginal, int DestSize)
 local utility function to resize the buffer
void ReAdjustEmptyBuf (StrBuf *Buf, long ThreshHold, long NewSize)
 shrink / increase an EMPTY buffer to NewSize.
long StrBufShrinkToFit (StrBuf *Buf, int Force)
 shrink long term buffers to their real size so they don't waste memory
StrBufNewStrBuf (void)
 Allocate a new buffer with default buffer size.
StrBufNewStrBufDup (const StrBuf *CopyMe)
 Copy Constructor; returns a duplicate of CopyMe.
void NewStrBufDupAppendFlush (StrBuf **CreateRelpaceMe, StrBuf *CopyFlushMe, const char *NoMe, int KeepOriginal)
 Copy Constructor; CreateRelpaceMe will contain CopyFlushMe afterwards.
StrBufNewStrBufPlain (const char *ptr, int nChars)
 create a new Buffer using an existing c-string this function should also be used if you want to pre-suggest the buffer size to allocate in conjunction with ptr == NULL
int StrBufPlain (StrBuf *Buf, const char *ptr, int nChars)
 Set an existing buffer from a c-string.
StrBuf_NewConstStrBuf (const char *StringConstant, size_t SizeOfStrConstant)
 use strbuf as wrapper for a string constant for easy handling
int FlushStrBuf (StrBuf *buf)
 flush the content of a Buf; keep its struct
int FLUSHStrBuf (StrBuf *buf)
 wipe the content of a Buf thoroughly (overwrite it -> expensive); keep its struct
void FreeStrBuf (StrBuf **FreeMe)
 Release a Buffer Its a double pointer, so it can NULL your pointer so fancy SIG11 appear instead of random results.
char * SmashStrBuf (StrBuf **SmashMe)
 flatten a Buffer to the Char * we return Its a double pointer, so it can NULL your pointer so fancy SIG11 appear instead of random results The Callee then owns the buffer and is responsible for freeing it.
void HFreeStrBuf (void *VFreeMe)
 Release the buffer If you want put your StrBuf into a Hash, use this as Destructor.

Function Documentation

StrBuf* _NewConstStrBuf ( const char *  StringConstant,
size_t  SizeOfStrConstant 
)

use strbuf as wrapper for a string constant for easy handling

Parameters:
StringConstanta string to wrap
SizeOfStrConstantshould be sizeof(StringConstant)-1

Definition at line 592 of file stringbuf.c.

{
       StrBuf *NewBuf;

       NewBuf = (StrBuf*) malloc(sizeof(StrBuf));
       NewBuf->buf = (char*) StringConstant;
       NewBuf->BufSize = SizeOfStrConstant;
       NewBuf->BufUsed = SizeOfStrConstant;
       NewBuf->ConstBuf = 1;

       dbg_Init(NewBuf);

       return NewBuf;
}
int FlushStrBuf ( StrBuf buf)

flush the content of a Buf; keep its struct

Parameters:
bufBuffer to flush

Definition at line 613 of file stringbuf.c.

{
       if ((buf == NULL) || (buf->buf == NULL))
              return -1;
       if (buf->ConstBuf)
              return -1;       
       buf->buf[0] ='\0';
       buf->BufUsed = 0;
       return 0;
}

Here is the caller graph for this function:

int FLUSHStrBuf ( StrBuf buf)

wipe the content of a Buf thoroughly (overwrite it -> expensive); keep its struct

Parameters:
bufBuffer to wipe

Definition at line 629 of file stringbuf.c.

{
       if (buf == NULL)
              return -1;
       if (buf->ConstBuf)
              return -1;
       if (buf->BufUsed > 0) {
              memset(buf->buf, 0, buf->BufUsed);
              buf->BufUsed = 0;
       }
       return 0;
}

Here is the caller graph for this function:

void FreeStrBuf ( StrBuf **  FreeMe)

Release a Buffer Its a double pointer, so it can NULL your pointer so fancy SIG11 appear instead of random results.

Parameters:
FreeMePointer Pointer to the buffer to free

Definition at line 652 of file stringbuf.c.

{
       if (*FreeMe == NULL)
              return;

       dbg_FreeStrBuf(FreeMe, 'F');

       if (!(*FreeMe)->ConstBuf) 
              free((*FreeMe)->buf);
       free(*FreeMe);
       *FreeMe = NULL;
}
void HFreeStrBuf ( void *  VFreeMe)

Release the buffer If you want put your StrBuf into a Hash, use this as Destructor.

Parameters:
VFreeMeuntyped pointer to a StrBuf. be shure to do the right thing [TM]

Definition at line 695 of file stringbuf.c.

{
       StrBuf *FreeMe = (StrBuf*)VFreeMe;
       if (FreeMe == NULL)
              return;

       dbg_FreeStrBuf(SmashMe, 'H');

       if (!FreeMe->ConstBuf) 
              free(FreeMe->buf);
       free(FreeMe);
}

Here is the caller graph for this function:

static int IncreaseBuf ( StrBuf Buf,
int  KeepOriginal,
int  DestSize 
) [static]

local utility function to resize the buffer

Parameters:
Bufthe buffer whichs storage we should increase
KeepOriginalshould we copy the original buffer or just start over with a new one
DestSizewhat should fit in after?

Definition at line 294 of file stringbuf.c.

{
       char *NewBuf;
       size_t NewSize = Buf->BufSize * 2;

       if (Buf->ConstBuf)
              return -1;
              
       if (DestSize > 0)
              while ((NewSize <= DestSize) && (NewSize != 0))
                     NewSize *= 2;

       if (NewSize == 0)
              return -1;

       NewBuf= (char*) malloc(NewSize);
       if (NewBuf == NULL)
              return -1;

       if (KeepOriginal && (Buf->BufUsed > 0))
       {
              memcpy(NewBuf, Buf->buf, Buf->BufUsed);
       }
       else
       {
              NewBuf[0] = '\0';
              Buf->BufUsed = 0;
       }
       free (Buf->buf);
       Buf->buf = NewBuf;
       Buf->BufSize = NewSize;

       dbg_IncreaseBuf(Buf);

       return Buf->BufSize;
}

Here is the caller graph for this function:

StrBuf* NewStrBuf ( void  )

Allocate a new buffer with default buffer size.

Returns:
the new stringbuffer

Definition at line 378 of file stringbuf.c.

{
       StrBuf *NewBuf;

       NewBuf = (StrBuf*) malloc(sizeof(StrBuf));
       NewBuf->buf = (char*) malloc(BaseStrBufSize);
       NewBuf->buf[0] = '\0';
       NewBuf->BufSize = BaseStrBufSize;
       NewBuf->BufUsed = 0;
       NewBuf->ConstBuf = 0;

       dbg_Init (NewBuf);

       return NewBuf;
}

Here is the caller graph for this function:

StrBuf* NewStrBufDup ( const StrBuf CopyMe)

Copy Constructor; returns a duplicate of CopyMe.

Parameters:
CopyMeBuffer to faxmilate
Returns:
the new stringbuffer

Definition at line 400 of file stringbuf.c.

{
       StrBuf *NewBuf;
       
       if (CopyMe == NULL)
              return NewStrBuf();

       NewBuf = (StrBuf*) malloc(sizeof(StrBuf));
       NewBuf->buf = (char*) malloc(CopyMe->BufSize);
       memcpy(NewBuf->buf, CopyMe->buf, CopyMe->BufUsed + 1);
       NewBuf->BufUsed = CopyMe->BufUsed;
       NewBuf->BufSize = CopyMe->BufSize;
       NewBuf->ConstBuf = 0;

       dbg_Init(NewBuf);

       return NewBuf;
}

Here is the call graph for this function:

Here is the caller graph for this function:

void NewStrBufDupAppendFlush ( StrBuf **  CreateRelpaceMe,
StrBuf CopyFlushMe,
const char *  NoMe,
int  KeepOriginal 
)

Copy Constructor; CreateRelpaceMe will contain CopyFlushMe afterwards.

Parameters:
NoMeif non-NULL, we will use that buffer as value; KeepOriginal will abused as len.
CopyFlushMeBuffer to faxmilate if KeepOriginal, or to move into CreateRelpaceMe if !KeepOriginal.
CreateRelpaceMeIf NULL, will be created, else Flushed and filled CopyFlushMe
KeepOriginalshould CopyFlushMe remain intact? or may we Steal its buffer?
Returns:
the new stringbuffer

Definition at line 428 of file stringbuf.c.

{
       StrBuf *NewBuf;
       
       if (CreateRelpaceMe == NULL)
              return;

       if (NoMe != NULL)
       {
              if (*CreateRelpaceMe != NULL)
                     StrBufPlain(*CreateRelpaceMe, NoMe, KeepOriginal);
              else 
                     *CreateRelpaceMe = NewStrBufPlain(NoMe, KeepOriginal);
              return;
       }

       if (CopyFlushMe == NULL)
       {
              if (*CreateRelpaceMe != NULL)
                     FlushStrBuf(*CreateRelpaceMe);
              else 
                     *CreateRelpaceMe = NewStrBuf();
              return;
       }

       /* 
        * Randomly Chosen: bigger than 64 chars is cheaper to swap the buffers instead of copying.
        * else *CreateRelpaceMe may use more memory than needed in a longer term, CopyFlushMe might
        * be a big IO-Buffer...
        */
       if (KeepOriginal || (StrLength(CopyFlushMe) < 256))
       {
              if (*CreateRelpaceMe == NULL)
              {
                     *CreateRelpaceMe = NewBuf = NewStrBufPlain(NULL, CopyFlushMe->BufUsed);
                     dbg_Init(NewBuf);
              }
              else 
              {
                     NewBuf = *CreateRelpaceMe;
                     FlushStrBuf(NewBuf);
              }
              StrBufAppendBuf(NewBuf, CopyFlushMe, 0);
       }
       else
       {
              if (*CreateRelpaceMe == NULL)
              {
                     *CreateRelpaceMe = NewBuf = NewStrBufPlain(NULL, CopyFlushMe->BufUsed);
                     dbg_Init(NewBuf);
              }
              else 
                     NewBuf = *CreateRelpaceMe;
              SwapBuffers (NewBuf, CopyFlushMe);
       }
       if (!KeepOriginal)
              FlushStrBuf(CopyFlushMe);
       return;
}

Here is the call graph for this function:

StrBuf* NewStrBufPlain ( const char *  ptr,
int  nChars 
)

create a new Buffer using an existing c-string this function should also be used if you want to pre-suggest the buffer size to allocate in conjunction with ptr == NULL

Parameters:
ptrthe c-string to copy; may be NULL to create a blank instance
nCharsHow many chars should we copy; -1 if we should measure the length ourselves
Returns:
the new stringbuffer

Definition at line 497 of file stringbuf.c.

{
       StrBuf *NewBuf;
       size_t Siz = BaseStrBufSize;
       size_t CopySize;

       NewBuf = (StrBuf*) malloc(sizeof(StrBuf));
       if (nChars < 0)
              CopySize = strlen((ptr != NULL)?ptr:"");
       else
              CopySize = nChars;

       while ((Siz <= CopySize) && (Siz != 0))
              Siz *= 2;

       if (Siz == 0)
       {
              free(NewBuf);
              return NULL;
       }

       NewBuf->buf = (char*) malloc(Siz);
       if (NewBuf->buf == NULL)
       {
              free(NewBuf);
              return NULL;
       }
       NewBuf->BufSize = Siz;
       if (ptr != NULL) {
              memcpy(NewBuf->buf, ptr, CopySize);
              NewBuf->buf[CopySize] = '\0';
              NewBuf->BufUsed = CopySize;
       }
       else {
              NewBuf->buf[0] = '\0';
              NewBuf->BufUsed = 0;
       }
       NewBuf->ConstBuf = 0;

       dbg_Init(NewBuf);

       return NewBuf;
}

Here is the caller graph for this function:

void ReAdjustEmptyBuf ( StrBuf Buf,
long  ThreshHold,
long  NewSize 
)

shrink / increase an EMPTY buffer to NewSize.

Buffercontent is thoroughly ignored and flushed.

Parameters:
BufBuffer to shrink (has to be empty)
ThreshHoldif the buffer is bigger then this, its readjusted
NewSizeif we Shrink it, how big are we going to be afterwards?

Definition at line 338 of file stringbuf.c.

{
       if ((Buf != NULL) && 
           (Buf->BufUsed == 0) &&
           (Buf->BufSize < ThreshHold)) {
              free(Buf->buf);
              Buf->buf = (char*) malloc(NewSize);
              Buf->BufUsed = 0;
              Buf->BufSize = NewSize;
       }
}

Here is the caller graph for this function:

char* SmashStrBuf ( StrBuf **  SmashMe)

flatten a Buffer to the Char * we return Its a double pointer, so it can NULL your pointer so fancy SIG11 appear instead of random results The Callee then owns the buffer and is responsible for freeing it.

Parameters:
SmashMePointer Pointer to the buffer to release Buf from and free
Returns:
the pointer of the buffer; Callee owns the memory thereafter.

Definition at line 674 of file stringbuf.c.

{
       char *Ret;

       if ((SmashMe == NULL) || (*SmashMe == NULL))
              return NULL;
       
       dbg_FreeStrBuf(SmashMe, 'S');

       Ret = (*SmashMe)->buf;
       free(*SmashMe);
       *SmashMe = NULL;
       return Ret;
}

Here is the caller graph for this function:

int StrBufPlain ( StrBuf Buf,
const char *  ptr,
int  nChars 
)

Set an existing buffer from a c-string.

Parameters:
Bufbuffer to load
ptrc-string to put into
nCharsset to -1 if we should work 0-terminated
Returns:
the new length of the string

Definition at line 549 of file stringbuf.c.

{
       size_t Siz;
       size_t CopySize;

       if (Buf == NULL)
              return -1;
       if (ptr == NULL) {
              FlushStrBuf(Buf);
              return -1;
       }

       Siz = Buf->BufSize;

       if (nChars < 0)
              CopySize = strlen(ptr);
       else
              CopySize = nChars;

       while ((Siz <= CopySize) && (Siz != 0))
              Siz *= 2;

       if (Siz == 0) {
              FlushStrBuf(Buf);
              return -1;
       }

       if (Siz != Buf->BufSize)
              IncreaseBuf(Buf, 0, Siz);
       memcpy(Buf->buf, ptr, CopySize);
       Buf->buf[CopySize] = '\0';
       Buf->BufUsed = CopySize;
       Buf->ConstBuf = 0;
       return CopySize;
}

Here is the call graph for this function:

Here is the caller graph for this function:

long StrBufShrinkToFit ( StrBuf Buf,
int  Force 
)

shrink long term buffers to their real size so they don't waste memory

Parameters:
Bufbuffer to shrink
Forceif not set, will just executed if the buffer is much to big; set for lifetime strings
Returns:
physical size of the buffer

Definition at line 357 of file stringbuf.c.

{
       if (Buf == NULL)
              return -1;
       if (Force || 
           (Buf->BufUsed + (Buf->BufUsed / 3) > Buf->BufSize))
       {
              char *TmpBuf = (char*) malloc(Buf->BufUsed + 1);
              memcpy (TmpBuf, Buf->buf, Buf->BufUsed + 1);
              Buf->BufSize = Buf->BufUsed + 1;
              free(Buf->buf);
              Buf->buf = TmpBuf;
       }
       return Buf->BufUsed;
}

Here is the caller graph for this function: