reference/strings/functions/trim.xml
27ae0a4a16cdfc868a884c0f0dad7023b5f2709c
...
...
@@ -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,112 +11,43 @@
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
-
<para>
17
+
<simpara>
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
-
<!-- sorted by importance. Printed 3 times: trim, ltrim, rtrim -->
23
-
<itemizedlist>
24
-
<listitem>
25
-
<simpara>
26
-
" " (<acronym>ASCII</acronym> <literal>32</literal>
27
-
(<literal>0x20</literal>)), an ordinary space.
28
-
</simpara>
29
-
</listitem>
30
-
<listitem>
31
-
<simpara>
32
-
"\t" (<acronym>ASCII</acronym> <literal>9</literal>
33
-
(<literal>0x09</literal>)), a tab.
34
-
</simpara>
35
-
</listitem>
36
-
<listitem>
37
-
<simpara>
38
-
"\n" (<acronym>ASCII</acronym> <literal>10</literal>
39
-
(<literal>0x0A</literal>)), a new line (line feed).
40
-
</simpara>
41
-
</listitem>
42
-
<listitem>
43
-
<simpara>
44
-
"\r" (<acronym>ASCII</acronym> <literal>13</literal>
45
-
(<literal>0x0D</literal>)), a carriage return.
46
-
</simpara>
47
-
</listitem>
48
-
<listitem>
49
-
<simpara>
50
-
"\0" (<acronym>ASCII</acronym> <literal>0</literal>
51
-
(<literal>0x00</literal>)), the <literal>NUL</literal>-byte.
52
-
</simpara>
53
-
</listitem>
54
-
<listitem>
55
-
<simpara> <!-- not \v, since not supported by PHP -->
56
-
"\x0B" (<acronym>ASCII</acronym> <literal>11</literal>
57
-
(<literal>0x0B</literal>)), a vertical tab.
58
-
</simpara>
59
-
</listitem>
60
-
</itemizedlist>
61
-
</para>
22
+
</simpara>
23
+
&strings.stripped.characters;
62
24
</refsect1>
63
25

64
26
<refsect1 role="parameters">
65
27
&reftitle.parameters;
66
-
<para>
67
-
<variablelist>
68
-
<varlistentry>
69
-
<term><parameter>str</parameter></term>
70
-
<listitem>
71
-
<para>
72
-
The <type>string</type> that will be trimmed.
73
-
</para>
74
-
</listitem>
75
-
</varlistentry>
76
-
<varlistentry>
77
-
<term><parameter>charlist</parameter></term>
78
-
<listitem>
79
-
<para>
80
-
Optionally, the stripped characters can also be specified using
81
-
the <parameter>charlist</parameter> parameter.
82
-
Simply list all characters that you want to be stripped. With
83
-
<literal>..</literal> you can specify a range of characters.
84
-
</para>
85
-
</listitem>
86
-
</varlistentry>
87
-
</variablelist>
88
-
</para>
28
+
<variablelist>
29
+
<varlistentry>
30
+
<term><parameter>string</parameter></term>
31
+
<listitem>
32
+
<para>
33
+
The <type>string</type> that will be trimmed.
34
+
</para>
35
+
</listitem>
36
+
</varlistentry>
37
+
<varlistentry>
38
+
<term><parameter>characters</parameter></term>
39
+
<listitem>
40
+
&strings.parameter.characters.optional;
41
+
</listitem>
42
+
</varlistentry>
43
+
</variablelist>
89
44
</refsect1>
90
45

91
46
<refsect1 role="returnvalues">
92
47
&reftitle.returnvalues;
93
-
<para>
48
+
<simpara>
94
49
The trimmed string.
95
-
</para>
96
-
</refsect1>
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>
50
+
</simpara>
120
51
</refsect1>
121
52

122
53
<refsect1 role="examples">
...
...
@@ -144,6 +75,9 @@ var_dump($trimmed);
144
75
$trimmed = trim($hello, "Hdle");
145
76
var_dump($trimmed);
146
77

78
+
$trimmed = trim($hello, 'HdWr');
79
+
var_dump($trimmed);
80
+

147
81
// trim the ASCII control characters at the beginning and end of $binary
148
82
// (from 0 to 31 inclusive)
149
83
$clean = trim($binary, "\x00..\x1F");
...
...
@@ -163,6 +97,7 @@ string(11) "Hello World"
163
97
string(28) "These are a few words :) ..."
164
98
string(24) "These are a few words :)"
165
99
string(5) "o Wor"
100
+
string(9) "ello Worl"
166
101
string(14) "Example string"
167
102
]]>
168
103
</screen>
...
...
@@ -214,17 +149,29 @@ array(3) {
214
149
</para>
215
150
</refsect1>
216
151

152
+
<refsect1 role="notes">
153
+
&reftitle.notes;
154
+
<note>
155
+
<title>Possible gotcha: removing middle characters</title>
156
+
<para>
157
+
Because <function>trim</function> trims characters from the beginning and end of
158
+
a <type>string</type>, it may be confusing when characters are (or are not) removed from
159
+
the middle. <literal>trim('abc', 'bad')</literal> removes both 'a' and 'b' because it
160
+
trims 'a' thus moving 'b' to the beginning to also be trimmed. So, this is why it "works"
161
+
whereas <literal>trim('abc', 'b')</literal> seemingly does not.
162
+
</para>
163
+
</note>
164
+
</refsect1>
165
+

217
166
<refsect1 role="seealso">
218
167
&reftitle.seealso;
219
-
<para>
220
-
<simplelist>
221
-
<member><function>ltrim</function></member>
222
-
<member><function>rtrim</function></member>
223
-
</simplelist>
224
-
</para>
168
+
<simplelist>
169
+
<member><function>ltrim</function></member>
170
+
<member><function>rtrim</function></member>
171
+
<member><function>str_replace</function></member>
172
+
</simplelist>
225
173
</refsect1>
226
174
</refentry>
227
-

228
175
<!-- Keep this comment at the end of the file
229
176
Local variables:
230
177
mode: sgml
231
178



Translation status