From 30a6ab9bdf79fa7dac5975878cd9a0c818708929 Mon Sep 17 00:00:00 2001
From: Matt Li <mazzanet@php.net>
Date: Sun, 25 Dec 2011 02:27:36 +0000
Subject: [PATCH] Fix as per note #106986 and unify format between related
 functions

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@321383 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/strings/functions/stripos.xml  | 26 +++++++++++++-----------
 reference/strings/functions/strpos.xml   | 23 +++++++++++----------
 reference/strings/functions/strripos.xml | 22 ++++++++++++--------
 reference/strings/functions/strrpos.xml  | 19 ++++++++++-------
 reference/strings/functions/strstr.xml   |  2 +-
 5 files changed, 52 insertions(+), 40 deletions(-)

diff --git a/reference/strings/functions/stripos.xml b/reference/strings/functions/stripos.xml
index e8f13f34aa..8fdde710b0 100644
--- a/reference/strings/functions/stripos.xml
+++ b/reference/strings/functions/stripos.xml
@@ -3,7 +3,7 @@
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.stripos">
  <refnamediv>
   <refname>stripos</refname>
-  <refpurpose>Find position of first occurrence of a case-insensitive string</refpurpose>
+  <refpurpose>Find the position of the first occurrence of a case-insensitive substring in a string</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
@@ -15,12 +15,11 @@
    <methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Returns the numeric position of the first occurrence of
-   <parameter>needle</parameter> in the <parameter>haystack</parameter>
-   <type>string</type>.
+   Find the numeric position of the last occurrence of
+   <parameter>needle</parameter> in the <parameter>haystack</parameter> string.
   </para>
   <para>
-   Unlike <function>strpos</function>, <function>stripos</function> is
+   Unlike the <function>strpos</function>, <function>stripos</function> is
    case-insensitive.
   </para>
  </refsect1>
@@ -33,7 +32,7 @@
      <term><parameter>haystack</parameter></term>
      <listitem>
       <para>
-       The string to search in
+       The string to search in.
       </para>
      </listitem>
     </varlistentry>
@@ -54,10 +53,9 @@
      <term><parameter>offset</parameter></term>
      <listitem>
       <para>
-       The optional <parameter>offset</parameter> parameter allows you
-       to specify which character in <parameter>haystack</parameter> to
-       start searching. The position returned is still relative to the
-       beginning of <parameter>haystack</parameter>.
+       If specified, search will start this number of characters counted from
+       the beginning of the string. Unlike <function>strrpos</function> and
+       <function>strripos</function>, the offset cannot be negative.
       </para>
      </listitem>
     </varlistentry>
@@ -68,8 +66,12 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns the position as an integer. If <parameter>needle</parameter> is not found,
-   <function>stripos</function> will return <type>boolean</type> &false;.
+   Returns the position of where the needle exists relative to the beginnning of
+   the <parameter>haystack</parameter> string (independent of offset).
+   Also note that string positions start at 0, and not 1.
+  </para>
+  <para>
+   Returns &false; if the needle was not found.
   </para>
   &return.falseproblem;
  </refsect1>
diff --git a/reference/strings/functions/strpos.xml b/reference/strings/functions/strpos.xml
index 6e4d9a4d04..677acaa8fb 100644
--- a/reference/strings/functions/strpos.xml
+++ b/reference/strings/functions/strpos.xml
@@ -3,7 +3,7 @@
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.strpos">
  <refnamediv>
   <refname>strpos</refname>
-  <refpurpose>Find position of first occurrence of a string</refpurpose>
+  <refpurpose>Find the position of the first occurrence of a substring in a string</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
@@ -15,9 +15,8 @@
    <methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Returns the numeric position of the first occurrence of
-   <parameter>needle</parameter> in the <parameter>haystack</parameter>
-   string.
+   Find the numeric position of the last occurrence of
+   <parameter>needle</parameter> in the <parameter>haystack</parameter> string.
   </para>
  </refsect1>
 
@@ -46,10 +45,9 @@
      <term><parameter>offset</parameter></term>
      <listitem>
       <para>
-       The optional <parameter>offset</parameter> parameter allows you
-       to specify which character in <parameter>haystack</parameter> to
-       start searching. The position returned is still relative to the
-       beginning of <parameter>haystack</parameter>.
+       If specified, search will start this number of characters counted from
+       the beginning of the string. Unlike <function>strrpos</function> and
+       <function>strripos</function>, the offset cannot be negative.
       </para>
      </listitem>
     </varlistentry>
