bionic (3) strbuf.3.gz

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