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