Revert f56158b2 "[doc] string pages improved" for specific files where
[scilab.git] / scilab / modules / string / help / en_US / grep.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:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:id="grep" xml:lang="en">
20     <refnamediv>
21         <refname>grep</refname>
22         <refpurpose>find matches of a string in a vector of strings</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             [row, which] = grep(haystack, needle )
28             [row, which] = grep(haystack, needle, "regexp" )
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Arguments</title>
33         <variablelist>
34             <varlistentry>
35                 <term>haystack</term>
36                 <listitem>
37                     <para>a row vector of character strings.</para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>needle</term>
42                 <listitem>
43                     <para>
44                         a character string or a row vector of character strings. The
45                         string(s) to search in <varname>haystack</varname>.
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>row</term>
51                 <listitem>
52                     <para>
53                         a vector of indices: row where a match has been found or an
54                         empty matrix if no match found.
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>which</term>
60                 <listitem>
61                     <para>
62                         a vector of indices: index of <varname>needle</varname> string found
63                         or an empty matrix if no match found.
64                     </para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>"regexp" | "r" flag</term>
69                 <listitem>
70                     <para>
71                         single character: Then <varname>needle</varname> elements are used as
72                         <emphasis role="bold">r</emphasis>egular expressions.
73                     </para>
74                 </listitem>
75             </varlistentry>
76         </variablelist>
77     </refsection>
78     <refsection>
79         <title>Description</title>
80         <para>
81             For each entry of <varname>haystack</varname>, <function>grep</function>
82             searches if at least a string in <varname>needle</varname> which matches a
83             substring. The <varname>haystack</varname> entries index where at least a
84             match has been found are returned in the <varname>row</varname> output
85             argument. The optional <varname>which</varname> output argument gives the
86             index of first string of <varname>needle</varname> found.
87         </para>
88         <para>
89             When using the third parameter <varname>flag</varname><literal>="r"</literal>, the
90             <varname>needle</varname> is expected to be a regular expression string.
91             In this case, <function>grep</function> uses the
92             <varname>needle</varname> as a regular expression and compares it
93             against <varname>haystack</varname> according to the regular expressions
94             rules. See the <link linkend="regexp">regexp</link> function for details about
95             regular expressions.
96         </para>
97     </refsection>
98     <refsection>
99         <title>Examples</title>
100         <para><emphasis role="bold">Example #1</emphasis></para>
101         <para>
102             In the following example, we search one or two strings in a text,
103             which is stored in the <varname>txt</varname> variable.
104         </para>
105         <programlisting role="example"><![CDATA[
106 txt=['find matches of a string in a vector of strings'
107      'search position of a character string in another string'
108      'Compare Strings'];
109
110 grep(txt,'strings')
111 grep(txt,['strings' 'Strings'])
112
113 [r,w]=grep(txt,['strings' 'Strings'])
114  ]]></programlisting>
115         <para/>
116
117         <para><emphasis role="bold">Example #2</emphasis></para>
118         <para>In the following example, we perform regexp searches.</para>
119         <programlisting role="example"><![CDATA[
120 str = ["hat";"cat";"hhat";"chat";"hcat";"ccchat";"at";"dog"]
121
122 grep(str,'/[hc]+at/','r')
123 grep(str,'/[hc]?at/','r')
124 grep(str,'/cat|dog/','r')
125  ]]></programlisting>
126     </refsection>
127     <refsection role="see also">
128         <title>See also</title>
129         <simplelist type="inline">
130             <member>
131                 <link linkend="strindex">strindex</link>
132             </member>
133             <member>
134                 <link linkend="regexp">regexp</link>
135             </member>
136             <member>
137                 <link linkend="find">find</link>
138             </member>
139             <member>
140                 <link linkend="vectorfind">vectorfind</link>
141             </member>
142         </simplelist>
143     </refsection>
144 </refentry>