@@ -60,9 +58,12 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns the position as an integer. If <parameter>needle</parameter> is
-   not found, <function>strpos</function> will return <type>boolean</type>
-   &false;.
+   Returns the position of where the needle exists relative to the beginnning of
+   the <parameter>haystack</parameter> string (independent of offset).
+   Also note that string positions start at 0, and not 1.
+  </para>
+  <para>
+   Returns &false; if the needle was not found.
   </para>
   &return.falseproblem;
  </refsect1>
diff --git a/reference/strings/functions/strripos.xml b/reference/strings/functions/strripos.xml
index e0f6f1a602..5c82b22d1d 100644
--- a/reference/strings/functions/strripos.xml
+++ b/reference/strings/functions/strripos.xml
@@ -3,7 +3,7 @@
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.strripos">
  <refnamediv>
   <refname>strripos</refname>
-  <refpurpose>Find position of last occurrence of a case-insensitive string in a string</refpurpose>
+  <refpurpose>Find the position of the last occurrence of a case-insensitive substring in a string</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
@@ -15,8 +15,11 @@
    <methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Find position of last occurrence of a string in a string. Unlike
-   <function>strrpos</function>, <function>strripos</function> is
+   Find the numeric position of the last occurrence of
+   <parameter>needle</parameter> in the <parameter>haystack</parameter> string.
+  </para>
+  <para> 
+   Unlike the <function>strrpos</function>, <function>strripos</function> is
    case-insensitive.
   </para>
  </refsect1>
@@ -46,9 +49,9 @@
      <term><parameter>offset</parameter></term>
      <listitem>
       <para>
-       If specified, search will stop this number of characters counted from the
+       If specified, search will start this number of characters counted from the
        beginning of the string. If the value is negative, search will instead start
-       from that many characters from the end of the string.
+       from that many characters from the end of the string, searching backwards.
       </para>
      </listitem>
     </varlistentry>
@@ -59,12 +62,13 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns the numerical position of the last occurrence of
-   <parameter>needle</parameter>. Also note that string positions start at 0,
-   and not 1.
+   Returns the position where the needle exists relative to the beginnning of
+   the <parameter>haystack</parameter> string (independent of search direction
+   or offset).
+   Also note that string positions start at 0, and not 1.
   </para>
   <para>
-   If <parameter>needle</parameter> is not found, &false; is returned.
+   Returns &false; if the needle was not found.
   </para>
   &return.falseproblem;
  </refsect1>
diff --git a/reference/strings/functions/strrpos.xml b/reference/strings/functions/strrpos.xml
index e390a83793..c98fbe840c 100644
--- a/reference/strings/functions/strrpos.xml
+++ b/reference/strings/functions/strrpos.xml
@@ -15,9 +15,8 @@
    <methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Returns the numeric position of the last occurrence of
-   <parameter>needle</parameter> in the <parameter>haystack</parameter>
-   string.
+   Find the numeric position of the last occurrence of
+   <parameter>needle</parameter> in the <parameter>haystack</parameter> string.
   </para>
  </refsect1>
 
@@ -46,9 +45,9 @@
      <term><parameter>offset</parameter></term>
      <listitem>
       <para>
-       If specified, search will stop this number of characters counted from the
+       If specified, search will start this number of characters counted from the
        beginning of the string. If the value is negative, search will instead start
-       from that many characters from the end of the string.
+       from that many characters from the end of the string, searching backwards.
       </para>
      </listitem>
     </varlistentry>
@@ -59,9 +58,15 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns the position where the needle exists. Returns &false; if the needle
-   was not found.
+   Returns the position where the needle exists relative to the beginnning of
+   the <parameter>haystack</parameter> string (independent of search direction
+   or offset).
+   Also note that string positions start at 0, and not 1.
   </para>
+  <para>
+   Returns &false; if the needle was not found.
+  </para>
+  &return.falseproblem;
  </refsect1>
  
  <refsect1 role="changelog">
diff --git a/reference/strings/functions/strstr.xml b/reference/strings/functions/strstr.xml
index 61b41cb23f..470d518a06 100644
--- a/reference/strings/functions/strstr.xml
+++ b/reference/strings/functions/strstr.xml
@@ -3,7 +3,7 @@
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.strstr">
  <refnamediv>
   <refname>strstr</refname>
-  <refpurpose>Find first occurrence of a string</refpurpose>
+  <refpurpose>Find the first occurrence of a string</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">