reference/strings/functions/trim.xml
eabde0419cf90f596f60db00e31fcb6ebe41ac55
...
...
@@ -1,7 +1,7 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
3
<!-- splitted from ./en/functions/strings.xml, last change in rev 1.2 -->
4
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.trim">
4
+
<refentry xml:id="function.trim" xmlns="http://docbook.org/ns/docbook">
5
5
<refnamediv>
6
6
<refname>trim</refname>
7
7
<refpurpose>Strip whitespace (or other characters) from the beginning and end of a string</refpurpose>
...
...
@@ -11,12 +11,12 @@
11
11
&reftitle.description;
12
12
<methodsynopsis>
13
13
<type>string</type><methodname>trim</methodname>
14
-
<methodparam><type>string</type><parameter>str</parameter></methodparam>
15
-
<methodparam choice="opt"><type>string</type><parameter>charlist</parameter></methodparam>
14
+
<methodparam><type>string</type><parameter>string</parameter></methodparam>
15
+
<methodparam choice="opt"><type>string</type><parameter>characters</parameter><initializer>" \n\r\t\v\x00"</initializer></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
18
This function returns a string with whitespace stripped from the
19
-
beginning and end of <parameter>str</parameter>.
19
+
beginning and end of <parameter>string</parameter>.
20
20
Without the second parameter,
21
21
<function>trim</function> will strip these characters:
22
22
<!-- sorted by importance. Printed 3 times: trim, ltrim, rtrim -->
...
...
@@ -52,8 +52,8 @@
52
52
</simpara>
53
53
</listitem>
54
54
<listitem>
55
-
<simpara> <!-- not \v, since not supported by PHP -->
56
-
"\x0B" (<acronym>ASCII</acronym> <literal>11</literal>
55
+
<simpara>
56
+
"\v" (<acronym>ASCII</acronym> <literal>11</literal>
57
57
(<literal>0x0B</literal>)), a vertical tab.
58
58
</simpara>
59
59
</listitem>
...
...
@@ -66,7 +66,7 @@
66
66
<para>
67
67
<variablelist>
68
68
<varlistentry>
69
-
<term><parameter>str</parameter></term>
69
+
<term><parameter>string</parameter></term>
70
70
<listitem>
71
71
<para>
72
72
The <type>string</type> that will be trimmed.
...
...
@@ -74,11 +74,11 @@
74
74
</listitem>
75
75
</varlistentry>
76
76
<varlistentry>
77
-
<term><parameter>charlist</parameter></term>
77
+
<term><parameter>characters</parameter></term>
78
78
<listitem>
79
79
<para>
80
80
Optionally, the stripped characters can also be specified using
81
-
the <parameter>charlist</parameter> parameter.
81
+
the <parameter>characters</parameter> parameter.
82
82
Simply list all characters that you want to be stripped. With
83
83
<literal>..</literal> you can specify a range of characters.
84
84
</para>
...
...
@@ -95,30 +95,6 @@
95
95
</para>
96
96
</refsect1>
97
97

98
-
<refsect1 role="changelog">
99
-
&reftitle.changelog;
100
-
<para>
101
-
<informaltable>
102
-
<tgroup cols="2">
103
-
<thead>
104
-
<row>
105
-
<entry>&Version;</entry>
106
-
<entry>&Description;</entry>
107
-
</row>
108
-
</thead>
109
-
<tbody>
110
-
<row>
111
-
<entry>4.1.0</entry>
112
-
<entry>
113
-
The optional <parameter>charlist</parameter> parameter was added.
114
-
</entry>
115
-
</row>
116
-
</tbody>
117
-
</tgroup>
118
-
</informaltable>
119
-
</para>
120
-
</refsect1>
121
-

122
98
<refsect1 role="examples">
123
99
&reftitle.examples;
124
100
<para>
...
...
@@ -144,6 +120,9 @@ var_dump($trimmed);
144
120
$trimmed = trim($hello, "Hdle");
145
121
var_dump($trimmed);
146
122

123
+
$trimmed = trim($hello, 'HdWr');
124
+
var_dump($trimmed);
125
+

147
126
// trim the ASCII control characters at the beginning and end of $binary
148
127
// (from 0 to 31 inclusive)
149
128
$clean = trim($binary, "\x00..\x1F");
...
...
@@ -163,6 +142,7 @@ string(11) "Hello World"
163
142
string(28) "These are a few words :) ..."
164
143
string(24) "These are a few words :)"
165
144
string(5) "o Wor"
145
+
string(9) "ello Worl"
166
146
string(14) "Example string"
167
147
]]>
168
148
</screen>
...
...
@@ -214,17 +194,31 @@ array(3) {
214
194
</para>
215
195
</refsect1>
216
196

197
+
<refsect1 role="notes">
198
+
&reftitle.notes;
199
+
<note>
200
+
<title>Possible gotcha: removing middle characters</title>
201
+
<para>
202
+
Because <function>trim</function> trims characters from the beginning and end of
203
+
a <type>string</type>, it may be confusing when characters are (or are not) removed from
204
+
the middle. <literal>trim('abc', 'bad')</literal> removes both 'a' and 'b' because it
205
+
trims 'a' thus moving 'b' to the beginning to also be trimmed. So, this is why it "works"
206
+
whereas <literal>trim('abc', 'b')</literal> seemingly does not.
207
+
</para>
208
+
</note>
209
+
</refsect1>
210
+

217
211
<refsect1 role="seealso">
218
212
&reftitle.seealso;
219
213
<para>
220
214
<simplelist>
221
215
<member><function>ltrim</function></member>
222
216
<member><function>rtrim</function></member>
217
+
<member><function>str_replace</function></member>
223
218
</simplelist>
224
219
</para>
225
220
</refsect1>
226
221
</refentry>
227
-

228
222
<!-- Keep this comment at the end of the file
229
223
Local variables:
230
224
mode: sgml
231
225