NAME¶

strbuf, sbnew, sbcpy, sbncpy, sbcat, sbncat, sbstr, sblen, sbmax, sbgrow, sbfree - Unidata string-buffer

SYNOPSIS¶

#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)

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¶

Steve Emmerson <steve@unidata.ucar.edu>.

SEE ALSO¶

udalloc(3), udposix(3).