cvs: phpdoc /en/functions strings.xml

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>.