From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/string.html | 244 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 244 insertions(+) create mode 100644 man/man3/string.html (limited to 'man/man3/string.html') diff --git a/man/man3/string.html b/man/man3/string.html new file mode 100644 index 00000000..55a1673b --- /dev/null +++ b/man/man3/string.html @@ -0,0 +1,244 @@ + +string(3) - Plan 9 from User Space + + + + +
+
+
STRING(3)STRING(3) +
+
+

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
+ +
+ + /usr/local/plan9/src/libString
+ +
+

SEE ALSO
+ +
+ + bio(3)
+ +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + -- cgit v1.2.3