From f6472a93ce1f7fccb6ad87af3f34de87c7eeda00 Mon Sep 17 00:00:00 2001
From: Philip Olson <philip@php.net>
Date: Tue, 31 May 2005 21:34:35 +0000
Subject: [PATCH] Added an example, moved to new doc style.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@187420 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/strings/functions/trim.xml | 144 +++++++++++++++++++++++----
 1 file changed, 124 insertions(+), 20 deletions(-)

diff --git a/reference/strings/functions/trim.xml b/reference/strings/functions/trim.xml
index 37daeb4a65..463a1cfecf 100644
--- a/reference/strings/functions/trim.xml
+++ b/reference/strings/functions/trim.xml
@@ -1,13 +1,14 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
 <refentry id="function.trim">
  <refnamediv>
   <refname>trim</refname> 
   <refpurpose>Strip whitespace (or other characters) from the beginning and end of a string</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>string</type><methodname>trim</methodname>
    <methodparam><type>string</type><parameter>str</parameter></methodparam>
@@ -58,22 +59,79 @@
     </listitem>
    </itemizedlist>
   </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
   <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.
+   <variablelist>
+    <varlistentry>
+     <term><parameter>str</parameter></term>
+     <listitem>
+      <para>
+       The <type>string</type> that will be trimmed.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>charlist</parameter></term>
+     <listitem>
+      <para>
+       Optionally, the stripped characters can also be specified using
+       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>
+     </listitem>
+    </varlistentry>
+   </variablelist>
   </para>
-  <example>
-   <title>Usage example of <function>trim</function></title>
-   <programlisting role="php">
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   The trimmed string.
+  </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>4.1.0</entry>
+       <entry>
+        The optional <parameter>charlist</parameter> parameter was added.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Usage example of <function>trim</function></title>
+    <programlisting role="php">
 <![CDATA[
 <?php
 
 $text = "\t\tThese are a few words :) ...  ";
 
 echo trim($text);           // "These are a few words :) ..."
-echo trim($text, " \t."); // "These are a few words :)"
+echo trim($text, " \t.");   // "These are a few words :)"
 
 // trim the ASCII control characters at the beginning and end of $binary
 // (from 0 to 31 inclusive)
@@ -81,16 +139,62 @@ $clean = trim($binary, "\x00..\x1F");
 
 ?>
 ]]>
-   </programlisting>
-  </example>
-  <note>
-   <simpara>
-    The optional <parameter>charlist</parameter> parameter was 
-    added in PHP 4.1.0
-   </simpara>
-  </note>
+    </programlisting>
+   </example>
+  </para>
   <para>
-   See also <function>ltrim</function> and <function>rtrim</function>.
+   <example>
+    <title>Trimming array values with <function>trim</function></title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+function trim_value(&$value) 
+{ 
+	$value = trim($value); 
+}
+
+$fruit = array('apple','banana ', ' cranberry ');
+var_dump($fruit);
+
+array_walk($fruit, 'trim_value');
+var_dump($fruit);
+
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+array(3) {
+  [0]=>
+  string(5) "apple"
+  [1]=>
+  string(7) "banana "
+  [2]=>
+  string(11) " cranberry "
+}
+array(3) {
+  [0]=>
+  string(5) "apple"
+  [1]=>
+  string(6) "banana"
+  [2]=>
+  string(9) "cranberry"
+}
+
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>ltrim</function></member>
+    <member><function>rtrim</function></member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>