Documentation on preg_match and preg_match_all incorrectly describes meaning
of offset parameter. Using offset parameter is NOT equivalent to passing
substr($subject, $offset) to preg_match in place of the subject string.
Although I have karma to commit the patch, I would like it to be "approved"
first, since I never commited to "en" tree.
Index: preg-match-all.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/pcre/functions/preg-match-all.xml,v
retrieving revision 1.13
diff -u -r1.13 preg-match-all.xml
--- preg-match-all.xml 3 Aug 2004 15:51:10 -0000 1.13
+++ preg-match-all.xml 12 Oct 2004 06:35:21 -0000
@@ -131,13 +131,23 @@
<para>
Normally, the search starts from the beginning of the subject string. The
optional parameter <parameter>offset</parameter> can be used to specify
- the alternate place from which to start the search. It is equivalent to
- passing <function>substr</function>($subject, $offset) to
- <function>preg_match</function> in place of the subject string.
+ the alternate place from which to start the search.
The <parameter>offset</parameter> parameter is available since
<literal>PHP</literal> 4.3.3.
</para>
+ <note>
+ <para>
+ Using <parameter>offset</parameter> is not equivalent to
+ passing <function>substr</function>($subject, $offset) to
+ <function>preg_match_all</function> in place of the subject string,
+ because <parameter>pattern</parameter> can contain assertions such as
+ <emphasis>^</emphasis>, <emphasis>$</emphasis> or
+ <emphasis>(?<=x)</emphasis>. See <function>preg_match</function> for
+ examples.
+ </para>
+ </note>
+
<para>
Returns the number of full pattern matches (which might be zero),
or &false; if an error occurred.
Index: preg-match.xml
===================================================================
RCS file: /repository/phpdoc/en/reference/pcre/functions/preg-match.xml,v
retrieving revision 1.15
diff -u -r1.15 preg-match.xml
--- preg-match.xml 10 Aug 2004 16:30:20 -0000 1.15
+++ preg-match.xml 12 Oct 2004 06:35:24 -0000
@@ -51,12 +51,71 @@
<para>
Normally, the search starts from the beginning of the subject string. The
optional parameter <parameter>offset</parameter> can be used to specify
- the alternate place from which to start the search. It is equivalent to
- passing <function>substr</function>($subject, $offset) to
- <function>preg_match</function> in place of the subject string.
+ the alternate place from which to start the search.
The <parameter>offset</parameter> parameter is available since
PHP 4.3.3.
</para>
+ <note>
+ <para>
+ Using <parameter>offset</parameter> is not equivalent to
+ passing <function>substr</function>($subject, $offset) to
+ <function>preg_match</function> in place of the subject string, because
+ <parameter>pattern</parameter> can contain assertions such as
+ <emphasis>^</emphasis>, <emphasis>$</emphasis> or
+ <emphasis>(?<=x)</emphasis>. Compare :
+ </para>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $subject = "abcdef";
+ $pattern = '/^def/';
+ preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
+ print_r($matches);
+?>
+]]>
+ </programlisting>
+ <para>
+ will produce
+ </para>
+ <screen>
+<![CDATA[
+Array
+(
+)
+]]>
+ </screen>
+ <para>
+ and
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $subject = "abcdef";
+ $pattern = '/^def/';
+ preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);
+ print_r($matches);
+?>
+]]>
+ </programlisting>
+ <para>
+ will produce
+ </para>
+ <screen>
+<![CDATA[
+Array
+(
+ [0] => Array
+ (
+ [0] => def
+ [1] => 0
+ )
+
+)
+]]>
+ </screen>
+ </informalexample>
+ </note>
<para>
<function>preg_match</function> returns the number of times
