From 5fb277d606b080ae0a481201386c6a574d64f775 Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Sat, 15 Aug 2015 14:43:21 +0000
Subject: [PATCH] improve strspn/strcspn documentation (contributed by
 francois)

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@337482 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/strings/functions/strcspn.xml | 87 ++++++++++++++++++++-----
 reference/strings/functions/strspn.xml  |  7 ++
 2 files changed, 77 insertions(+), 17 deletions(-)

diff --git a/reference/strings/functions/strcspn.xml b/reference/strings/functions/strcspn.xml
index 2037391b12..3176526403 100644
--- a/reference/strings/functions/strcspn.xml
+++ b/reference/strings/functions/strcspn.xml
@@ -10,35 +10,43 @@
   &reftitle.description;
   <methodsynopsis>
    <type>int</type><methodname>strcspn</methodname>
-   <methodparam><type>string</type><parameter>str1</parameter></methodparam>
-   <methodparam><type>string</type><parameter>str2</parameter></methodparam>
+   <methodparam><type>string</type><parameter>subject</parameter></methodparam>
+   <methodparam><type>string</type><parameter>mask</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>start</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
   </methodsynopsis>
   <para>
    Returns the length of the initial segment of
-   <parameter>str1</parameter> which does <emphasis>not</emphasis>
-   contain any of the characters in <parameter>str2</parameter>.
+   <parameter>subject</parameter> which does <emphasis>not</emphasis>
+   contain any of the characters in <parameter>mask</parameter>.
+  </para>
+  <para>
+   If <parameter>start</parameter> and <parameter>length</parameter>
+   are omitted, then all of <parameter>subject</parameter> will be
+   examined. If they are included, then the effect will be the same as
+   calling <literal>strcspn(substr($subject, $start, $length),
+   $mask)</literal> (see <xref linkend="function.substr" />
+   for more information).
   </para>
  </refsect1>
-
+ 
  <refsect1 role="parameters">
   &reftitle.parameters;
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>str1</parameter></term>
+     <term><parameter>subject</parameter></term>
      <listitem>
       <para>
-       The first string.
+       The string to examine.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
-     <term><parameter>str2</parameter></term>
+     <term><parameter>mask</parameter></term>
      <listitem>
       <para>
-       The second string.
+       The string containing every disallowed character.
       </para>
      </listitem>
     </varlistentry>
@@ -46,7 +54,25 @@
      <term><parameter>start</parameter></term>
      <listitem>
       <para>
-       The start position of the string to examine.
+       The position in <parameter>subject</parameter> to
+       start searching.
+      </para>
+      <para>
+       If <parameter>start</parameter> is given and is non-negative,
+       then <function>strcspn</function> will begin
+       examining <parameter>subject</parameter> at
+       the <parameter>start</parameter>'th position. For instance, in
+       the string '<literal>abcdef</literal>', the character at
+       position <literal>0</literal> is '<literal>a</literal>', the
+       character at position <literal>2</literal> is
+       '<literal>c</literal>', and so forth.
+      </para>
+      <para>
+       If <parameter>start</parameter> is given and is negative,
+       then <function>strspn</function> will begin
+       examining <parameter>subject</parameter> at
+       the <parameter>start</parameter>'th position from the end
+       of <parameter>subject</parameter>.
       </para>
      </listitem>
     </varlistentry>
@@ -54,21 +80,42 @@
      <term><parameter>length</parameter></term>
      <listitem>
       <para>
-       The length of the string to examine.
+       The length of the segment from <parameter>subject</parameter>
+       to examine. 
+      </para>
+      <para>
+       If <parameter>length</parameter> is given and is non-negative,
+       then <parameter>subject</parameter> will be examined
+       for <parameter>length</parameter> characters after the starting
+       position.
+      </para>
+      <para>
+       If <parameter>length</parameter> is given and is negative,
+       then <parameter>subject</parameter> will be examined from the
+       starting position up to <parameter>length</parameter>
+       characters from the end of <parameter>subject</parameter>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect1>
-
+ 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns the length of the segment as an integer.
+   Returns the length of the initial segment of <parameter>subject</parameter>
+   which consists entirely of characters <emphasis>not</emphasis> in <parameter>mask</parameter>.
   </para>
+  <note>
+   <para>
+    When a <parameter>start</parameter> parameter is set, the returned length
+    is counted starting from this position, not from the beginning of
+    <parameter>subject</parameter>.
+   </para>
+  </note>
  </refsect1>
-
+ 
  <refsect1 role="examples">
   &reftitle.examples;
   <example xml:id="strcspn.example">
@@ -80,11 +127,15 @@ $a = strcspn('abcd',  'apple');
 $b = strcspn('abcd',  'banana');
 $c = strcspn('hello', 'l');
 $d = strcspn('hello', 'world');
+$e = strcspn('abcdhelloabcd', 'abcd', -9);
+$f = strcspn('abcdhelloabcd', 'abcd', -9, -5);
 
 var_dump($a);
 var_dump($b);
 var_dump($c);
 var_dump($d);
+var_dump($e);
+var_dump($f);
 ?>
 ]]>
    </programlisting>
@@ -95,16 +146,18 @@ int(0)
 int(0)
 int(2)
 int(2)
+int(5)
+int(4)
 ]]>
    </screen>
   </example>
  </refsect1>
-
+ 
  <refsect1 role="notes">
   &reftitle.notes;
   &note.bin-safe;
  </refsect1>
-
+ 
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
@@ -113,7 +166,7 @@ int(2)
    </simplelist>
   </para>
  </refsect1>
-
+ 
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/strings/functions/strspn.xml b/reference/strings/functions/strspn.xml
index f24b9a3519..926aba4ffe 100644
--- a/reference/strings/functions/strspn.xml
+++ b/reference/strings/functions/strspn.xml
@@ -125,6 +125,13 @@ $var = strspn("42 is the answer to the 128th question.", "1234567890");
    Returns the length of the initial segment of <parameter>subject</parameter>
    which consists entirely of characters in <parameter>mask</parameter>.
   </para>
+  <note>
+   <para>
+    When a <parameter>start</parameter> parameter is set, the returned length
+    is counted starting from this position, not from the beginning of
+    <parameter>subject</parameter>.
+   </para>
+  </note>
  </refsect1>
 
  <refsect1 role="examples">