jeroen Thu Aug 9 16:52:57 2001 EDT
Modified files:
/phpdoc/en/functions strings.xml
Log:
Documented new second parameter of trim, ltrim and rtrim (and chop of course)
Index: phpdoc/en/functions/strings.xml
diff -u phpdoc/en/functions/strings.xml:1.102 phpdoc/en/functions/strings.xml:1.103
--- phpdoc/en/functions/strings.xml:1.102 Sun Aug 5 18:49:38 2001
+++ phpdoc/en/functions/strings.xml Thu Aug 9 16:52:55 2001
@@ -1,5 +1,5 @@
<?xml encoding="iso-8859-1"?>
-<!-- $Revision: 1.102 $ -->
+<!-- $Revision: 1.103 $ -->
<reference id="ref.strings">
<title>String functions</title>
<titleabbrev>Strings</titleabbrev>
@@ -153,37 +153,20 @@
<refentry id="function.chop">
<refnamediv>
<refname>chop</refname>
- <refpurpose>Remove trailing whitespace</refpurpose>
+ <refpurpose>Alias of <function>rtrim</function></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>string <function>chop</function></funcdef>
- <paramdef>string <parameter>str</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
<para>
- Returns the argument string without trailing whitespace,
- including newlines.
- <example>
- <title><function>chop</function> example</title>
- <programlisting role="php">
-$trimmed = chop($line);
- </programlisting>
- </example>
+ This function is an alias of <function>rtrim</function>.
</para>
<note>
<para>
<function>chop</function> is different than the Perl
- <parameter>chop()</parameter> function, which removes the last
+ <literal>chop()</literal> function, which removes the last
character in the string.
</para>
</note>
- <para>
- See also <function>trim</function>, <function>ltrim</function>,
- <function>rtrim</function>, and <function>chop</function>.
- </para>
</refsect1>
</refentry>
@@ -1323,6 +1306,7 @@
</refsect1>
</refentry>
+ <!-- this section is nearly-identical to trim, ltrim and rtrim -->
<refentry id="function.ltrim">
<refnamediv>
<refname>ltrim</refname>
@@ -1334,19 +1318,96 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>string <function>ltrim</function></funcdef>
- <paramdef>string <parameter>str</parameter></paramdef>
+ <funcdef>string
+ <function>ltrim</function>
+ </funcdef>
+ <paramdef>string
+ <parameter>str</parameter>
+ </paramdef>
+ <paramdef>string
+ <parameter><optional>charlist</optional></parameter>
+ </paramdef>
</funcprototype>
</funcsynopsis>
<para>
This function returns a string with whitespace stripped from the
- beginning of <parameter>str</parameter>. The whitespace
- characters it currently strips are: "\n", "\r", "\t", "\v", "\0",
- and a plain space.
+ beginning of <parameter>str</parameter>.
+ Without the second parameter,
+ <function>ltrim</function> will strip these characters:
+ <!-- sorted by importance. Printed 3 times: trim, ltrim, rtrim -->
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ " " (<acronym>ASCII</acronym> <literal>32</literal>
+ (<literal>0x20</literal>)), an ordinary space.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ "\t" (<acronym>ASCII</acronym> <literal>9</literal>
+ (<literal>0x09</literal>)), a tab.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ "\n" (<acronym>ASCII</acronym> <literal>13</literal>
+ (<literal>0x0D</literal>)), a newline.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ "\r" (<acronym>ASCII</acronym> <literal>10</literal>
+ (<literal>0x0A</literal>)), a return.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ "\0" (<acronym>ASCII</acronym> <literal>0</literal>
+ (<literal>0x00</literal>)), the <literal>NUL</literal>-byte.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara> <!-- not \v, since not supported by PHP -->
+ "\x0B" (<acronym>ASCII</acronym> <literal>11</literal>
+ (<literal>0x0B</literal>)), a <!-- TODO: -->.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ You can also specify the characters you want to strip, by means
+ of the <parameter>charlist</parameter> parameter.
+ Simply list all characters that you want to be stripped. With
+ <literal>..</literal> you can specify a range of characters.
</para>
+ <example>
+ <title>Usuage example of <function>ltrim</function></title>
+ <para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$text = "\t\tThese are a few words :) ... ";
+$trimmed = ltrim($text);
+// $trimmed = "These are a few words :) ... "
+$trimmed = ltrim($text," \t.");
+// $trimmed = "These are a few words :) ... "
+$clean = ltrim($binary,"\0x00..\0x1F");
+// trim the ASCII control characters at the beginning of $binary
+// (from 0 to 31 inclusive)
+
+?>
+]]>
+ </programlisting>
+ </para>
+ </example>
+ <note>
+ <simpara>
+ The second parameter was added in PHP 4.0.7
+ </simpara>
+ </note>
<para>
- See also <function>chop</function>, <function>rtrim</function>, and
- <function>trim</function>.
+ See also <function>trim</function> and <function>rtrim</function>.
</para>
</refsect1>
</refentry>
@@ -1617,32 +1678,108 @@
</refsect1>
</refentry>
+ <!-- this section is nearly-identical to trim, ltrim and rtrim -->
<refentry id="function.rtrim">
<refnamediv>
<refname>rtrim</refname>
- <refpurpose>Remove trailing whitespace.</refpurpose>
+ <refpurpose>
+ Strip whitespace from the end of a string
+ </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>string <function>rtrim</function></funcdef>
- <paramdef>string <parameter>str</parameter></paramdef>
+ <funcdef>string
+ <function>rtrim</function>
+ </funcdef>
+ <paramdef>string
+ <parameter>str</parameter>
+ </paramdef>
+ <paramdef>string
+ <parameter><optional>charlist</optional></parameter>
+ </paramdef>
</funcprototype>
</funcsynopsis>
<para>
- Returns the argument string without trailing whitespace,
- including newlines. This is an alias for <function>chop</function>.
- <example>
- <title><function>rtrim</function> example</title>
+ This function returns a string with whitespace stripped from the
+ end of <parameter>str</parameter>.
+ Without the second parameter,
+ <function>rtrim</function> will strip these characters:
+ <!-- sorted by importance. Printed 3 times: trim, ltrim, rtrim -->
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ " " (<acronym>ASCII</acronym> <literal>32</literal>
+ (<literal>0x20</literal>)), an ordinary space.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ "\t" (<acronym>ASCII</acronym> <literal>9</literal>
+ (<literal>0x09</literal>)), a tab.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ "\n" (<acronym>ASCII</acronym> <literal>13</literal>
+ (<literal>0x0D</literal>)), a newline.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ "\r" (<acronym>ASCII</acronym> <literal>10</literal>
+ (<literal>0x0A</literal>)), a return.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ "\0" (<acronym>ASCII</acronym> <literal>0</literal>
+ (<literal>0x00</literal>)), the <literal>NUL</literal>-byte.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara> <!-- not \v, since not supported by PHP -->
+ "\x0B" (<acronym>ASCII</acronym> <literal>11</literal>
+ (<literal>0x0B</literal>)), a <!-- TODO: -->.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ You can also specify the characters you want to strip, by means
+ of the <parameter>charlist</parameter> parameter.
+ Simply list all characters that you want to be stripped. With
+ <literal>..</literal> you can specify a range of characters.
+ </para>
+ <example>
+ <title>Usuage example of <function>rtrim</function></title>
+ <para>
<programlisting role="php">
-$trimmed = rtrim($line);
+<![CDATA[
+<?php
+
+$text = "\t\tThese are a few words :) ... ";
+$trimmed = rtrim($text);
+// $trimmed = "\t\tThese are a few words :) ..."
+$trimmed = rtrim($text," \t.");
+// $trimmed = "\t\tThese are a few words :)"
+$clean = rtrim($binary,"\0x00..\0x1F");
+// trim the ASCII control characters at the end of $binary
+// (from 0 to 31 inclusive)
+
+?>
+]]>
</programlisting>
- </example>
- </para>
+ </para>
+ </example>
+ <note>
+ <simpara>
+ The second parameter was added in PHP 4.0.7
+ </simpara>
+ </note>
<para>
- See also <function>trim</function>, <function>ltrim</function>, and
- <function>rtrim</function>.
+ See also <function>trim</function> and <function>ltrim</function>.
</para>
</refsect1>
</refentry>
@@ -3398,6 +3535,7 @@
</refsect1>
</refentry>
+ <!-- this section is nearly-identical to trim, ltrim and rtrim -->
<refentry id="function.trim">
<refnamediv>
<refname>trim</refname>
@@ -3409,19 +3547,96 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>string <function>trim</function></funcdef>
- <paramdef>string <parameter>str</parameter></paramdef>
+ <funcdef>string
+ <function>trim</function>
+ </funcdef>
+ <paramdef>string
+ <parameter>str</parameter>
+ </paramdef>
+ <paramdef>string
+ <parameter><optional>charlist</optional></parameter>
+ </paramdef>
</funcprototype>
</funcsynopsis>
<para>
- This function returns a string with whitespace stripped from
- the beginning and end of <parameter>str</parameter>. The
- whitespace characters it currently strips are: "\n", "\r", "\t",
- "\v", "\0", and a plain space.
+ This function returns a string with whitespace stripped from the
+ beginning and end of <parameter>str</parameter>.
+ Without the second parameter,
+ <function>trim</function> will strip these characters:
+ <!-- sorted by importance. Printed 3 times: trim, ltrim, rtrim -->
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ " " (<acronym>ASCII</acronym> <literal>32</literal>
+ (<literal>0x20</literal>)), an ordinary space.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ "\t" (<acronym>ASCII</acronym> <literal>9</literal>
+ (<literal>0x09</literal>)), a tab.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ "\n" (<acronym>ASCII</acronym> <literal>13</literal>
+ (<literal>0x0D</literal>)), a newline.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ "\r" (<acronym>ASCII</acronym> <literal>10</literal>
+ (<literal>0x0A</literal>)), a return.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ "\0" (<acronym>ASCII</acronym> <literal>0</literal>
+ (<literal>0x00</literal>)), the <literal>NUL</literal>-byte.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara> <!-- not \v, since not supported by PHP -->
+ "\x0B" (<acronym>ASCII</acronym> <literal>11</literal>
+ (<literal>0x0B</literal>)), a <!-- TODO: -->.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ You can also specify the characters you want to strip, by means
+ of the <parameter>charlist</parameter> parameter.
+ Simply list all characters that you want to be stripped. With
+ <literal>..</literal> you can specify a range of characters.
</para>
+ <example>
+ <title>Usuage example of <function>trim</function></title>
+ <para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$text = "\t\tThese are a few words :) ... ";
+$trimmed = trim($text);
+// $trimmed = "These are a few words :) ..."
+$trimmed = trim($text," \t.");
+// $trimmed = "These are a few words :)"
+$clean = trim($binary,"\0x00..\0x1F");
+// trim the ASCII control characters at the beginning and end of $binary
+// (from 0 to 31 inclusive)
+
+?>
+]]>
+ </programlisting>
+ </para>
+ </example>
+ <note>
+ <simpara>
+ The second parameter was added in PHP 4.0.7
+ </simpara>
+ </note>
<para>
- See also <function>chop</function>, <function>rtrim</function> and
- <function>ltrim</function>.
+ See also <function>ltrim</function> and <function>rtrim</function>.
</para>
</refsect1>
</refentry>
