Revert f56158b2 "[doc] string pages improved" for specific files where
[scilab.git] / scilab / modules / string / help / en_US / tokens.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA -
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2020 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:db="http://docbook.org/ns/docbook"
18           xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="tokens">
19     <refnamediv>
20         <refname>tokens</refname>
21         <refpurpose>
22             Splits a string using separators and gives its chunks
23         </refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             Chunks = tokens(str)
29             Chunks = tokens(str, separators)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>str</term>
37                 <listitem>
38                     A single string to be split. It can include extended UTF-8 international characters.
39                     <para/>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>separators</term>
44                 <listitem>
45                     Vector of characters. Default value =
46                     <literal>[" ", ascii(9)]</literal>, ascii(9) being the horizontal tab.
47                     <para/>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>Chunks</term>
52                 <listitem>
53                     Column vector: Pieces of the split string.
54                     <para/>
55                 </listitem>
56             </varlistentry>
57         </variablelist>
58     </refsection>
59     <refsection>
60         <title>Description</title>
61         <para>
62             <literal>tokens(…)</literal> searches the string for given separator(s),
63             and splits it into chunks. Chunks are free of separators.
64             Consecutive separators are merged.
65         </para>
66     </refsection>
67     <refsection>
68         <title>Examples</title>
69         <programlisting role="example"><![CDATA[
70 tokens("The given   text")
71
72 tokens("SCI/demos/scicos", "/")'
73
74 tokens("Επιστήμη και καινοτομία", ["α"," "])'
75
76 nbsp = ascii(160); // non-breakable space
77 t = "the" + nbsp + "given   text"
78 tokens(t)
79  ]]></programlisting>
80     <screen><![CDATA[
81 --> tokens('The given   text')
82  ans  =
83   "The"
84   "given"
85   "text"
86
87
88 --> tokens('SCI/demos/scicos', '/')'
89  ans  =
90   "SCI"  "demos"  "scicos"
91
92
93 --> tokens("Επιστήμη και καινοτομία", ["α"," "])'
94  ans  =
95   "Επιστήμη"  "κ"  "ι"  "κ"  "ινοτομί"
96
97
98 --> nbsp = ascii(160); // non-breakable space
99 --> t = "the" + nbsp + "given   text"
100  t  =
101   "the given   text"
102
103 --> tokens(t)
104  ans  =
105   "the given"
106   "text"
107 ]]></screen>
108     </refsection>
109     <refsection role="see also">
110         <title>See also</title>
111         <simplelist type="inline">
112             <member>
113                 <link linkend="strsplit">strsplit</link>
114             </member>
115             <member>
116                 <link linkend="regexp">regexp</link>
117             </member>
118             <member>
119                 <link linkend="strindex">strindex</link>
120             </member>
121             <member>
122                 <link linkend="tokenpos">tokenpos</link>
123             </member>
124         </simplelist>
125     </refsection>
126 </refentry>