* A new output argument to the function regexp has been added to retrieve
[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  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <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="regexp" xml:lang="en">
14     <refnamediv>
15         <refname>regexp</refname>
16         <refpurpose>find a substring that matches the regular expression
17             string
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>[start]=regexp(input,pattern,[flag])
23             [start,end,match]=regexp(input,pattern,[flag])
24             [start,end]=regexp(input,pattern,[flag])
25             [start,end,match]=regexp(input,pattern,[flag])
26             [start,end,match,foundString]=regexp(input,pattern,[flag])
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>input</term>
34                 <listitem>
35                     <para>a string.</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>pattern</term>
40                 <listitem>
41                     <para>a character string (under the rules of regular
42                         expression)
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>start</term>
48                 <listitem>
49                     <para>the starting index of each substring of str that matches the
50                         regular expression string pattern
51                     </para>
52                 </listitem>
53             </varlistentry>
54             <varlistentry>
55                 <term>end</term>
56                 <listitem>
57                     <para>the ending index of each substring of str that matches the
58                         regular expression string pattern
59                     </para>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>match</term>
64                 <listitem>
65                     <para>the text of each substring of str that matches
66                         <literal>pattern</literal>.
67                     </para>
68                 </listitem>
69             </varlistentry>
70             <varlistentry>
71                 <term>foundString</term>
72                 <listitem>
73                     <para>
74                         The captured parenthesized <literal>subpatterns</literal>.
75                     </para>
76                 </listitem>
77             </varlistentry>
78             <varlistentry>
79                 <term>[flag]</term>
80                 <listitem>
81                     <para>'o' for matching the pattern once .</para>
82                 </listitem>
83             </varlistentry>
84         </variablelist>
85     </refsection>
86     <refsection>
87         <title>Description</title>
88         <para>The rules of regular expression are similar to perl language. For a
89             quick start , see <ulink url="http://perldoc.perl.org/perlrequick.html">http://perldoc.perl.org/perlrequick.html</ulink>.
90             For a more in-depth tutorial on , see <ulink url="http://perldoc.perl.org/perlretut.html">http://perldoc.perl.org/perlretut.html</ulink>
91             and for the reference page, see <ulink url="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</ulink>
92         </para>
93         <para>A difference with Perl is that matching a position but no character
94             (for example, with /^/ or /(?=o)/) is a successful match in Perl but not
95             in Scilab.
96         </para>
97     </refsection>
98     <refsection>
99         <title>Examples</title>
100         <programlisting role="example"><![CDATA[ 
101 regexp('xabyabbbz','/ab*/','o')
102 regexp('a!','/((((((((((a))))))))))\041/')
103 regexp('ABCC','/^abc$/i')
104 regexp('ABC','/ab|cd/i')
105 [a b c]=regexp('XABYABBBZ','/ab*/i')
106
107 piString="3.14"
108 [a,b,c,piStringSplit]=regexp(piString,"/(\d+)\.(\d+)/")
109 disp(piStringSplit(1))
110 disp(piStringSplit(2))
111
112 [a,b,c,d]=regexp('xabyabbbz','/ab(.*)b(.*)/')
113 size(d)
114
115
116
117 // get host name from URL
118 myURL="http://www.scilab.org/download/";
119 [a,b,c,d]=regexp(myURL,'@^(?:http://)?([^/]+)@i')
120
121
122 str='foobar: 2012';
123 // Using named subpatterns
124 [a,b,c,d]=regexp(str,'/(?P<name>\w+): (?P<digit>\d+)/')
125 d(1)=="foobar"
126 d(2)=="2012"
127  ]]></programlisting>
128     </refsection>
129     <refsection role="see also">
130         <title>See Also</title>
131         <simplelist type="inline">
132             <member>
133                 <link linkend="strindex">strindex</link>
134             </member>
135         </simplelist>
136     </refsection>
137     <refsection>
138         <title>History</title>
139         <revhistory>
140             <revision>
141                 <revnumber>5.4.10</revnumber>
142                 <revremark>A new output argument, foundString, has been added to retrieve subpatterns matches.</revremark>
143             </revision>
144         </revhistory>
145     </refsection>
146     
147 </refentry>