reference/strings/functions/str-replace.xml
464fbf0d12f89b1e723908780fb68acf667f5901
...
...
@@ -1,6 +1,6 @@
1
-
<?xml version="1.0" encoding="iso-8859-1"?>
1
+
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.str-replace">
3
+
<refentry xml:id="function.str-replace" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>str_replace</refname>
6
6
<refpurpose>Replace all occurrences of the search string with the replacement string</refpurpose>
...
...
@@ -9,11 +9,11 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>mixed</type><methodname>str_replace</methodname>
13
-
<methodparam><type>mixed</type><parameter>search</parameter></methodparam>
14
-
<methodparam><type>mixed</type><parameter>replace</parameter></methodparam>
15
-
<methodparam><type>mixed</type><parameter>subject</parameter></methodparam>
16
-
<methodparam choice="opt"><type>int</type><parameter role="reference">count</parameter></methodparam>
12
+
<type class="union"><type>string</type><type>array</type></type><methodname>str_replace</methodname>
13
+
<methodparam><type class="union"><type>array</type><type>string</type></type><parameter>search</parameter></methodparam>
14
+
<methodparam><type class="union"><type>array</type><type>string</type></type><parameter>replace</parameter></methodparam>
15
+
<methodparam><type class="union"><type>string</type><type>array</type></type><parameter>subject</parameter></methodparam>
16
+
<methodparam choice="opt"><type>int</type><parameter role="reference">count</parameter><initializer>&null;</initializer></methodparam>
17
17
</methodsynopsis>
18
18
<para>
19
19
This function returns a string or an array with all occurrences of
...
...
@@ -21,9 +21,8 @@
21
21
replaced with the given <parameter>replace</parameter> value.
22
22
</para>
23
23
<para>
24
-
If you don't need fancy replacing rules (like regular expressions), you
25
-
should always use this function instead of <function>ereg_replace</function>
26
-
or <function>preg_replace</function>.
24
+
To replace text based on a pattern rather than a fixed
25
+
string, use <function>preg_replace</function>.
27
26
</para>
28
27
</refsect1>
29
28

...
...
@@ -31,14 +30,14 @@
31
30
&reftitle.parameters;
32
31
<para>
33
32
If <parameter>search</parameter> and <parameter>replace</parameter> are
34
-
arrays, then <function>str_replace</function> takes a value from each
35
-
array and uses them to do search and replace on
36
-
<parameter>subject</parameter>. If <parameter>replace</parameter> has
37
-
fewer values than <parameter>search</parameter>, then an empty string is
38
-
used for the rest of replacement values. If <parameter>search</parameter>
39
-
is an array and <parameter>replace</parameter> is a string, then this
40
-
replacement string is used for every value of
41
-
<parameter>search</parameter>. The converse would not make sense, though.
33
+
arrays, then <function>str_replace</function> takes a value from each array
34
+
and uses them to search and replace on <parameter>subject</parameter>. If
35
+
<parameter>replace</parameter> has fewer values than
36
+
<parameter>search</parameter>, then an empty string is used for the rest of
37
+
replacement values. If <parameter>search</parameter> is an array and
38
+
<parameter>replace</parameter> is a string, then this replacement string is
39
+
used for every value of <parameter>search</parameter>. The converse would
40
+
not make sense, though.
42
41
</para>
43
42
<para>
44
43
If <parameter>search</parameter> or <parameter>replace</parameter>
...
...
@@ -50,6 +49,8 @@
50
49
<term><parameter>search</parameter></term>
51
50
<listitem>
52
51
<para>
52
+
The value being searched for, otherwise known as the <emphasis>needle</emphasis>.
53
+
An array may be used to designate multiple needles.
53
54
</para>
54
55
</listitem>
55
56
</varlistentry>
...
...
@@ -57,6 +58,8 @@
57
58
<term><parameter>replace</parameter></term>
58
59
<listitem>
59
60
<para>
61
+
The replacement value that replaces found <parameter>search</parameter>
62
+
values. An array may be used to designate multiple replacements.
60
63
</para>
61
64
</listitem>
62
65
</varlistentry>
...
...
@@ -64,6 +67,10 @@
64
67
<term><parameter>subject</parameter></term>
65
68
<listitem>
66
69
<para>
70
+
The string or array being searched and replaced on,
71
+
otherwise known as the <emphasis>haystack</emphasis>.
72
+
</para>
73
+
<para>
67
74
If <parameter>subject</parameter> is an array, then the search and
68
75
replace is performed with every entry of
69
76
<parameter>subject</parameter>, and the return value is an array as
...
...
@@ -74,11 +81,9 @@
74
81
<varlistentry>
75
82
<term><parameter>count</parameter></term>
76
83
<listitem>
77
-
<note>
78
-
<simpara>
79
-
If passed, this will hold the number of matched and replaced needles.
80
-
</simpara>
81
-
</note>
84
+
<para>
85
+
If passed, this will be set to the number of replacements performed.
86
+
</para>
82
87
</listitem>
83
88
</varlistentry>
84
89
</variablelist>
...
...
@@ -92,54 +97,11 @@
92
97
</para>
93
98
</refsect1>
94
99

