Revert f56158b2 "[doc] string pages improved" for specific files where
[scilab.git] / scilab / modules / string / help / en_US / strsplit.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  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
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" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="strsplit" xml:lang="en">
17     <refnamediv>
18         <refname>strsplit</refname>
19         <refpurpose>split a string into a vector of strings</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>
24             v = strsplit(str,ind)
25             [v, matched_separators] = strsplit(str)
26             [v, matched_separators] = strsplit(str, matrix_of_strings, limit)
27             [v, matched_separators] = strsplit(str, regexp_pattern, limit)
28         </synopsis>
29     </refsynopsisdiv>
30     <refsection>
31         <title>Arguments</title>
32         <variablelist>
33             <varlistentry>
34                 <term>str</term>
35                 <listitem>
36                     <para>a character string to split.</para>
37                 </listitem>
38             </varlistentry>
39             <varlistentry>
40                 <term>ind</term>
41                 <listitem>
42                     <para>
43                         a vector of strictly increasing indices in the interval
44                         <literal>[1 length(str)-1]</literal>.
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>v</term>
50                 <listitem>
51                     <para>
52                         the resulting column vector of string (dimension &gt;<literal>size(ind,'*')+1</literal>).
53                     </para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>matched_separators</term>
58                 <listitem>
59                     <para>
60                         a column vector of the matched separators.
61                     </para>
62                 </listitem>
63             </varlistentry>
64             <varlistentry>
65                 <term>matrix_of_strings</term>
66                 <listitem>
67                     <para>
68                         a matrix of strings to search in <varname>str</varname>.
69                     </para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>regexp_pattern</term>
74                 <listitem>
75                     <para>a regular expression pattern.</para>
76                 </listitem>
77             </varlistentry>
78             <varlistentry>
79                 <term>limit</term>
80                 <listitem>
81                     <para>maximum of limit elements.</para>
82                 </listitem>
83             </varlistentry>
84         </variablelist>
85     </refsection>
86     <refsection>
87         <title>Description</title>
88         <para>
89             <code>v= strsplit(str, ind)</code> splits the string
90             <varname>str</varname> into a vector of strings at the points given by the
91             indices in <varname>ind</varname> (after each characters pointed to by the
92             index in <varname>ind</varname>).
93         </para>
94         <para>
95             <code>strsplit(str)</code> returns same thing as
96             <code>strsplit(str,1:length(str)-1).</code>
97         </para>
98         <para>
99             <code>strsplit(str, regexp_pattern, limit)</code> returns an
100             column vector of strings, each of which is a substring of
101             <varname>str</varname> formed by splitting it on boundaries formed
102             by the case-sensitive regular expression pattern.
103         </para>
104         <para>
105             If there are <literal>n</literal> occurrences of pattern, the
106             returned array will contain <literal>n+1</literal> items.
107         </para>
108         <para>
109             For example, if there is no occurrence of pattern, an array with
110             only one element will be returned. Of course, this is also true if <varname>str</varname> is empty.
111         </para>
112         <para>
113             If <varname>limit</varname> is set, the returned array will contain
114             a maximum of limit elements with the last element containing the
115             whole rest of string.
116         </para>
117         <para>
118             <code>strsplit(str, matrix_of_strings, limit)</code> splits
119             <varname>str</varname> on any of elements. It allows to
120             split on different separators for users without regexp knowledge.
121         </para>
122         <para>
123             If <code>strsplit()</code> is called with a second output
124             argument, the column vector of the matched separators is returned.
125         </para>
126     </refsection>
127     <refsection>
128         <title>Examples</title>
129         <programlisting role="example"><![CDATA[
130 S='strsplit splits a string into a vector of strings';
131 strsplit(S,[15 25 30])
132 ind=strindex(S,' ')
133
134 [r_1, r_2] = strsplit("abcd")
135
136 [r_1, r_2] = strsplit("root:x:0:0:root:/root:/bin/bash",":",5)
137
138 [r_1, r_2] = strsplit("abc,def:ijk,:lmo","/:|,/")
139
140 [r_1, r_2] = strsplit("abc,def:ijk,:lmo",[":";","])
141
142 strsplit("abcdef2ghijkl3mnopqr6stuvw7xyz","/\d+/")
143
144 [r_1, r_2] = strsplit("abcdef2ghijkl3mnopqr6stuvw7xyz","/\d+/",2)
145  ]]></programlisting>
146     </refsection>
147     <refsection role="see also">
148         <title>See also</title>
149         <simplelist type="inline">
150             <member>
151                 <link linkend="part"> part</link>
152             </member>
153             <member>
154                 <link linkend="strcat"> strcat</link>
155             </member>
156             <member>
157                 <link linkend="tokens"> tokens</link>
158             </member>
159             <member>
160                 <link linkend="regexp"> regexp</link>
161             </member>
162         </simplelist>
163     </refsection>
164 </refentry>