svn: /phpdoc/en/trunk/reference/strings/functions/ strcspn.xml strspn.xml
| From: | Christoph Michael Becker | Date: | Sat, 15 Aug 2015 14:43:21 +0000 |
| Subject: | svn: /phpdoc/en/trunk/reference/strings/functions/ strcspn.xml strspn.xml | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-13592@lists.php.net to get a copy of this message | ||
cmb Sat, 15 Aug 2015 14:43:21 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=337482
Log:
improve strspn/strcspn documentation (contributed by francois)
Changed paths:
U phpdoc/en/trunk/reference/strings/functions/strcspn.xml
U phpdoc/en/trunk/reference/strings/functions/strspn.xml
Modified: phpdoc/en/trunk/reference/strings/functions/strcspn.xml
===================================================================
--- phpdoc/en/trunk/reference/strings/functions/strcspn.xml 2015-08-15 14:41:42 UTC (rev 337481)
+++ phpdoc/en/trunk/reference/strings/functions/strcspn.xml 2015-08-15 14:43:21 UTC (rev 337482)
@@ -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,29 +54,68 @@
<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>
<varlistentry>
<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 @@
$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(2)
int(2)
+int(5)
+int(4)
]]>
</screen>
</example>
</refsect1>
-
+
<refsect1 role="notes">
&reftitle.notes;
¬e.bin-safe;
</refsect1>
-
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
@@ -113,7 +166,7 @@
</simplelist>
</para>
</refsect1>
-
+
</refentry>
<!-- Keep this comment at the end of the file
Modified: phpdoc/en/trunk/reference/strings/functions/strspn.xml
===================================================================
--- phpdoc/en/trunk/reference/strings/functions/strspn.xml 2015-08-15 14:41:42 UTC (rev 337481)
+++ phpdoc/en/trunk/reference/strings/functions/strspn.xml 2015-08-15 14:43:21 UTC (rev 337482)
@@ -125,6 +125,13 @@
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">