95
-
<refsect1 role="changelog">
96
-
&reftitle.changelog;
97
-
<para>
98
-
<informaltable>
99
-
<tgroup cols="2">
100
-
<thead>
101
-
<row>
102
-
<entry>&Version;</entry>
103
-
<entry>&Description;</entry>
104
-
</row>
105
-
</thead>
106
-
<tbody>
107
-
<row>
108
-
<entry>5.0.0</entry>
109
-
<entry>
110
-
The <parameter>count</parameter> parameter was added.
111
-
</entry>
112
-
</row>
113
-
<row>
114
-
<entry>4.3.3</entry>
115
-
<entry>
116
-
The behaviour of this function changed. In older versions a bug
117
-
existed when using arrays as both <parameter>search</parameter> and
118
-
<parameter>replace</parameter> parameters which caused empty
119
-
<parameter>search</parameter> indexes to be skipped without advancing
120
-
the internal pointer on the <parameter>replace</parameter> array.
121
-
This has been corrected in PHP 4.3.3, any scripts which relied on
122
-
this bug should remove empty search values prior to calling this
123
-
function in order to mimic the original behavior.
124
-
</entry>
125
-
</row>
126
-
<row>
127
-
<entry>4.0.5</entry>
128
-
<entry>
129
-
Most parameters can now be an <type>array</type>.
130
-
</entry>
131
-
</row>
132
-
</tbody>
133
-
</tgroup>
134
-
</informaltable>
135
-
</para>
136
-
</refsect1>
137
-

138
100
<refsect1 role="examples">
139
101
&reftitle.examples;
140
102
<para>
141
103
<example>
142
-
<title><function>str_replace</function> examples</title>
104
+
<title>Basic <function>str_replace</function> examples</title>
143
105
<programlisting role="php">
144
106
<![CDATA[
145
107
<?php
...
...
@@ -157,18 +119,37 @@ $yummy = array("pizza", "beer", "ice cream");
157
119

158
120
$newphrase = str_replace($healthy, $yummy, $phrase);
159
121

160
-
// Use of the count parameter is available as of PHP 5.0.0
122
+
// Provides: 2
161
123
$str = str_replace("ll", "", "good golly miss molly!", $count);
162
-
echo $count; // 2
163
-

124
+
echo $count;
125
+
?>
126
+
]]>
127
+
</programlisting>
128
+
</example>
129
+
</para>
130
+
<para>
131
+
<example>
132
+
<title>Examples of potential <function>str_replace</function> gotchas</title>
133
+
<programlisting role="php">
134
+
<![CDATA[
135
+
<?php
164
136
// Order of replacement
165
137
$str = "Line 1\nLine 2\rLine 3\r\nLine 4\n";
166
138
$order = array("\r\n", "\n", "\r");
167
139
$replace = '<br />';
140
+

168
141
// Processes \r\n's first so they aren't converted twice.
169
142
$newstr = str_replace($order, $replace, $str);
170
143

144
+
// Outputs F because A is replaced with B, then B is replaced with C, and so on...
145
+
// Finally E is replaced with F, because of left to right replacements.
146
+
$search = array('A', 'B', 'C', 'D', 'E');
147
+
$replace = array('B', 'C', 'D', 'E', 'F');
148
+
$subject = 'A';
149
+
echo str_replace($search, $replace, $subject);
150
+

171
151
// Outputs: apearpearle pear
152
+
// For the same reason mentioned above
172
153
$letters = array('a', 'p');
173
154
$fruit = array('apple', 'pear');
174
155
$text = 'a p';
...
...
@@ -184,6 +165,14 @@ echo $output;
184
165
<refsect1 role="notes">
185
166
&reftitle.notes;
186
167
&note.bin-safe;
168
+
<caution>
169
+
<title>Replacement order gotcha</title>
170
+
<para>
171
+
Because <function>str_replace</function> replaces left to right, it might
172
+
replace a previously inserted value when doing multiple replacements.
173
+
See also the examples in this document.
174
+
</para>
175
+
</caution>
187
176
<note>
188
177
<para>
189
178
This function is case-sensitive. Use <function>str_ireplace</function>
...
...
@@ -205,7 +194,6 @@ echo $output;
205
194
</refsect1>
206
195

207
196
</refentry>
208
-

209
197
<!-- Keep this comment at the end of the file
210
198
Local variables:
211
199
mode: sgml
212
200