.TH STRING 2.SH NAMEs_alloc, s_append, s_array, s_copy, s_error, s_free, s_incref, s_memappend, s_nappend, s_new, s_newalloc, s_parse, s_reset, s_restart, s_terminate, s_tolower, s_putc, s_unique, s_grow, s_read, s_read_line, s_getline \- extensible strings.SH SYNOPSIS.B #include <u.h>.br.B #include <libc.h>.br.B #include <String.h>.PP.BString*	s_new(void).br.Bvoid		s_free(String *s).br.BString*	s_newalloc(int n).br.BString*	s_array(char *p, int n).br.BString*	s_grow(String *s, int n).PP.Bvoid		s_putc(String *s, int c).br.Bvoid		s_terminate(String *s).br.BString*	s_reset(String *s).br.BString*	s_restart(String *s).br.BString*	s_append(String *s, char *p).br.BString*	s_nappend(String *s, char *p, int n).br.BString*	s_memappend(String *s, char *p, int n).br.BString*	s_copy(char *p).br.BString*	s_parse(String *s1, String *s2).br.PP.Bvoid		s_tolower(String *s).PP.BString*	s_incref(String *s).br.BString*	s_unique(String *s).PP.B#include <bio.h>.PP.Bint		s_read(Biobuf *b, String *s, int n).br.Bchar*	s_read_line(Biobuf *b, String *s).br.Bchar*	s_getline(Biobuf *b, String *s).SH DESCRIPTION.PPThese routines manipulate extensible strings.  The basic type is.BR String ,which points to an array of characters.  The stringmaintains pointers to the beginning and end of the allocatedarray.  In addition a finger pointer keeps track of where parsing will start (for.IR s_parse )or new characters will be added (for.IR s_putc ,.IR s_append ,and.IR s_nappend ).The structure, and a few useful macros are:.sp.EXtypedef struct String {	Lock;	char	*base;	/* base of String */	char	*end;	/* end of allocated space+1 */	char	*ptr;	/* ptr into String */	...} String; #define s_to_c(s) ((s)->base)#define s_len(s) ((s)->ptr-(s)->base)#define s_clone(s) s_copy((s)->base).EE.PP.I S_to_cis used when code needs a reference to the character array.Using.B s->basedirectly is frowned upon since it exposes too much of the implementation..SS "allocation and freeing.PPA string must be allocated before it can be used.One normally does this using.IR s_new ,giving the string an initial allocation of128 bytes.If you know that the string will need to grow muchlonger, you can use.I s_newallocinstead, specifying the number of bytes in theinitial allocation..PP.I S_freecauses both the string and its character array to be freed..PP.I S_growgrows a string's allocation by a fixed amount.  It is useful ifyou are reading directly into a string's character array but shouldbe avoided if possible..PP.I S_arrayis used to create a constant array, that is, one whose contentswon't change.  It points directly to the character arraygiven as an argument.  Tread lightly when using this call..SS "Filling the stringAfter its initial allocation, the string points to the beginningof an allocated array of characters starting with.SM NUL..PP.I S_putcwrites a character into the string at thepointer and advances the pointer to point after it..PP.I S_terminatewrites a.SM NULat the pointer but doesn't advance it..PP.I S_restartresets the pointer to the begining of the string but doesn't change the contents..PP.I S_resetis equivalent to.I s_restartfollowed by.IR s_terminate ..PP.I S_appendand.I s_nappendcopy characters into the string at the pointer andadvance the pointer.  They also write a.SM NULatthe pointer without advancing the pointer beyond it.Both routines stop copying on encountering a.SM NUL..I S_memappendis like.I s_nappendbut doesn't stop at a.SM NUL..PPIf you know the initial character array to be copied into a string,you can allocate a string and copy in the bytes using.IR s_copy .This is the equivalent of a.I s_newfollowed by an.IR s_append ..PP.I S_parsecopies the next white space terminated token from.I s1tothe end of .IR s2 .White space is defined as space, tab,and newline.  Both single and double quoted strings are treated asa single token.  The bounding quotes are not copied.There is no escape mechanism. .PP.I S_tolowerconverts all.SM ASCIIcharacters in the string to lower case..SS Multithreading.PP.I S_increfis used by multithreaded programs to avoid having the string memoryreleased until the last user of the string performs an.IR s_free ..I S_uniquereturns a unique copy of the string: if the reference count it1 it returns the string, otherwise it returns an.I s_cloneof the string..SS "Bio interaction.PP.I S_readreads the requested number of characters through a.I Biobufinto a string.  The string is grown as necessary.An eof or error terminates the read.The number of bytes read is returned.The string is null terminated..PP.I S_read_linereads up to and including the next newline and returnsa pointer to the beginning of the bytes read.An eof or error terminates the read.The string is null terminated..PP.I S_getlinereads up to the next newline and returnsa pointer to the beginning of the bytes read.  Leadingspaces and tabs and the trailing newline are all discarded..I S_getlinewill recursively read through files included with.B #includeand discard all other lines beginning with.BR # ..SH SOURCE.B /sys/src/libString.SH SEE ALSO.IR bio (2)