.TH stralloc 3

.SH NAME

stralloc \- dynamically allocated strings

.SH SYNTAX

.B #include <stralloc.h>

int \fBstralloc_ready\fP(&\fIsa\fR,\fIlen\fR);

.br

int \fBstralloc_readyplus\fP(&\fIsa\fR,\fIlen\fR);

int \fBstralloc_copy\fP(&\fIsa\fR,&\fIsa2\fR);

.br

int \fBstralloc_copys\fP(&\fIsa\fR,\fIbuf\fR);

.br

int \fBstralloc_copyb\fP(&\fIsa\fR,\fIbuf\fR,\fIlen\fR);

int \fBstralloc_cat\fP(&\fIsa\fR,&\fIsa2\fR);

.br

int \fBstralloc_cats\fP(&\fIsa\fR,\fIbuf\fR);

.br

int \fBstralloc_catb\fP(&\fIsa\fR,\fIbuf\fR,\fIlen\fR);

int \fBstralloc_append\fP(&\fIsa\fR,\fIbuf\fR);

.br

int \fBstralloc_0\fP(&\fIsa\fR);

int \fBstralloc_starts\fP(&\fIsa\fR,\fIbuf\fR);

stralloc \fIsa\fR = {0};

.br

stralloc \fIsa2\fR = {0};

.br

unsigned int \fIlen\fR;

.br

char *\fIbuf\fR;

.SH DESCRIPTION

A

.B stralloc

variable holds a string in dynamically allocated space.

String length is limited only by memory.

String contents are unrestricted.

The

.B stralloc

structure has three components:

.I sa\fB.s

is a pointer to the string, or 0 if it is not allocated;

.I sa\fB.len

is the number of bytes in the string, if it is allocated;

.I sa\fB.a

is the number of bytes allocated for the string, if it is allocated.

A

.B stralloc

variable should be initialized to {0},

meaning unallocated.

.B stralloc_ready

makes sure that

.I sa

has enough space allocated for

.I len

characters.

It allocates extra space if necessary.

.B stralloc_readyplus

makes sure that

.I sa

has enough space allocated for

.I len

characters more than its current length.

If

.I sa

is unallocated,

.B stralloc_readyplus

is the same as

.BR stralloc_ready .

.B stralloc_copy

copies

.I sa2

to

.IR sa ,

allocating space if necessary.

Here

.I sa2

is an allocated

.B stralloc

variable.

.B stralloc_copys

copies a 0-terminated string,

.IR buf ,

to

.IR sa ,

without the 0.

.B stralloc_copyb

copies

.I len

characters from

.I buf

to

.IR sa .

.B stralloc_cat

appends

.I sa2

to

.IR sa ,

allocating space if necessary.

If

.I sa

is unallocated,

.B stralloc_cat

is the same as

.BR stralloc_copy .

.B stralloc_cats

and

.B stralloc_catb

are analogous to

.B stralloc_copys

and

.BR stralloc_copyb .

.B stralloc_append

adds a single character,

.IR *buf ,

to

.IR sa ,

allocating space if necessary.

.B stralloc_0

adds a single 0 character

to

.IR sa .

.B stralloc_starts

returns 1 if the 0-terminated string

.IR buf ,

without the 0,

is a prefix of

.IR sa .

.SH "ERROR HANDLING"

If a

.B stralloc

routine runs out of memory,

it leaves

.I sa

alone and returns 0,

setting

.B errno

appropriately.

On success it returns 1;

this guarantees that

.I sa

is allocated.

.SH "SEE ALSO"

alloc(3),

error(3)