reference/strings/functions/substr-replace.xml
e095023e408c8cb6378ae16bb6870343a3946919
...
...
@@ -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.substr-replace">
3
+
<refentry xml:id="function.substr-replace" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>substr_replace</refname>
6
6
<refpurpose>Replace text within a portion of a string</refpurpose>
...
...
@@ -9,18 +9,18 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>mixed</type><methodname>substr_replace</methodname>
13
-
<methodparam><type>mixed</type><parameter>string</parameter></methodparam>
14
-
<methodparam><type>string</type><parameter>replacement</parameter></methodparam>
15
-
<methodparam><type>int</type><parameter>start</parameter></methodparam>
16
-
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
12
+
<type class="union"><type>string</type><type>array</type></type><methodname>substr_replace</methodname>
13
+
<methodparam><type class="union"><type>array</type><type>string</type></type><parameter>string</parameter></methodparam>
14
+
<methodparam><type class="union"><type>array</type><type>string</type></type><parameter>replace</parameter></methodparam>
15
+
<methodparam><type class="union"><type>array</type><type>int</type></type><parameter>offset</parameter></methodparam>
16
+
<methodparam choice="opt"><type class="union"><type>array</type><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
17
17
</methodsynopsis>
18
18
<para>
19
19
<function>substr_replace</function> replaces a copy of
20
20
<parameter>string</parameter> delimited by the
21
-
<parameter>start</parameter> and (optionally)
21
+
<parameter>offset</parameter> and (optionally)
22
22
<parameter>length</parameter> parameters with the string given in
23
-
<parameter>replacement</parameter>.
23
+
<parameter>replace</parameter>.
24
24
</para>
25
25
</refsect1>
26
26

...
...
@@ -34,10 +34,19 @@
34
34
<para>
35
35
The input string.
36
36
</para>
37
+
<para>
38
+
An <type>array</type> of <type>string</type>s can be provided, in which
39
+
case the replacements will occur on each string in turn. In this case,
40
+
the <parameter>replace</parameter>, <parameter>offset</parameter>
41
+
and <parameter>length</parameter> parameters may be provided either as
42
+
scalar values to be applied to each input string in turn, or as
43
+
<type>array</type>s, in which case the corresponding array element will
44
+
be used for each input string.
45
+
</para>
37
46
</listitem>
38
47
</varlistentry>
39
48
<varlistentry>
40
-
<term><parameter>replacement</parameter></term>
49
+
<term><parameter>replace</parameter></term>
41
50
<listitem>
42
51
<para>
43
52
The replacement string.
...
...
@@ -45,16 +54,16 @@
45
54
</listitem>
46
55
</varlistentry>
47
56
<varlistentry>
48
-
<term><parameter>start</parameter></term>
57
+
<term><parameter>offset</parameter></term>
49
58
<listitem>
50
59
<para>
51
-
If <parameter>start</parameter> is positive, the replacing will
52
-
begin at the <parameter>start</parameter>'th offset into
60
+
If <parameter>offset</parameter> is non-negative, the replacing will
61
+
begin at the <parameter>offset</parameter>'th offset into
53
62
<parameter>string</parameter>.
54
63
</para>
55
64
<para>
56
-
If <parameter>start</parameter> is negative, the replacing will
57
-
begin at the <parameter>start</parameter>'th character from the
65
+
If <parameter>offset</parameter> is negative, the replacing will
66
+
begin at the <parameter>offset</parameter>'th character from the
58
67
end of <parameter>string</parameter>.
59
68
</para>
60
69
</listitem>
...
...
@@ -71,9 +80,9 @@
71
80
<parameter>string</parameter> ); i.e. end the replacing at the
72
81
end of <parameter>string</parameter>. Of course, if
73
82
<parameter>length</parameter> is zero then this function will have the
74
-
effect of inserting <parameter>replacement</parameter> into
83
+
effect of inserting <parameter>replace</parameter> into
75
84
<parameter>string</parameter> at the given
76
-
<parameter>start</parameter> offset.
85
+
<parameter>offset</parameter> offset.
77
86
</para>
78
87
</listitem>
79
88
</varlistentry>
...
...
@@ -89,11 +98,35 @@
89
98
</para>
90
99
</refsect1>
91
100

101
+
<refsect1 role="changelog">
102
+
&reftitle.changelog;
103
+
<para>
104
+
<informaltable>
105
+
<tgroup cols="2">
106
+
<thead>
107
+
<row>
108
+
<entry>&Version;</entry>
109
+
<entry>&Description;</entry>
110
+
</row>
111
+
</thead>
112
+
<tbody>
113
+
<row>
114
+
<entry>8.0.0</entry>
115
+
<entry>
116
+
<parameter>length</parameter> is nullable now.
117
+
</entry>
118
+
</row>
119
+
</tbody>
120
+
</tgroup>
121
+
</informaltable>
122
+
</para>
123
+
</refsect1>
124
+

92
125
<refsect1 role="examples">
93
126
&reftitle.examples;
94
127
<para>
95
128
<example>
96
-
<title><function>substr_replace</function> example</title>
129
+
<title>Simple <function>substr_replace</function> examples</title>
97
130
<programlisting role="php">
98
131
<![CDATA[
99
132
<?php
...
...
@@ -118,6 +151,40 @@ echo substr_replace($var, '', 10, -1) . "<br />\n";
118
151
</programlisting>
119
152
</example>
120
153
</para>
154
+
<para>
155
+
<example>
156
+
<title>
157
+
Using <function>substr_replace</function> to replace multiple strings at
158
+
once
159
+
</title>
160
+
<programlisting role="php">
161
+
<![CDATA[
162
+
<?php
163
+
$input = array('A: XXX', 'B: XXX', 'C: XXX');
164
+

165
+
// A simple case: replace XXX in each string with YYY.
166
+
echo implode('; ', substr_replace($input, 'YYY', 3, 3))."\n";
167
+

168
+
// A more complicated case where each replacement is different.
169
+
$replace = array('AAA', 'BBB', 'CCC');
170
+
echo implode('; ', substr_replace($input, $replace, 3, 3))."\n";
171
+

172
+
// Replace a different number of characters each time.
173
+
$length = array(1, 2, 3);
174
+
echo implode('; ', substr_replace($input, $replace, 3, $length))."\n";
175
+
?>
176
+
]]>
177
+
</programlisting>
178
+
&example.outputs;
179
+
<screen>
180
+
<![CDATA[
181
+
A: YYY; B: YYY; C: YYY
182
+
A: AAA; B: BBB; C: CCC
183
+
A: AAAXX; B: BBBX; C: CCC
184
+
]]>
185
+
</screen>
186
+
</example>
187
+
</para>
121
188
</refsect1>
122
189

123
190
<refsect1 role="notes">
...
...
@@ -131,12 +198,12 @@ echo substr_replace($var, '', 10, -1) . "<br />\n";
131
198
<simplelist>
132
199
<member><function>str_replace</function></member>
133
200
<member><function>substr</function></member>
201
+
<member><link linkend="language.types.string.substr">String access and modification by character</link></member>
134
202
</simplelist>
135
203
</para>
136
204
</refsect1>
137
205

138
206
</refentry>
139
-

140
207
<!-- Keep this comment at the end of the file
141
208
Local variables:
142
209
mode: sgml
143
210