astring advanced usage
Creating new string modification functions
There are four standard astring functions which modify an astring: two versions of string copy and two versions of string append. Obviously, these are not the only actions you may wish to perform to modify a string.
The implementation of the astrcpy and astrcat functions makes use of a basic astring function called astrensure() which is available to external callers. After calling astrensure(&pasz,len), and getting a non-zero return, it can be safely assumed there are len+1 bytes allocated at pasz until the next astring function or other memory operation is performed on pasz. Use the space as you see fit. Be aware that subsequent calls to astrensure() will run strlen(), so always ensure there is a '\0' string terminator at or before pasz[len];
Example code:
char *astr_insert(char **ppasz,char *pszToInsert)
{ /* Example: insert a string at the beginning of an astring */
int len = strlen(pszToInsert);
if (*ppasz) {
len += strlen(*ppasz);
}
if (astrensure(ppasz,len)) { /* non-zero return means we can proceed */
/* Be sure to move the \0 also. */
memmove(*ppasz,*ppasz+strlen(pszToInsert),strlen(*ppasz)+1);
memcpy(*ppasz,pszToInsert,strlen(pszToInsert));
}
return *ppasz;
} /* astr_insert */
It is not recommended storing binary data which could contain ASCII NUL ('\0') in the buffer, since subsequent calls to astrensure() will truncate the data at that length. The libmib variable sized buffer routines (VSB and CVsb) implement dynamic binary buffers in a much better fashion.
Long-Lived astrings
astrensure() generally "overallocates" memory. When the string must grow in later calls, this having additional space reduces the amount of copying. But if large numbers of astrings must be allocated, the wasted space can be significant. The astrstatic() function call will force a realloc() to just what is needed. (Note that there still may be some wasted space depending on how realloc operates. Many malloc packages allocate blocks of certain fixed sizes.)
Changing the implementation strategy
(The documentation here is incomplete.) There are ways to run-time configure behavior of astrensure(), by calling astrprofile(). See the source. Change the number of bytes overallocated, the number of strings which were tracked, and a debugging mode which forces the movement of the string in memory on every astring call.
Up to: Libmib Allocated String Functions
Up to: Libmib: Character String Processing
Up to: Libmib
This Libmib documentation may not be distributed.
Copyright 1998, Forrest J. Cavalier III
Mib Software
High Reuse Software Development