jimw Thu Dec 20 18:05:10 2001 EDT
Modified files:
/phpdoc/en/functions strings.xml
Log:
substr: fix examples and explanations related to negative starts and lengths, clean
up layout
Index: phpdoc/en/functions/strings.xml
diff -u phpdoc/en/functions/strings.xml:1.144 phpdoc/en/functions/strings.xml:1.145
--- phpdoc/en/functions/strings.xml:1.144 Thu Dec 20 17:38:53 2001
+++ phpdoc/en/functions/strings.xml Thu Dec 20 18:05:09 2001
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.144 $ -->
+<!-- $Revision: 1.145 $ -->
<reference id="ref.strings">
<title>String functions</title>
<titleabbrev>Strings</titleabbrev>
@@ -3742,59 +3742,58 @@
character at position <literal>2</literal> is
'<literal>c</literal>', and so forth.
</para>
- <para>
- Examples:
- <informalexample>
- <programlisting role="php">
+ <example>
+ <title>Basic <function>substr</function> usage</title>
+ <programlisting role="php">
<![CDATA[
$rest = substr("abcdef", 1); // returns "bcdef"
$rest = substr("abcdef", 1, 3); // returns "bcd"
+$rest = substr("abcdef", 0, 4); // returns "abcd"
+$rest = substr("abcdef", 0, 8); // returns "abcdef"
]]>
- </programlisting>
- </informalexample>
- </para>
+ </programlisting>
+ </example>
<para>
If <parameter>start</parameter> is negative, the returned string
will start at the <parameter>start</parameter>'th character
from the end of <parameter>string</parameter>.</para>
- <para>
- Examples:
- <informalexample>
- <programlisting role="php">
+ <example>
+ <title>Using a negative <parameter>start</parameter></title>
+ <programlisting role="php">
<![CDATA[
$rest = substr("abcdef", -1); // returns "f"
$rest = substr("abcdef", -2); // returns "ef"
$rest = substr("abcdef", -3, 1); // returns "d"
]]>
- </programlisting>
- </informalexample>
- </para>
+ </programlisting>
+ </example>
<para>
- If <parameter>length</parameter> is given and is positive, the
- string returned will end <parameter>length</parameter> characters
- from <parameter>start</parameter>. If this would result in a
- string with negative length (because the start is past the end of
- the string), then the returned string will contain the single
- character at <parameter>start</parameter>.
+ If <parameter>length</parameter> is given and is positive, the string
+ returned will contain at most <parameter>length</parameter> characters
+ beginning from <parameter>start</parameter> (depending on the length of
+ <parameter>string</parameter>. If <parameter>string</parameter> is less
+ than <parameter>start</parameter> characters long, &false; will be
+ returned.
</para>
<para>
- If <parameter>length</parameter> is given and is negative, the
- string returned will end <parameter>length</parameter> characters
- from the end of <parameter>string</parameter>. If this would
- result in a string with negative length, then the returned string
- will contain the single character at
- <parameter>start</parameter>.
+ If <parameter>length</parameter> is given and is negative, then that many
+ characters will be omitted from the end of <parameter>string</parameter>
+ (after the start position has been calculated when a
+ <parameter>start</parameter> is negative). If
+ <parameter>start</parameter> denotes a position beyond this truncation,
+ an empty string will be returned.
</para>
- <para>
- Examples:
- <informalexample>
- <programlisting role="php">
+ <example>
+ <title>Using a negative <parameter>length</parameter></title>
+ <programlisting role="php">
<![CDATA[
-$rest = substr("abcdef", 1, -1); // returns "bcde"
+$rest = substr("abcdef", 0, -1); // returns "abcde"
+$rest = substr("abcdef", 2, -1); // returns "cde"
+$rest = substr("abcdef", 4, -4); // returns ""
+$rest = substr("abcdef", -3, -1); // returns "de"
]]>
- </programlisting>
- </informalexample>
- </para>
+ </programlisting>
+ </example>
<para>
See also <function>strrchr</function> and
<function>ereg</function>.
