245 lines
11 KiB
HTML
245 lines
11 KiB
HTML
|
<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>
|