Revert f56158b2 "[doc] string pages improved" for specific files where
[scilab.git] / scilab / modules / string / help / en_US / strindex.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"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:id="strindex" xml:lang="en">
20     <refnamediv>
21         <refname>strindex</refname>
22         <refpurpose>
23             search position of a character string in another string
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntax</title>
28         <synopsis>
29             [ind, which] = strindex(haystack, needle)
30             [ind, which] = strindex(haystack, needle, "regexp")
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection>
34         <title>Arguments</title>
35         <variablelist>
36             <varlistentry>
37                 <term>haystack</term>
38                 <listitem>
39                     <para>
40                         a character string. The string where to search
41                         occurrences of <varname>needle</varname>.
42                     </para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>needle</term>
47                 <listitem>
48                     <para>
49                         a character string or character string vector. The
50                         string(s) to search in <varname>haystack</varname>.
51                     </para>
52                 </listitem>
53             </varlistentry>
54             <varlistentry>
55                 <term>ind</term>
56                 <listitem>
57                     <para>a vector of indexes.</para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>which</term>
62                 <listitem>
63                     <para>a vector of indexes.</para>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>"regexp" | "r" flag</term>
68                 <listitem>
69                     <para>
70                         Then <varname>needle</varname> elements are used as regular expressions.
71                     </para>
72                 </listitem>
73             </varlistentry>
74         </variablelist>
75     </refsection>
76     <refsection>
77         <title>Description</title>
78         <para>
79             <function>strindex</function> searches indexes where
80             <literal>needle(i)</literal> is found in <varname>haystack</varname>.
81         </para>
82         <para>
83             For each <literal>k</literal> it exist an <literal>i</literal> such
84             that <code>part(haystack,ind(k)+(0:length(needle(i))-1))</code> is
85             the same string than <literal>needle(i)</literal>. If
86             <varname>which</varname> argument is required it contains these
87             <literal>i</literal>. When using the third parameter <literal>"r"</literal>, the <varname>needle</varname>
88             should be a string of regular expression. And then <function>strindex</function> is going to
89             match it with <varname>haystack</varname> according to the regular express rules.
90         </para>
91         <para>
92             <function>strindex</function> without regular expression argument is
93             based on Knuth-Morris-Pratt algorithm.
94         </para>
95         <para>
96             This algorithm is more powerful than that used in Scilab 4.x. In
97             some special case, result can be different.
98         </para>
99         <para>Example:</para>
100         <para>// Scilab 5.x</para>
101         <para>--&gt;[k,w]=strindex('aab',['a','ab'])</para>
102         <para>w = 1. 1. 2. k = 1. 2. 2.</para>
103         <para>// Scilab 4.x</para>
104         <para>--&gt;[k,w]=strindex('aab',['a','ab'])</para>
105         <para>w = 1. 1. k = 1. 2.</para>
106         <para>
107             The rules of regular expression are similar to Perl language. For a
108             quick start, see <ulink url="http://perldoc.perl.org/perlrequick.html">http://perldoc.perl.org/perlrequick.html</ulink>.
109             For a more in-depth tutorial on, see <ulink url="http://perldoc.perl.org/perlretut.html">http://perldoc.perl.org/perlretut.html</ulink>
110             and for the reference page, see <ulink url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>
111         </para>
112     </refsection>
113     <refsection>
114         <title>Examples</title>
115         <programlisting role="example"><![CDATA[
116 k=strindex('SCI/demos/scicos','/')
117 k=strindex('SCI/demos/scicos','SCI/')
118 k=strindex('SCI/demos/scicos','!')
119 k=strindex('aaaaa','aa')
120 k=strindex('SCI/demos/scicos',['SCI','sci'])
121 [k,w]=strindex('1+3*abc/2.33',['+','-','*','/'])
122 k=strindex('2' ,'/2(]*)?$\1/' ,'r')
123  ]]></programlisting>
124     </refsection>
125     <refsection role="see also">
126         <title>See also</title>
127         <simplelist type="inline">
128             <member>
129                 <link linkend="string">string</link>
130             </member>
131             <member>
132                 <link linkend="strings">strings</link>
133             </member>
134             <member>
135                 <link linkend="regexp">regexp</link>
136             </member>
137             <member>
138                 <link linkend="strsubst">strsubst</link>
139             </member>
140         </simplelist>
141     </refsection>
142 </refentry>