| <head> |
| <title>string(3) - Plan 9 from User Space</title> |
| <meta content="text/html; charset=utf-8" http-equiv=Content-Type> |
| </head> |
| <body bgcolor=#ffffff> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=10><td> |
| <tr><td width=20><td> |
| <tr><td width=20><td><b>STRING(3)</b><td align=right><b>STRING(3)</b> |
| <tr><td width=20><td colspan=2> |
| <br> |
| <p><font size=+1><b>NAME </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| 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<br> |
| |
| </table> |
| <p><font size=+1><b>SYNOPSIS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>#include <u.h><br> |
| #include <libc.h><br> |
| #include <String.h> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>String* s_new(void)<br> |
| void s_free(String *s)<br> |
| String* s_newalloc(int n)<br> |
| String* s_array(char *p, int n)<br> |
| String* s_grow(String *s, int n) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void s_putc(String *s, int c)<br> |
| void s_terminate(String *s)<br> |
| String* s_reset(String *s)<br> |
| String* s_restart(String *s)<br> |
| String* s_append(String *s, char *p)<br> |
| String* s_nappend(String *s, char *p, int n)<br> |
| String* s_memappend(String *s, char *p, int n)<br> |
| String* s_copy(char *p)<br> |
| String* s_parse(String *s1, String *s2)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void s_tolower(String *s) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>String* s_incref(String *s)<br> |
| String* s_unique(String *s) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>Sinstack* s_allocinstack(char *file)<br> |
| void s_freeinstack(Sinstack *stack)<br> |
| char* s_rdinstack(Sinstack *stack, String *s) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>#include <bio.h> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>int s_read(Biobuf *b, String *s, int n)<br> |
| char* s_read_line(Biobuf *b, String *s)<br> |
| char* s_getline(Biobuf *b, String *s)<br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>DESCRIPTION </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| These routines manipulate extensible strings. The basic type is |
| <tt><font size=+1>String</font></tt>, 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 |
| <i>s_parse</i>) or new characters will be added (for <i>s_putc</i>, |
| <i>s_append</i>, and <i>s_nappend</i>). The structure, and a few useful macros |
| are:<br> |
| <tt><font size=+1>typedef struct String {<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| Lock;<br> |
| char*base;/* base of String */<br> |
| char*end;/* end of allocated space+1 */<br> |
| char*ptr;/* ptr into String */<br> |
| ...<br> |
| |
| </table> |
| |
| </table> |
| } String;<br> |
| #define s_to_c(s) ((s)−>base)<br> |
| #define s_len(s) ((s)−>ptr−(s)−>base)<br> |
| #define s_clone(s) s_copy((s)−>base)<br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <i>S_to_c</i> is used when code needs a reference to the character array. |
| Using <tt><font size=+1>s−>base</font></tt> directly is frowned upon since it exposes too much |
| of the implementation.<br> |
| <p><font size=+1><b>Allocation and freeing </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| A string must be allocated before it can be used. One normally |
| does this using <i>s_new</i>, giving the string an initial allocation |
| of 128 bytes. If you know that the string will need to grow much |
| longer, you can use <i>s_newalloc</i> instead, specifying the number |
| of bytes in the initial allocation. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_free</i> causes both the string and its character array to be freed. |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_grow</i> 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. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_array</i> 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.<br> |
| <p><font size=+1><b>Filling the string </b></font><br> |
| After its initial allocation, the string points to the beginning |
| of an allocated array of characters starting with NUL. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_putc</i> writes a character into the string at the pointer and advances |
| the pointer to point after it. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_terminate</i> writes a NUL at the pointer but doesn’t advance it. |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_restart</i> resets the pointer to the begining of the string but |
| doesn’t change the contents. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_reset</i> is equivalent to <i>s_restart</i> followed by <i>s_terminate</i>. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_append</i> and <i>s_nappend</i> 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. <i>S_memappend</i> is like <i>s_nappend</i> |
| but doesn’t stop at a NUL. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| If you know the initial character array to be copied into a string, |
| you can allocate a string and copy in the bytes using <i>s_copy</i>. |
| This is the equivalent of a <i>s_new</i> followed by an <i>s_append</i>. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_parse</i> copies the next white space terminated token from <i>s1</i> to |
| the end of <i>s2</i>. 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. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_tolower</i> converts all ASCII characters in the string to lower |
| case.<br> |
| <p><font size=+1><b>Multithreading </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_incref</i> is used by multithreaded programs to avoid having the |
| string memory released until the last user of the string performs |
| an <i>s_free</i>. <i>S_unique</i> returns a unique copy of the string: if the |
| reference count it 1 it returns the string, otherwise it returns |
| an <i>s_clone</i> of the string.<br> |
| <p><font size=+1><b>Bio interaction </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_read</i> reads the requested number of characters through a <i>Biobuf</i> |
| 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. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_read_line</i> 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. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_getline</i> reads up to the next newline, appends the input to <i>s</i>, |
| and returns a pointer to the beginning of the bytes read. Leading |
| spaces and tabs and the trailing newline are all discarded. <i>S_getline</i> |
| discards blank lines and lines beginning with <tt><font size=+1>#</font></tt>. <i>S_getline</i> ignores |
| newlines escaped by immediately-preceding |
| backslashes. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>S_allocinstack</i> allocates an input stack with the single file <i>file</i> |
| open for reading. <i>S_freeinstack</i> frees an input stack. <i>S_rdinstack</i> |
| reads a line from an input stack. It follows the same rules as |
| <i>s_getline</i> except that when it encounters a line of the form <tt><font size=+1>#include</font></tt> |
| <i>newfile</i>, <i>s_getline</i> pushes <i>newfile</i> onto the input stack, |
| postponing further reading of the current file until <i>newfile</i> has |
| been read. The input stack has a maximum depth of 32 nested include |
| files.<br> |
| |
| </table> |
| <p><font size=+1><b>SOURCE </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>/usr/local/plan9/src/libString<br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>SEE ALSO </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <a href="../man3/bio.html"><i>bio</i>(3)</a><br> |
| |
| </table> |
| |
| <td width=20> |
| <tr height=20><td> |
| </table> |
| <!-- TRAILER --> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=15><td width=10><td><td width=10> |
| <tr><td><td> |
| <center> |
| <a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> |
| </center> |
| </table> |
| <!-- TRAILER --> |
| </body></html> |
