1    <refentry id="reftok">
2
3      <refmeta>
4	<refentrytitle>ne_token</refentrytitle>
5	<manvolnum>3</manvolnum>
6      </refmeta>
7
8      <refnamediv>
9	<refname>ne_token</refname>
10	<refname>ne_qtoken</refname>
11	<refpurpose>string tokenizers</refpurpose>
12      </refnamediv>
13      
14      <refsynopsisdiv>
15	
16	<funcsynopsis>
17
18	  <funcsynopsisinfo>#include &lt;ne_string.h&gt;</funcsynopsisinfo>
19
20	  <funcprototype>
21	    <funcdef>char *<function>ne_token</function></funcdef>
22	    <paramdef>char **<parameter>str</parameter></paramdef>
23	    <paramdef>char <parameter>sep</parameter></paramdef>
24	  </funcprototype>
25
26	  <funcprototype>
27	    <funcdef>char *<function>ne_qtoken</function></funcdef>
28	    <paramdef>char **<parameter>str</parameter></paramdef>
29	    <paramdef>char <parameter>sep</parameter></paramdef>
30	    <paramdef>const char *<parameter>quotes</parameter></paramdef>
31	  </funcprototype>
32
33	</funcsynopsis>
34	
35      </refsynopsisdiv>
36
37      <refsect1>
38	<title>Description</title>
39
40	<!-- FIXME: italics on tokenize -->
41
42	<para><function>ne_token</function> and
43<function>ne_qtoken</function> tokenize the string at the location
44stored in the pointer <parameter>str</parameter>.  Each time the
45function is called, it returns the next token, and modifies the
46<parameter>str</parameter> pointer to point to the remainer of the
47string, or &null; if there are no more tokens in the string.  A token
48is delimited by the separator character <parameter>sep</parameter>; if
49<function>ne_qtoken</function> is used any quoted segments of the
50string are skipped when searching for a separator.  A quoted segment
51is enclosed in a pair of one of the characters given in the
52<parameter>quotes</parameter> string.</para>
53
54	<para>The string being tokenized is modified each time
55the tokenizing function is called; replacing the next separator
56character with a &nul; terminator.</para>
57
58      </refsect1>
59
60      <refsect1>
61	<title>Examples</title>
62
63	<para>The following function prints out each token in a
64comma-separated string <parameter>list</parameter>, which is
65modified in-place:</para>
66
67	<programlisting>static void splitter(char *list)
68{
69  do {
70    printf("Token: %s\n", ne_token(&amp;list, ','));
71  while (list);
72}</programlisting>
73
74 </refsect1>
75
76    </refentry>
77