SYNOPSIS

#include "udposix.h"
#include <stddef.h> /* for "size_t" */
#include "strbuf.h"

DESCRIPTION

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.

MAINTAINER