Clarified removing middle strings via an example and note. Deals with PHP Bug #54697

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@310860 c90b9560-bf6c-de11-be94-00142212c4b1

reference/strings/functions/trim.xml

@@ -144,6 +144,9 @@ var_dump($trimmed);
 $trimmed = trim($hello, "Hdle");
 var_dump($trimmed);
 
+$trimmed = trim($hello, 'HdWr');
+var_dump($trimmed);
+
 // trim the ASCII control characters at the beginning and end of $binary
 // (from 0 to 31 inclusive)
 $clean = trim($binary, "\x00..\x1F");
@@ -163,6 +166,7 @@ string(11) "Hello World"
 string(28) "These are a few words :) ..."
 string(24) "These are a few words :)"
 string(5) "o Wor"
+string(9) "ello Worl"
 string(14) "Example string"
 ]]>
     </screen>
@@ -214,12 +218,27 @@ array(3) {
   </para>
  </refsect1>
 
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <note>
+   <title>Possible gotcha: removing middle characters</title>
+   <para>
+    Because <function>trim</function> trims characters from the beginning and end of
+    a <type>string</type>, it may be confusing when characters are (or are not) removed from
+    the middle. <literal>trim('abc', 'bad')</literal> removes both 'a' and 'b' because it
+    trims 'a' thus moving 'b' to the beginning to also be trimmed. So, this is why it "works"
+    whereas <literal>trim('abc', 'b')</literal> seemingly does not.
+   </para>
+  </note>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
     <member><function>ltrim</function></member>
     <member><function>rtrim</function></member>
+    <member><function>str_replace</function></member>
    </simplelist>
   </para>
  </refsect1>