Revert f56158b2 "[doc] string pages improved" for specific files where
[scilab.git] / scilab / modules / string / help / en_US / regexp.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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xml:id="regexp" xml:lang="en">
20     <refnamediv>
21         <refname>regexp</refname>
22         <refpurpose>
23             find a substring that matches the regular expression string
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntax</title>
28         <synopsis>
29             [start, final, match, foundString] = regexp(input, pattern)
30             [start, final, match, foundString] = regexp(input, pattern, "once")
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection>
34         <title>Arguments</title>
35         <variablelist>
36             <varlistentry>
37                 <term>input</term>
38                 <listitem>
39                     <para>a string.</para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>pattern</term>
44                 <listitem>
45                     <para>
46                         a character string (under the rules of regular expression).
47                     </para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>start</term>
52                 <listitem>
53                     <para>
54                         the starting index of each substring of
55                         <varname>input</varname> that matches the regular
56                         expression string <varname>pattern</varname>.
57                     </para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>final</term>
62                 <listitem>
63                     <para>
64                         the ending index of each substring of
65                         <varname>input</varname> that matches the regular
66                         expression string <varname>pattern</varname>.
67                     </para>
68                 </listitem>
69             </varlistentry>
70             <varlistentry>
71                 <term>match</term>
72                 <listitem>
73                     <para>
74                         the text of each substring of <varname>input</varname>
75                         that matches <varname>pattern</varname>.
76                     </para>
77                 </listitem>
78             </varlistentry>
79             <varlistentry>
80                 <term>foundString</term>
81                 <listitem>
82                     <para>
83                         the captured parenthesized <literal>subpatterns</literal>.
84                     </para>
85                 </listitem>
86             </varlistentry>
87             <varlistentry>
88                 <term>"once | "o" flag</term>
89                 <listitem>
90                     <para>
91                         <literal>'o'</literal> for matching the pattern only once.
92                     </para>
93                 </listitem>
94             </varlistentry>
95         </variablelist>
96     </refsection>
97     <refsection>
98         <title>Description</title>
99         <para>
100             The rules of regular expression are similar to Perl language. For a
101             quick start, see
102             <ulink url="http://perldoc.perl.org/perlrequick.html">http://perldoc.perl.org/perlrequick.html</ulink>.
103             For a more in-depth tutorial on, see
104             <ulink url="http://perldoc.perl.org/perlretut.html">http://perldoc.perl.org/perlretut.html</ulink>
105             and for the reference page, see
106             <ulink url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>
107         </para>
108         <para>
109             A difference with Perl is that matching a position but no character
110             (for example, with <literal>/^/</literal> or
111             <literal>/(?=o)/</literal>) is a successful match in Perl but not
112             in Scilab.
113         </para>
114     </refsection>
115     <refsection>
116         <title>Examples</title>
117         <programlisting role="example"><![CDATA[
118 regexp('xabyabbbz','/ab*/','o')
119 regexp('a!','/((((((((((a))))))))))\041/')
120 regexp('ABCC','/^abc$/i')
121 regexp('ABC','/ab|cd/i')
122 [a b c]=regexp('XABYABBBZ','/ab*/i')
123
124 piString="3.14"
125 [a,b,c,piStringSplit]=regexp(piString,"/(\d+)\.(\d+)/")
126 disp(piStringSplit(1))
127 disp(piStringSplit(2))
128
129 [a,b,c,d]=regexp('xabyabbbz','/ab(.*)b(.*)/')
130 size(d)
131
132 // get host name from URL
133 myURL="http://www.scilab.org/download/";
134 [a,b,c,d]=regexp(myURL,'@^(?:http://)?([^/]+)@i')
135
136 str='foobar: 2012';
137 // Using named subpatterns
138 [a,b,c,d]=regexp(str,'/(?P<name>\w+): (?P<digit>\d+)/')
139 d(1)=="foobar"
140 d(2)=="2012"
141
142     ]]></programlisting>
143     </refsection>
144     <refsection role="see also">
145         <title>See also</title>
146         <simplelist type="inline">
147             <member>
148                 <link linkend="strindex">strindex</link>
149             </member>
150         </simplelist>
151     </refsection>
152     <refsection>
153         <title>History</title>
154         <revhistory>
155             <revision>
156                 <revnumber>5.4.0</revnumber>
157                 <revremark>
158                     A new output argument, foundString, has been added to retrieve subpatterns matches.
159                 </revremark>
160             </revision>
161         </revhistory>
162     </refsection>
163 </refentry>