The stralloc library interface

I'm replacing the stralloc interface with the array interface.

Dynamically allocated strings

     #include <stralloc.h>

     stralloc sa = {0};

A stralloc variable holds a byte string in dynamically allocated space. String contents are unrestricted; in particular, strings may contain \0. String length is limited only by memory and by the size of an unsigned int.

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

Applications are expected to use sa.s and sa.len directly.

Allocating space

     #include <stralloc.h>

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

     stralloc sa;
     unsigned int len;

stralloc_ready makes sure that sa has enough space allocated to hold len bytes:

If sa is not allocated, stralloc_ready allocates at least len bytes of space, and returns 1.
If sa is already allocated, but not enough to hold len bytes, stralloc_ready allocates at least len bytes of space, copies the old string into the new space, frees the old space, and returns 1. Note that this changes sa.s.
If enough space is already allocated, stralloc_ready returns 1.

If it runs out of memory, stralloc_ready leaves sa alone and returns 0, setting errno appropriately.

stralloc_readyplus is like stralloc_ready except that, if sa is already allocated, stralloc_readyplus adds the current length of sa to len.

Copying strings

     #include <stralloc.h>

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

     stralloc sa;
     stralloc sa2;
     char *buf;
     unsigned int len;

stralloc_copyb copies the string buf[0], buf[1], ..., buf[len-1] into sa, allocating space if necessary, and returns 1. If it runs out of memory, stralloc_copyb leaves sa alone and returns 0.

stralloc_copys copies a \0-terminated string from buf into sa, without the \0. It is the same as stralloc_copyb(&sa,buf,str_len(buf)).

stralloc_copy copies the string stored in sa2 into sa. It is the same as stralloc_copyb(&sa,sa2.s,sa2.len). sa2 must already be allocated.

Concatenating strings

     #include <stralloc.h>

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

     stralloc sa;
     stralloc sa2;
     char *buf;
     unsigned int len;

stralloc_catb adds the string buf[0], buf[1], ... buf[len-1] to the end of the string stored in sa, allocating space if necessary, and returns 1. If sa is unallocated, stralloc_catb is the same as stralloc_copyb. If it runs out of memory, stralloc_catb leaves sa alone and returns 0.

stralloc_cats is analogous to stralloc_copys, and stralloc_cat is analogous to stralloc_copy.

stralloc_append adds one byte buf[0] to the end of the string stored in sa. It is the same as stralloc_catb(&sa,buf,1).

stralloc_0 adds \0 to the end of the string stored in sa. It is the same as stralloc_append(&sa,"").

Comparing strings

     #include <stralloc.h>

     stralloc_starts(&sa,buf);

     stralloc sa;
     char *buf;

stralloc_starts returns 1 if the \0-terminated string in buf, without the terminating \0, is a prefix of the string stored in sa. Otherwise it returns 0. sa must already be allocated.