1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
-
- This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
- project.
-
- Copyright (C) 1998-2018 OpenLink Software
-
- This project is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; only version 2 of the License, dated June 1991.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-->
<refentry id="fn_regexp_instr">
<refmeta>
<refentrytitle>regexp_instr</refentrytitle>
<refmiscinfo>string</refmiscinfo>
</refmeta>
<refnamediv>
<refname>regexp_instr</refname>
<refpurpose>Returns the first position of the occurrence of a regular-expression pattern in a given string.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_regexp_instr">
<funcprototype id="fproto_regexp_instr">
<funcdef>integer <function>regexp_instr</function></funcdef>
<paramdef>in <parameter>source_string</parameter> varchar</paramdef>
<paramdef>in <parameter>pattern</parameter> varchar</paramdef>
<paramdef><optional>in <parameter>start_position</parameter> integer</optional></paramdef>
<paramdef><optional>in <parameter>occurrence</parameter> integer</optional></paramdef>
<paramdef><optional>in <parameter>return_option</parameter> integer</optional></paramdef>
<paramdef><optional>in <parameter>match_parameter</parameter> integer</optional></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc"><title>Description</title>
<para>This function looks for a pattern and returns the first position of the
pattern. Optionally, you can indicate the <parameter>start_position</parameter>
you want to begin the search. The <parameter>occurrence</parameter> parameter
defaults to 1 unless you indicate that you are looking for a subsequent occurrence.
The default value of the <parameter>return_option</parameter> is 0, which returns
the starting position of the pattern; a value of 1 returns the starting position of
the next character following the match. </para>
<para>This function returns the starting position of a pattern, so it works much
like the familiar INSTR function. The main difference between the two functions
is that REGEXP_INSTR lets you specify a pattern instead of a specific search string;
thus providing greater versatility. </para>
</refsect1>
<refsect1 id="params_regexp_instr"><title>Parameters</title>
<refsect2><title>source_string</title>
<para>The string to search.</para></refsect2>
<refsect2><title>pattern</title>
<para>The regular expression to match.</para></refsect2>
<refsect2><title>start_position</title>
<para>The position to begin the search from.</para></refsect2>
<refsect2><title>occurrence</title>
<para>Defaulting to 1, this parameter describes how many occurrences to look for.</para></refsect2>
<refsect2><title>return_option</title>
<para>Default is 0, which returns the starting position of the pattern; a value of 1 returns the starting position of the
next character following the match.</para></refsect2>
<refsect2><title>match_parameter</title>
<para>Match parameter value.</para></refsect2>
</refsect1>
<refsect1 id="ret_regexp_instr"><title>Returns</title>
<para>This function returns the a substring matching the regular expression.</para>
</refsect1>
<refsect1 id="examples"><title>Examples</title>
<example id="ex_regexp_instr">
<title>Examples</title>
<para>
This example uses <function>REGEXP_INSTR()</function> to return the starting
position of the five-digit zip-code pattern within the string Joe Smith, 10045 Berry
Lane, San Joseph, CA 91234. If the regular expression is written
as :digit:?{5}, you will get the house number's starting position instead of the zip
code's, because 10045 is the first occurrence of five consecutive digits. Therefore,
you must anchor the expression to the end of the line, as indicated with
the $ metacharacter, and the function will display the starting position of
the zip code regardless of the number of digits for the house number. </para>
<programlisting><![CDATA[
SELECT REGEXP_INSTR('Joe Smith, 10045 Berry Lane, San Joseph, CA 91234',
'[[:digit:]]{5}\$')
AS rx_instr;
RX_INSTR
----------
45
]]></programlisting>
</example>
</refsect1>
<refsect1 id="seealso_regexp_instr"><title>See Also</title>
<para><link linkend="fn_regexp_match"><function>regexp_match()</function></link></para>
<para><link linkend="fn_regexp_like"><function>regexp_like()</function></link></para>
<para><link linkend="fn_regexp_parse"><function>regexp_parse()</function></link></para>
<para><link linkend="fn_regexp_replace"><function>regexp_replace()</function></link></para>
<para><link linkend="fn_regexp_substr"><function>regexp_substr()</function></link></para>
</refsect1>
</refentry>
|
