| STRBUF(3) | UNIDATA LIBRARY FUNCTIONS | STRBUF(3) |
strbuf, sbnew, sbcpy, sbncpy, sbcat, sbncat, sbstr, sblen, sbmax, sbgrow, sbfree - Unidata string-buffer
#include "udposix.h" #include <stddef.h> /* for "size_t" */ #include "strbuf.h" Strbuf *sbnew(size_t max) Strbuf *sbensure(Strbuf *sb, size_t max) Strbuf *sbcpy(Strbuf *sb, const char *string) Strbuf *sbncpy(Strbuf *sb, const char *string, size_t len) Strbuf *sbcat(Strbuf *sb, const char *string) Strbuf *sbncat(Strbuf *sb, const char *string, size_t len) char *sbstr(const Strbuf *sb) size_t sblen(const Strbuf *sb) size_t sbmax(const Strbuf *sb) Strbuf *sbgrow(Strbuf *sb) Strbuf *sbfree(Strbuf *sb)
These routines define the Unidata string-buffer abstraction. This abstraction permits operating on strings without concern for size (e.g. arbitrary concatenation).
sbnew() creates a new instance of a string buffer. max is the initial maximum size of the string buffer, which is the number of characters the buffer may hold, excluding the terminating ´\0´ character. Although the buffer will grow beyond this size if necessary, it is in the user's interest to set max to an appropriate value (e.g. sufficient to hold 90% of it's potential population). This function returns the new string-buffer or NULL if an error occurs.
sbensure() ensure that the string buffer will be able to contain a string having max characters (excluding the terminating ´\0´). This function returns the new string-buffer or NULL if an error occurs.
sbcpy() sets the string-buffer to string, which must be 0-terminated. If successful, this function returns the original string-buffer. If an error occurs, this function returns NULL and the string-buffer is unchanged.
sbncpy() sets the string-buffer to string. len is the number of characters in string to use and should exclude any terminating \'0´ character. If successful, this function returns the original string-buffer. If an error occurs, this function returns NULL and the string-buffer is unchanged.
sbcat() appends string, which must be 0-terminated, to the contents of the string-buffer. If the string-buffer has not been set via an earlier call to sbcpy() or sbncpy(), then the result is the same as sbcpy(sb, string). If successful, this function returns the original string-buffer. If an error occurs, this function returns NULL and the string-buffer is unchanged.
sbncat() appends string to the contents of the string-buffer. len is the number of characters to append and should exclude any terminating \'0´ character. If the string-buffer has not been set via an earlier call to sbcpy() or sbncpy(), then the result is the same as sbcpy(sb, string). If successful, this function returns the original string-buffer. If an error occurs, this function returns NULL and the string-buffer is unchanged.
sbstr() returns a pointer to the ´\0´-terminated string in the string-buffer. If the string buffer has not been set, then the pointed-to string is empty (NB: the pointer is not NULL). The returned string pointer may be used like any other string pointer provided the user has ensured the size of the string-buffer via a call to sbensure(), if appropriate. For example:
(void) sbensure(sb, strlen(string)); (void) strcpy(sbstr(sb), string);
When string buffers are used this way, the calling application is responsible for ensuring proper ´\0´-termination.
sblen() returns the number of characters in the string-buffer, excluding the terminating ´\0´ character. If the string-buffer has not been set, then the returned length is zero.
sbmax() returns the maximum number of characters that the string-buffer can currently hold, excluding the terminating ´\0´ character.
sbgrow() increases the size of the string buffer. This is useful when there is no a priori knowledge of how large the string buffer should be.
sbfree() releases the resources used by the string-buffer back to the operating-system and should be called when the string-buffer is no longer needed. It always returns (Strbuf*)NULL.
This package uses the UDPOSIX programming environment and the udalloc(3) memory allocation package.
Steve Emmerson <steve@unidata.ucar.edu>.
| $Date: 2000/08/07 23:15:04 $ | Printed: 0-0-0 |