focal (3) stralloc.3.gz

NAME

       stralloc - dynamically allocated strings

SYNTAX

       #include <stralloc.h>

       int stralloc_ready(&sa,len);
       int stralloc_readyplus(&sa,len);

       int stralloc_copy(&sa,&sa2);
       int stralloc_copys(&sa,buf);
       int stralloc_copyb(&sa,buf,len);

       int stralloc_cat(&sa,&sa2);
       int stralloc_cats(&sa,buf);
       int stralloc_catb(&sa,buf,len);

       int stralloc_append(&sa,buf);
       int stralloc_0(&sa);

       int stralloc_starts(&sa,buf);

       stralloc sa = {0};
       stralloc sa2 = {0};
       unsigned int len;
       char *buf;

DESCRIPTION

       A  stralloc  variable  holds  a  string in dynamically allocated space.  String length is limited only by
       memory.  String contents are unrestricted.

       The stralloc structure has three components: sa.s is a  pointer  to  the  string,  or  0  if  it  is  not
       allocated;  sa.len  is the number of bytes in the string, if it is allocated; sa.a is the number of bytes
       allocated for the string, if it is allocated.  A stralloc variable should be initialized to {0},  meaning
       unallocated.

       stralloc_ready  makes  sure  that  sa  has enough space allocated for len characters.  It allocates extra
       space if necessary.

       stralloc_readyplus makes sure that sa has enough space allocated for len characters more than its current
       length.  If sa is unallocated, stralloc_readyplus is the same as stralloc_ready.

       stralloc_copy  copies  sa2  to  sa,  allocating  space  if  necessary.  Here sa2 is an allocated stralloc
       variable.

       stralloc_copys copies a 0-terminated string, buf, to sa, without the 0.

       stralloc_copyb copies len characters from buf to sa.

       stralloc_cat appends sa2 to sa, allocating space if necessary.  If sa is unallocated, stralloc_cat is the
       same as stralloc_copy.

       stralloc_cats and stralloc_catb are analogous to stralloc_copys and stralloc_copyb.

       stralloc_append adds a single character, *buf, to sa, allocating space if necessary.

       stralloc_0 adds a single 0 character to sa.

       stralloc_starts returns 1 if the 0-terminated string buf, without the 0, is a prefix of sa.

ERROR HANDLING

       If  a stralloc routine runs out of memory, it leaves sa alone and returns 0, setting errno appropriately.
       On success it returns 1; this guarantees that sa is allocated.

SEE ALSO

       alloc(3), error(3)

                                                                                                     stralloc(3)