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