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

Printed: 125-11-1                         $Date: 2000/08/07 23:15:04 $                                 STRBUF(3)