|
NAME
| |
s_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, s_allocinstack, s_freeinstack, s_rdinstack – extensible
strings
|
SYNOPSIS
| |
#include <u.h>
#include <libc.h>
#include <String.h>
String* s_new(void)
void s_free(String *s)
String* s_newalloc(int n)
String* s_array(char *p, int n)
String* s_grow(String *s, int n)
void s_putc(String *s, int c)
void s_terminate(String *s)
String* s_reset(String *s)
String* s_restart(String *s)
String* s_append(String *s, char *p)
String* s_nappend(String *s, char *p, int n)
String* s_memappend(String *s, char *p, int n)
String* s_copy(char *p)
String* s_parse(String *s1, String *s2)
void s_tolower(String *s)
String* s_incref(String *s)
String* s_unique(String *s)
Sinstack* s_allocinstack(char *file)
void s_freeinstack(Sinstack *stack)
char* s_rdinstack(Sinstack *stack, String *s)
#include <bio.h>
int s_read(Biobuf *b, String *s, int n)
char* s_read_line(Biobuf *b, String *s)
char* s_getline(Biobuf *b, String *s)
|
DESCRIPTION
| |
These routines manipulate extensible strings. The basic type is
String, which points to an array of characters. The string maintains
pointers to the beginning and end of the allocated array. In addition
a finger pointer keeps track of where parsing will start (for
s_parse) or new characters will be added (for s_putc, s_append,
and s_nappend). The
structure, and a few useful macros are:
typedef 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)
S_to_c is used when code needs a reference to the character array.
Using s−>base directly is frowned upon since it exposes too much
of the implementation.
Allocation and freeing
A string must be allocated before it can be used. One normally
does this using s_new, giving the string an initial allocation
of 128 bytes. If you know that the string will need to grow much
longer, you can use s_newalloc instead, specifying the number
of bytes in the initial allocation.
S_free causes both the string and its character array to be freed.
S_grow grows a string’s allocation by a fixed amount. It is useful
if you are reading directly into a string’s character array but
should be avoided if possible.
S_array is used to create a constant array, that is, one whose
contents won’t change. It points directly to the character array
given as an argument. Tread lightly when using this call.
Filling the string
After its initial allocation, the string points to the beginning
of an allocated array of characters starting with NUL.
S_putc writes a character into the string at the pointer and advances
the pointer to point after it.
S_terminate writes a NUL at the pointer but doesn’t advance it.
S_restart resets the pointer to the begining of the string but
doesn’t change the contents.
S_reset is equivalent to s_restart followed by s_terminate.
S_append and s_nappend copy characters into the string at the
pointer and advance the pointer. They also write a NUL at the
pointer without advancing the pointer beyond it. Both routines
stop copying on encountering a NUL. S_memappend is like s_nappend
but doesn’t stop at a NUL.
If you know the initial character array to be copied into a string,
you can allocate a string and copy in the bytes using s_copy.
This is the equivalent of a s_new followed by an s_append.
S_parse copies the next white space terminated token from s1 to
the end of s2. White space is defined as space, tab, and newline.
Both single and double quoted strings are treated as a single
token. The bounding quotes are not copied. There is no escape
mechanism.
S_tolower converts all ASCII characters in the string to lower
case.
Multithreading
S_incref is used by multithreaded programs to avoid having the
string memory released until the last user of the string performs
an s_free. S_unique returns a unique copy of the string: if the
reference count it 1 it returns the string, otherwise it returns
an s_clone of the string.
Bio interaction
S_read reads the requested number of characters through a Biobuf
into 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.
S_read_line reads up to and including the next newline and returns
a pointer to the beginning of the bytes read. An eof or error
terminates the read. The string is null terminated.
S_getline reads up to the next newline, appends the input to s,
and returns a pointer to the beginning of the bytes read. Leading
spaces and tabs and the trailing newline are all discarded. S_getline
discards blank lines and lines beginning with #. S_getline ignores
newlines escaped by immediately-preceding backslashes.
S_allocinstack allocates an input stack with the single file file
open for reading. S_freeinstack frees an input stack. S_rdinstack
reads a line from an input stack. It follows the same rules as
s_getline except that when it encounters a line of the form #include
newfile, s_getline pushes newfile onto the input stack, postponing
further reading of the
current file until newfile has been read. The input stack has
a maximum depth of 32 nested include files.
|
SOURCE
SEE ALSO
|
|
