language/types/string.xml
2832df2e1bd7daa1ec29ffb167dce1c9feb8cc6b
...
...
@@ -4,7 +4,7 @@
4
4
<title>Strings</title>
5
5

6
6
<para>
7
-
A <type>string</type> is series of characters, where a character is
7
+
A <type>string</type> is a series of characters, where a character is
8
8
the same as a byte. This means that PHP only supports a 256-character set,
9
9
and hence does not offer native Unicode support. See
10
10
<link linkend="language.types.string.details">details of the string
...
...
@@ -13,7 +13,8 @@
13
13

14
14
<note>
15
15
<simpara>
16
-
<type>string</type> can be as large as up to 2GB (2147483647 bytes maximum)
16
+
On 32-bit builds, a <type>string</type> can be as large as up to 2GB
17
+
(2147483647 bytes maximum)
17
18
</simpara>
18
19
</note>
19
20

...
...
@@ -43,7 +44,6 @@
43
44
<listitem>
44
45
<simpara>
45
46
<link linkend="language.types.string.syntax.nowdoc">nowdoc syntax</link>
46
-
(since PHP 5.3.0)
47
47
</simpara>
48
48
</listitem>
49
49
</itemizedlist>
...
...
@@ -76,34 +76,35 @@
76
76
</simpara>
77
77
</note>
78
78

79
-
<informalexample>
79
+
<example>
80
+
<title>Syntax Variants</title>
80
81
<programlisting role="php">
81
82
<![CDATA[
82
83
<?php
83
-
echo 'this is a simple string';
84
+
echo 'this is a simple string', PHP_EOL;
84
85

85
86
echo 'You can also have embedded newlines in
86
87
strings this way as it is
87
-
okay to do';
88
+
okay to do', PHP_EOL;
88
89

89
90
// Outputs: Arnold once said: "I'll be back"
90
-
echo 'Arnold once said: "I\'ll be back"';
91
+
echo 'Arnold once said: "I\'ll be back"', PHP_EOL;
91
92

92
93
// Outputs: You deleted C:\*.*?
93
-
echo 'You deleted C:\\*.*?';
94
+
echo 'You deleted C:\\*.*?', PHP_EOL;
94
95

95
96
// Outputs: You deleted C:\*.*?
96
-
echo 'You deleted C:\*.*?';
97
+
echo 'You deleted C:\*.*?', PHP_EOL;
97
98

98
99
// Outputs: This will not expand: \n a newline
99
-
echo 'This will not expand: \n a newline';
100
+
echo 'This will not expand: \n a newline', PHP_EOL;
100
101

101
102
// Outputs: Variables do not $expand $either
102
-
echo 'Variables do not $expand $either';
103
+
echo 'Variables do not $expand $either', PHP_EOL;
103
104
?>
104
105
]]>
105
106
</programlisting>
106
-
</informalexample>
107
+
</example>
107
108

108
109
</sect3>
109
110

...
...
@@ -111,8 +112,8 @@ echo 'Variables do not $expand $either';
111
112
<title>Double quoted</title>
112
113

113
114
<para>
114
-
If the <type>string</type> is enclosed in double-quotes ("), PHP will
115
-
interpret more escape sequences for special characters:
115
+
If the <type>string</type> is enclosed in double-quotes (<literal>"</literal>), PHP will
116
+
interpret the following escape sequences for special characters:
116
117
</para>
117
118

118
119
<table>
...
...
@@ -141,15 +142,15 @@ echo 'Variables do not $expand $either';
141
142
</row>
142
143
<row>
143
144
<entry><literal>\v</literal></entry>
144
-
<entry>vertical tab (VT or 0x0B (11) in ASCII) (since PHP 5.2.5)</entry>
145
+
<entry>vertical tab (VT or 0x0B (11) in ASCII)</entry>
145
146
</row>
146
147
<row>
147
148
<entry><literal>\e</literal></entry>
148
-
<entry>escape (ESC or 0x1B (27) in ASCII) (since PHP 5.4.4)</entry>
149
+
<entry>escape (ESC or 0x1B (27) in ASCII)</entry>
149
150
</row>
150
151
<row>
151
152
<entry><literal>\f</literal></entry>
152
-
<entry>form feed (FF or 0x0C (12) in ASCII) (since PHP 5.2.5)</entry>
153
+
<entry>form feed (FF or 0x0C (12) in ASCII)</entry>
153
154
</row>
154
155
<row>
155
156
<entry><literal>\\</literal></entry>
...
...
@@ -166,15 +167,25 @@ echo 'Variables do not $expand $either';
166
167
<row>
167
168
<entry><literal>\[0-7]{1,3}</literal></entry>
168
169
<entry>
169
-
the sequence of characters matching the regular expression is a
170
-
character in octal notation
170
+
Octal: the sequence of characters matching the regular expression <literal>[0-7]{1,3}</literal>
171
+
is a character in octal notation (e.g. <literal>"\101" === "A"</literal>),
172
+
which silently overflows to fit in a byte (e.g. <literal>"\400" === "\000"</literal>)
171
173
</entry>
172
174
</row>
173
175
<row>
174
176
<entry><literal>\x[0-9A-Fa-f]{1,2}</literal></entry>
175
177
<entry>
176
-
the sequence of characters matching the regular expression is a
177
-
character in hexadecimal notation
178
+
Hexadecimal: the sequence of characters matching the regular expression
179
+
<literal>[0-9A-Fa-f]{1,2}</literal> is a character in hexadecimal notation
180
+
(e.g. <literal>"\x41" === "A"</literal>)
181
+
</entry>
182
+
</row>
183
+
<row>
184
+
<entry><literal>\u{[0-9A-Fa-f]+}</literal></entry>
185
+
<entry>
186
+
Unicode: the sequence of characters matching the regular expression <literal>[0-9A-Fa-f]+</literal>
187
+
is a Unicode codepoint, which will be output to the string as that codepoint's UTF-8 representation.
188
+
The braces are required in the sequence. E.g. <literal>"\u{41}" === "A"</literal>
178
189
</entry>
179
190
</row>
180
191
</tbody>
...
...
@@ -183,14 +194,13 @@ echo 'Variables do not $expand $either';
183
194

184
195
<para>
185
196
As in single quoted <type>string</type>s, escaping any other character will
186
-
result in the backslash being printed too. Before PHP 5.1.1, the backslash
187
-
in <literal>\{$var}</literal> had not been printed.
197
+
result in the backslash being printed too.
188
198
</para>
189
199

190
200
<para>
191
201
The most important feature of double-quoted <type>string</type>s is the fact
192
202
that variable names will be expanded. See
193
-
<link linkend="language.types.string.parsing">string parsing</link> for
203
+
<link linkend="language.types.string.parsing">string interpolation</link> for
194
204
details.
195
205
</para>
196
206
</sect3>
...
...
@@ -206,22 +216,204 @@ echo 'Variables do not $expand $either';
206
216
</simpara>
207
217

208
218
<simpara>
209
-
The closing identifier <emphasis>must</emphasis> begin in the first column
210
-
of the line. Also, the identifier must follow the same naming rules as any
219
+
The closing identifier may be indented by space or tab, in which case
220
+
the indentation will be stripped from all lines in the doc string.
221
+
Prior to PHP 7.3.0, the closing identifier <emphasis>must</emphasis>
222
+
begin in the first column of the line.
223
+
</simpara>
224
+

225
+
<simpara>
226
+
Also, the closing identifier must follow the same naming rules as any
211
227
other label in PHP: it must contain only alphanumeric characters and
212
228
underscores, and must start with a non-digit character or underscore.
213
229
</simpara>
214
230

231
+
<example>
232
+
<title>Basic Heredoc example as of PHP 7.3.0</title>
233
+
<programlisting role="php">
234
+
<![CDATA[
235
+
<?php
236
+
// no indentation
237
+
echo <<<END
238
+
a
239
+
b
240
+
c
241
+
\n
242
+
END;
243
+

244
+
// 4 spaces of indentation
245
+
echo <<<END
246
+
a
247
+
b
248
+
c
249
+
END;
250
+
]]>
251
+
</programlisting>
252
+
&example.outputs.73;
253
+
<screen>
254
+
<![CDATA[
255
+
a
256
+
b
257
+
c
258
+

259
+
a
260
+
b
261
+
c
262
+
]]>
263
+
</screen>
264
+
</example>
265
+

266
+
<simpara>
267
+
If the closing identifier is indented further than any lines of the body, then a <classname>ParseError</classname> will be thrown:
268
+
</simpara>
269
+

270
+
<example>
271
+
<title>Closing identifier must not be indented further than any lines of the body</title>
272
+
<programlisting role="php">
273
+
<![CDATA[
274
+
<?php
275
+
echo <<<END
276
+
a
277
+
b
278
+
c
279
+
END;
280
+
]]>
281
+
</programlisting>
282
+
&example.outputs.73;
283
+
<screen>
284
+
<![CDATA[
285
+
Parse error: Invalid body indentation level (expecting an indentation level of at least 3) in example.php on line 4
286
+
]]>
287
+
</screen>
288
+
</example>
289
+

290
+
<simpara>
291
+
If the closing identifier is indented, tabs can be used as well, however,
292
+
tabs and spaces <emphasis>must not</emphasis> be intermixed regarding
293
+
the indentation of the closing identifier and the indentation of the body
294
+
(up to the closing identifier). In any of these cases, a <classname>ParseError</classname> will be thrown.
295
+

296
+
These whitespace constraints have been included because mixing tabs and
297
+
spaces for indentation is harmful to legibility.
298
+
</simpara>
299
+

300
+
<example>
301
+
<title>Different indentation for body (spaces) closing identifier</title>
302
+
<programlisting role="php" annotations="non-interactive">
303
+
<![CDATA[
304
+
<?php
305
+
// All the following code do not work.
306
+

307
+
// different indentation for body (spaces) ending marker (tabs)
308
+
{
309
+
echo <<<END
310
+
a
311
+
END;
312
+
}
313
+

314
+
// mixing spaces and tabs in body
315
+
{
316
+
echo <<<END
317
+
a
318
+
END;
319
+
}
320
+

321
+
// mixing spaces and tabs in ending marker
322
+
{
323
+
echo <<<END
324
+
a
325
+
END;
326
+
}
327
+
]]>
328
+
</programlisting>
329
+
&example.outputs.73;
330
+
<screen>
331
+
<![CDATA[
332
+
Parse error: Invalid indentation - tabs and spaces cannot be mixed in example.php line 8
333
+
]]>
334
+
</screen>
335
+
</example>
336
+

337
+
<simpara>
338
+
The closing identifier for the body string is not required to be
339
+
followed by a semicolon or newline. For example, the following code
340
+
is allowed as of PHP 7.3.0:
341
+
</simpara>
342
+

343
+
<example>
344
+
<title>Continuing an expression after a closing identifier</title>
345
+
<programlisting role="php">
346
+
<![CDATA[
347
+
<?php
348
+
$values = [<<<END
349
+
a
350
+
b
351
+
c
352
+
END, 'd e f'];
353
+
var_dump($values);
354
+
]]>
355
+
</programlisting>
356
+
&example.outputs.73;
357
+
<screen>
358
+
<![CDATA[
359
+
array(2) {
360
+
[0] =>
361
+
string(11) "a
362
+
b
363
+
c"
364
+
[1] =>
365
+
string(5) "d e f"
366
+
}
367
+
]]>
368
+
</screen>
369
+
</example>
370
+

371
+
<warning>
372
+
<simpara>
373
+
If the closing identifier was found at the start of a line, then
374
+
regardless of whether it was a part of another word, it may be considered
375
+
as the closing identifier and causes a <classname>ParseError</classname>.
376
+
</simpara>
377
+

378
+
<example>
379
+
<title>Closing identifier in body of the string tends to cause ParseError</title>
380
+
<programlisting role="php">
381
+
<![CDATA[
382
+
<?php
383
+
$values = [<<<END
384
+
a
385
+
b
386
+
END ING
387
+
END, 'd e f'];
388
+
]]>
389
+
</programlisting>
390
+
&example.outputs.73;
391
+
<screen>
392
+
<![CDATA[
393
+
Parse error: syntax error, unexpected identifier "ING", expecting "]" in example.php on line 5
394
+
]]>
395
+
</screen>
396
+
</example>
397
+

398
+
<simpara>
399
+
To avoid this problem, it is safe to follow the simple rule:
400
+
<emphasis>do not choose a word that appears in the body of the text
401
+
as a closing identifier</emphasis>.
402
+
</simpara>
403
+

404
+
</warning>
405
+

215
406
<warning>
216
407
<simpara>
217
-
It is very important to note that the line with the closing identifier must
218
-
contain no other characters, except a semicolon (<literal>;</literal>).
408
+
Prior to PHP 7.3.0, it is very important to note that the line with the
409
+
closing identifier must contain no other characters, except a semicolon
410
+
(<literal>;</literal>).
219
411
That means especially that the identifier
220
412
<emphasis>may not be indented</emphasis>, and there may not be any spaces
221
413
or tabs before or after the semicolon. It's also important to realize that
222
414
the first character before the closing identifier must be a newline as
223
415
defined by the local operating system. This is <literal>\n</literal> on
224
-
UNIX systems, including Mac OS X. The closing delimiter must also be
416
+
UNIX systems, including macOS. The closing delimiter must also be
225
417
followed by a newline.
226
418
</simpara>
227
419

...
...
@@ -232,14 +424,10 @@ echo 'Variables do not $expand $either';
232
424
current file, a parse error will result at the last line.
233
425
</simpara>
234
426

235
-
<para>
236
-
Heredocs can not be used for initializing class properties. Since PHP 5.3,
237
-
this limitation is valid only for heredocs containing variables.
238
-
</para>
239
-
240
427
<example>
241
-
<title>Invalid example</title>
428
+
<title>Invalid example, prior to PHP 7.3.0</title>
242
429
<programlisting role="php">
430
+
<!-- This is an INVALID example -->
243
431
<![CDATA[
244
432
<?php
245
433
class foo {
...
...
@@ -247,10 +435,31 @@ class foo {
247
435
bar
248
436
EOT;
249
437
}
438
+
// Identifier must not be indented
439
+
?>
440
+
]]>
441
+
</programlisting>
442
+
</example>
443
+
<example>
444
+
<title>Valid example, even prior to PHP 7.3.0</title>
445
+
<programlisting role="php">
446
+
<!-- This is a VALID example -->
447
+
<![CDATA[
448
+
<?php
449
+
class foo {
450
+
public $bar = <<<EOT
451
+
bar
452
+
EOT;
453
+
}
250
454
?>
251
455
]]>
252
456
</programlisting>
253
457
</example>
458
+

459
+
<para>
460
+
Heredocs containing variables can not be used for initializing class properties.
461
+
</para>
462
+

254
463
</warning>
255
464

256
465
<para>
...
...
@@ -278,7 +487,7 @@ class foo
278
487
var $foo;
279
488
var $bar;
280
489

281
-
function foo()
490
+
function __construct()
282
491
{
283
492
$this->foo = 'Foo';
284
493
$this->bar = array('Bar1', 'Bar2', 'Bar3');
...
...
@@ -325,13 +534,13 @@ EOD
325
534
</example>
326
535

327
536
<para>
328
-
As of PHP 5.3.0, it's possible to initialize static variables and class
537
+
It's possible to initialize static variables and class
329
538
properties/constants using the Heredoc syntax:
330
539
</para>
331
540

332
541
<example>
333
542
<title>Using Heredoc to initialize static values</title>
334
-
<programlisting role="php">
543
+
<programlisting role="php" annotations="non-interactive">
335
544
<![CDATA[
336
545
<?php
337
546
// Static variables
...
...
@@ -359,7 +568,7 @@ FOOBAR;
359
568
</example>
360
569

361
570
<para>
362
-
Starting with PHP 5.3.0, the opening Heredoc identifier may optionally be
571
+
The opening Heredoc identifier may optionally be
363
572
enclosed in double quotes:
364
573
</para>
365
574

...
...
@@ -384,7 +593,7 @@ FOOBAR;
384
593
<para>
385
594
Nowdocs are to single-quoted strings what heredocs are to double-quoted
386
595
strings. A nowdoc is specified similarly to a heredoc, but <emphasis>no
387
-
parsing is done</emphasis> inside a nowdoc. The construct is ideal for
596
+
String interpolation is done</emphasis> inside a nowdoc. The construct is ideal for
388
597
embedding PHP code or other large blocks of text without the need for
389
598
escaping. It shares some features in common with the SGML
390
599
<literal>&lt;![CDATA[ ]]&gt;</literal> construct, in that it declares a
...
...
@@ -404,19 +613,34 @@ FOOBAR;
404
613
<programlisting role="php">
405
614
<![CDATA[
406
615
<?php
407
-
$str = <<<'EOD'
408
-
Example of string
409
-
spanning multiple lines
410
-
using nowdoc syntax.
616
+
echo <<<'EOD'
617
+
Example of string spanning multiple lines
618
+
using nowdoc syntax. Backslashes are always treated literally,
619
+
e.g. \\ and \'.
411
620
EOD;
621
+
]]>
622
+
</programlisting>
623
+
&example.outputs;
624
+
<screen>
625
+
<![CDATA[
626
+
Example of string spanning multiple lines
627
+
using nowdoc syntax. Backslashes are always treated literally,
628
+
e.g. \\ and \'.
629
+
]]>
630
+
</screen>
631
+
</example>
412
632

413
-
/* More complex example, with variables. */
633
+
<example>
634
+
<title>Nowdoc string quoting example with variables</title>
635
+
<programlisting role="php">
636
+
<![CDATA[
637
+
<?php
414
638
class foo
415
639
{
416
640
public $foo;
417
641
public $bar;
418
642

419
-
function foo()
643
+
function __construct()
420
644
{
421
645
$this->foo = 'Foo';
422
646
$this->bar = array('Bar1', 'Bar2', 'Bar3');
...
...
@@ -443,16 +667,9 @@ This should not print a capital 'A': \x41]]>
443
667
</screen>
444
668
</example>
445
669

446
-
<note>
447
-
<para>
448
-
Unlike heredocs, nowdocs can be used in any static data context. The
449
-
typical example is initializing class properties or constants:
450
-
</para>
451
-
</note>
452
-
453
670
<example>
454
671
<title>Static data example</title>
455
-
<programlisting role="php">
672
+
<programlisting role="php" annotations="non-interactive">
456
673
<![CDATA[
457
674
<?php
458
675
class foo {
...
...
@@ -465,55 +682,41 @@ EOT;
465
682
</programlisting>
466
683
</example>
467
684

468
-
<note>
469
-
<para>
470
-
Nowdoc support was added in PHP 5.3.0.
471
-
</para>
472
-
</note>
473
-

474
685
</sect3>
475
686

476
687
<sect3 xml:id="language.types.string.parsing">
477
-
<title>Variable parsing</title>
688
+
<title>String interpolation</title>
478
689

479
690
<simpara>
480
691
When a <type>string</type> is specified in double quotes or with heredoc,
481
-
<link linkend="language.variables">variables</link> are parsed within it.
692
+
<link linkend="language.variables">variables</link> can be substituted within it.
482
693
</simpara>
483
694

484
695
<simpara>
485
696
There are two types of syntax: a
486
-
<link linkend="language.types.string.parsing.simple">simple</link> one and a
487
-
<link linkend="language.types.string.parsing.complex">complex</link> one.
488
-
The simple syntax is the most common and convenient. It provides a way to
697
+
<link linkend="language.types.string.parsing.basic">basic</link> one and an
698
+
<link linkend="language.types.string.parsing.advanced">advanced</link> one.
699
+
The basic syntax is the most common and convenient. It provides a way to
489
700
embed a variable, an <type>array</type> value, or an <type>object</type>
490
701
property in a <type>string</type> with a minimum of effort.
491
702
</simpara>
492
703

493
-
<simpara>
494
-
The complex syntax can be recognised by the
495
-
curly braces surrounding the expression.
496
-
</simpara>
497
-

498
-
<sect4 xml:id="language.types.string.parsing.simple">
499
-
<title>Simple syntax</title>
500
-

704
+
<sect4 xml:id="language.types.string.parsing.basic">
705
+
<title>Basic syntax</title>
501
706
<simpara>
502
-
If a dollar sign (<literal>$</literal>) is encountered, the parser will
503
-
greedily take as many tokens as possible to form a valid variable name.
504
-
Enclose the variable name in curly braces to explicitly specify the end of
505
-
the name.
707
+
If a dollar sign (<literal>$</literal>) is encountered, the characters
708
+
that follow it which can be used in a variable name will be interpreted
709
+
as such and substituted.
506
710
</simpara>
507
-

508
-
<informalexample>
711
+
<example>
712
+
<title>String Interpolation</title>
509
713
<programlisting role="php">
510
714
<![CDATA[
511
715
<?php
512
716
$juice = "apple";
513
717

514
-
echo "He drank some $juice juice.".PHP_EOL;
515
-
// Invalid. "s" is a valid character for a variable name, but the variable is $juice.
516
-
echo "He drank some juice made of $juices.";
718
+
echo "He drank some $juice juice." . PHP_EOL;
719
+

517
720
?>
518
721
]]>
519
722
</programlisting>
...
...
@@ -521,42 +724,131 @@ echo "He drank some juice made of $juices.";
521
724
<screen>
522
725
<![CDATA[
523
726
He drank some apple juice.
524
-
He drank some juice made of .
525
727
]]>
526
728
</screen>
527
-
</informalexample>
729
+
</example>
528
730

529
731
<simpara>
530
-
Similarly, an <type>array</type> index or an <type>object</type> property
531
-
can be parsed. With array indices, the closing square bracket
532
-
(<literal>]</literal>) marks the end of the index. The same rules apply to
533
-
object properties as to simple variables.
732
+
Formally, the structure for the basic variable substitution syntax is
733
+
as follows:
534
734
</simpara>
735
+
<informalexample>
736
+
<programlisting>
737
+
<![CDATA[
738
+
string-variable::
739
+
variable-name (offset-or-property)?
740
+
| ${ expression }
535
741

536
-
<example><title>Simple syntax example</title>
537
-
<programlisting role="php">
742
+
offset-or-property::
743
+
offset-in-string
744
+
| property-in-string
745
+

746
+
offset-in-string::
747
+
[ name ]
748
+
| [ variable-name ]
749
+
| [ integer-literal ]
750
+

751
+
property-in-string::
752
+
-> name
753
+

754
+
variable-name::
755
+
$ name
756
+

757
+
name::
758
+
[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*
759
+

760
+
]]>
761
+
</programlisting>
762
+
</informalexample>
763
+

764
+
<warning>
765
+
<para>
766
+
The <literal>${ expression }</literal> syntax is deprecated as of
767
+
PHP 8.2.0, as it can be interpreted as
768
+
<link linkend="language.variables.variable">variable variables</link>:
769
+
<informalexample>
770
+
<programlisting role="php">
771
+
<![CDATA[
772
+
<?php
773
+
const foo = 'bar';
774
+
$foo = 'foo';
775
+
$bar = 'bar';
776
+
var_dump("${foo}");
777
+
var_dump("${(foo)}");
778
+
?>
779
+
]]>
780
+
</programlisting>
781
+
&example.outputs.82;
782
+
<screen>
783
+
<![CDATA[
784
+
Deprecated: Using ${var} in strings is deprecated, use {$var} instead in file on line 6
785
+

786
+
Deprecated: Using ${expr} (variable variables) in strings is deprecated, use {${expr}} instead in file on line 9
787
+
string(3) "foo"
788
+
string(3) "bar"
789
+
]]>
790
+
</screen>
791
+
&example.outputs;
792
+
<screen>
793
+
<![CDATA[
794
+
string(3) "foo"
795
+
string(3) "bar"
796
+
]]>
797
+
</screen>
798
+
</informalexample>
799
+
The <link linkend="language.types.string.parsing.advanced">advanced</link>
800
+
string interpolation syntax should be used instead.
801
+
</para>
802
+
</warning>
803
+

804
+
<note>
805
+
<simpara>
806
+
If it is not possible to form a valid name the dollar sign remains
807
+
as verbatim in the string:
808
+
</simpara>
809
+
<informalexample>
810
+
<programlisting role="php">
538
811
<![CDATA[
539
812
<?php
540
-
$juices = array("apple", "orange", "koolaid1" => "purple");
813
+
echo "No interpolation $ has happened\n";
814
+
echo "No interpolation $\n has happened\n";
815
+
echo "No interpolation $2 has happened\n";
816
+
?>
817
+
]]>
818
+
</programlisting>
819
+
&example.outputs;
820
+
<screen>
821
+
<![CDATA[
822
+
No interpolation $ has happened
823
+
No interpolation $
824
+
has happened
825
+
No interpolation $2 has happened
826
+
]]>
827
+
</screen>
828
+
</informalexample>
829
+
</note>
541
830

542
-
echo "He drank some $juices[0] juice.".PHP_EOL;
543
-
echo "He drank some $juices[1] juice.".PHP_EOL;
544
-
echo "He drank some $juices[koolaid1] juice.".PHP_EOL;
831
+
<example>
832
+
<title>Interpolating the value of the first dimension of an array or property</title>
833
+
<programlisting role="php">
834
+
<![CDATA[
835
+
<?php
836
+
$juices = array("apple", "orange", "string_key" => "purple");
545
837

546
-
class people {
547
-
public $john = "John Smith";
548
-
public $jane = "Jane Smith";
549
-
public $robert = "Robert Paulsen";
838
+
echo "He drank some $juices[0] juice.";
839
+
echo PHP_EOL;
840
+
echo "He drank some $juices[1] juice.";
841
+
echo PHP_EOL;
842
+
echo "He drank some $juices[string_key] juice.";
843
+
echo PHP_EOL;
550
844

551
-
public $smith = "Smith";
845
+
class A {
846
+
public $s = "string";
552
847
}
553
848

554
-
$people = new people();
849
+
$o = new A();
555
850

556
-
echo "$people->john drank some $juices[0] juice.".PHP_EOL;
557
-
echo "$people->john then said hello to $people->jane.".PHP_EOL;
558
-
echo "$people->john's wife greeted $people->robert.".PHP_EOL;
559
-
echo "$people->robert greeted the two $people->smiths."; // Won't work
851
+
echo "Object value: $o->s.";
560
852
?>
561
853
]]>
562
854
</programlisting>
...
...
@@ -566,56 +858,105 @@ echo "$people->robert greeted the two $people->smiths."; // Won't work
566
858
He drank some apple juice.
567
859
He drank some orange juice.
568
860
He drank some purple juice.
569
-
John Smith drank some apple juice.
570
-
John Smith then said hello to Jane Smith.
571
-
John Smith's wife greeted Robert Paulsen.
572
-
Robert Paulsen greeted the two .
861
+
Object value: string.
862
+
]]>
863
+
</screen>
864
+
</example>
865
+

866
+
<note>
867
+
<simpara>
868
+
The array key must be unquoted, and it is therefore not possible to
869
+
refer to a constant as a key with the basic syntax. Use the
870
+
<link linkend="language.types.string.parsing.advanced">advanced</link>
871
+
syntax instead.
872
+
</simpara>
873
+
</note>
874
+

875
+
<simpara>
876
+
As of PHP 7.1.0 also <emphasis>negative</emphasis> numeric indices are
877
+
supported.
878
+
</simpara>
879
+

880
+
<example><title>Negative numeric indices</title>
881
+
<programlisting role="php">
882
+
<![CDATA[
883
+
<?php
884
+
$string = 'string';
885
+
echo "The character at index -2 is $string[-2].", PHP_EOL;
886
+
$string[-3] = 'o';
887
+
echo "Changing the character at index -3 to o gives $string.", PHP_EOL;
888
+
?>
889
+
]]>
890
+
</programlisting>
891
+
&example.outputs;
892
+
<screen>
893
+
<![CDATA[
894
+
The character at index -2 is n.
895
+
Changing the character at index -3 to o gives strong.
573
896
]]>
574
897
</screen>
575
898
</example>
576
899

577
900
<simpara>
578
-
For anything more complex, you should use the complex syntax.
901
+
For anything more complex, the
902
+
<link linkend="language.types.string.parsing.advanced">advanced</link>
903
+
syntax must be used.
579
904
</simpara>
580
905
</sect4>
581
906

582
-
<sect4 xml:id="language.types.string.parsing.complex">
583
-
<title>Complex (curly) syntax</title>
907
+
<sect4 xml:id="language.types.string.parsing.advanced">
908
+
<title>Advanced (curly) syntax</title>
584
909

585
910
<simpara>
586
-
This isn't called complex because the syntax is complex, but because it
587
-
allows for the use of complex expressions.
911
+
The advanced syntax permits the interpolation of
912
+
<emphasis>variables</emphasis> with arbitrary accessors.
588
913
</simpara>
589
914

590
915
<simpara>
591
-
Any scalar variable, array element or object property with a
916
+
Any scalar variable, array element or object property
917
+
(<modifier>static</modifier> or not) with a
592
918
<type>string</type> representation can be included via this syntax.
593
-
Simply write the expression the same way as it would appear outside the
594
-
<type>string</type>, and then wrap it in <literal>{</literal> and
919
+
The expression is written the same way as it would appear outside the
920
+
<type>string</type>, and then wrapped in <literal>{</literal> and
595
921
<literal>}</literal>. Since <literal>{</literal> can not be escaped, this
596
922
syntax will only be recognised when the <literal>$</literal> immediately
597
923
follows the <literal>{</literal>. Use <literal>{\$</literal> to get a
598
924
literal <literal>{$</literal>. Some examples to make it clear:
599
925
</simpara>
600
926

601
-
<informalexample>
927
+
<example>
928
+
<title>Curly Syntax</title>
602
929
<programlisting role="php">
603
930
<![CDATA[
604
931
<?php
605
-
// Show all errors
606
-
error_reporting(E_ALL);
607
-

932
+
const DATA_KEY = 'const-key';
608
933
$great = 'fantastic';
934
+
$arr = [
935
+
'1',
936
+
'2',
937
+
'3',
938
+
[41, 42, 43],
939
+
'key' => 'Indexed value',
940
+
'const-key' => 'Key with minus sign',
941
+
'foo' => ['foo1', 'foo2', 'foo3']
942
+
];
609
943

610
944
// Won't work, outputs: This is { fantastic}
611
945
echo "This is { $great}";
612
946

613
947
// Works, outputs: This is fantastic
614
948
echo "This is {$great}";
615
-
echo "This is ${great}";
949
+

950
+
class Square {
951
+
public $width;
952
+

953
+
public function __construct(int $width) { $this->width = $width; }
954
+
}
955
+

956
+
$square = new Square(5);
616
957

617
958
// Works
618
-
echo "This square is {$square->width}00 centimeters broad.";
959
+
echo "This square is {$square->width}00 centimeters wide.";
619
960

620
961

621
962
// Works, quoted keys only work using the curly brace syntax
...
...
@@ -623,109 +964,35 @@ echo "This works: {$arr['key']}";
623
964

624
965

625
966
// Works
626
-
echo "This works: {$arr[4][3]}";
967
+
echo "This works: {$arr[3][2]}";
627
968

628
-
// This is wrong for the same reason as $foo[bar] is wrong outside a string.
629
-
// In other words, it will still work, but only because PHP first looks for a
630
-
// constant named foo; an error of level E_NOTICE (undefined constant) will be
631
-
// thrown.
632
-
echo "This is wrong: {$arr[foo][3]}";
969
+
echo "This works: {$arr[DATA_KEY]}";
633
970

634
-
// Works. When using multi-dimensional arrays, always use braces around arrays
971
+
// When using multidimensional arrays, always use braces around arrays
635
972
// when inside of strings
636
-
echo "This works: {$arr['foo'][3]}";
637
-

638
-
// Works.
639
-
echo "This works: " . $arr['foo'][3];
640
-

641
-
echo "This works too: {$obj->values[3]->name}";
973
+
echo "This works: {$arr['foo'][2]}";
642
974

643
-
echo "This is the value of the var named $name: {${$name}}";
975
+
echo "This works: {$obj->values[3]->name}";
644
976

645
-
echo "This is the value of the var named by the return value of getName(): {${getName()}}";
977
+
echo "This works: {$obj->$staticProp}";
646
978

647
-
echo "This is the value of the var named by the return value of \$object->getName(): {${$object->getName()}}";
979
+
// Won't work, outputs: C:\directory\{fantastic}.txt
980
+
echo "C:\directory\{$great}.txt";
648
981

649
-
// Won't work, outputs: This is the return value of getName(): {getName()}
650
-
echo "This is the return value of getName(): {getName()}";
982
+
// Works, outputs: C:\directory\fantastic.txt
983
+
echo "C:\\directory\\{$great}.txt";
651
984
?>
652
985
]]>
653
-
<!-- maybe it's better to leave this out??
654
-
// this works, but i disencourage its use, since this is NOT
655
-
// involving functions, rather than mere variables, arrays and objects.
656
-
$beer = 'Heineken';
657
-
echo "I'd like to have another {${ strrev('reeb') }}, hips";
658
-
-->
659
986
</programlisting>
660
-
</informalexample>
661
-

662
-
<para>
663
-
It is also possible to access class properties using variables
664
-
within strings using this syntax.
665
-
</para>
666
-

667
-
<informalexample>
668
-
<programlisting role="php">
669
-
<![CDATA[
670
-
<?php
671
-
class foo {
672
-
var $bar = 'I am bar.';
673
-
}
674
-

675
-
$foo = new foo();
676
-
$bar = 'bar';
677
-
$baz = array('foo', 'bar', 'baz', 'quux');
678
-
echo "{$foo->$bar}\n";
679
-
echo "{$foo->$baz[1]}\n";
680
-
?>
681
-
]]>
682
-
</programlisting>
683
-
&example.outputs;
684
-
<screen>
685
-
<![CDATA[
686
-
I am bar.
687
-
I am bar.
688
-
]]>
689
-
</screen>
690
-
</informalexample>
987
+
</example>
691
988

692
989
<note>
693
-
<para>
694
-
Functions, method calls, static class variables, and class
695
-
constants inside <literal>{$}</literal> work since PHP
696
-
5. However, the value accessed will be interpreted as the name
697
-
of a variable in the scope in which the string is defined. Using
698
-
single curly braces (<literal>{}</literal>) will not work for
699
-
accessing the return values of functions or methods or the
700
-
values of class constants or static class variables.
701
-
</para>
990
+
<simpara>
991
+
As this syntax allows arbitrary expressions it is possible to use
992
+
<link linkend="language.variables.variable">variable variables</link>
993
+
within the advanced syntax.
994
+
</simpara>
702
995
</note>
703
-

704
-
<informalexample>
705
-
<programlisting role="php">
706
-
<![CDATA[
707
-
<?php
708
-
// Show all errors.
709
-
error_reporting(E_ALL);
710
-

711
-
class beers {
712
-
const softdrink = 'rootbeer';
713
-
public static $ale = 'ipa';
714
-
}
715
-

716
-
$rootbeer = 'A & W';
717
-
$ipa = 'Alexander Keith\'s';
718
-

719
-
// This works; outputs: I'd like an A & W
720
-
echo "I'd like an {${beers::softdrink}}\n";
721
-

722
-
// This works too; outputs: I'd like an Alexander Keith's
723
-
echo "I'd like an {${beers::$ale}}\n";
724
-
?>
725
-
]]>
726
-
</programlisting>
727
-
</informalexample>
728
-

729
996
</sect4>
730
997
</sect3>
731
998

...
...
@@ -744,8 +1011,19 @@ echo "I'd like an {${beers::$ale}}\n";
744
1011

745
1012
<note>
746
1013
<simpara>
747
-
<type>String</type>s may also be accessed using braces, as in
1014
+
As of PHP 7.1.0, negative string offsets are also supported. These specify
1015
+
the offset from the end of the string.
1016
+
Formerly, negative offsets emitted <constant>E_NOTICE</constant> for reading
1017
+
(yielding an empty string) and <constant>E_WARNING</constant> for writing
1018
+
(leaving the string untouched).
1019
+
</simpara>
1020
+
</note>
1021
+

1022
+
<note>
1023
+
<simpara>
1024
+
Prior to PHP 8.0.0, <type>string</type>s could also be accessed using braces, as in
748
1025
<varname>$str{42}</varname>, for the same purpose.
1026
+
This curly brace syntax was deprecated as of PHP 7.4.0 and no longer supported as of PHP 8.0.0.
749
1027
</simpara>
750
1028
</note>
751
1029

...
...
@@ -753,10 +1031,10 @@ echo "I'd like an {${beers::$ale}}\n";
753
1031
<simpara>
754
1032
Writing to an out of range offset pads the string with spaces.
755
1033
Non-integer types are converted to integer.
756
-
Illegal offset type emits <constant>E_NOTICE</constant>.
757
-
Negative offset emits <constant>E_NOTICE</constant> in write but reads empty string.
1034
+
Illegal offset type emits <constant>E_WARNING</constant>.
758
1035
Only the first character of an assigned string is used.
759
-
Assigning empty string assigns NULL byte.
1036
+
As of PHP 7.1.0, assigning an empty string throws a fatal error. Formerly,
1037
+
it assigned a NULL byte.
760
1038
</simpara>
761
1039
</warning>
762
1040

...
...
@@ -769,6 +1047,13 @@ echo "I'd like an {${beers::$ale}}\n";
769
1047
</simpara>
770
1048
</warning>
771
1049

1050
+
<note>
1051
+
<simpara>
1052
+
As of PHP 7.1.0, applying the empty index operator on an empty string throws a fatal
1053
+
error. Formerly, the empty string was silently converted to an array.
1054
+
</simpara>
1055
+
</note>
1056
+

772
1057
<example>
773
1058
<title>Some string examples</title>
774
1059
<programlisting role="php">
...
...
@@ -777,77 +1062,70 @@ echo "I'd like an {${beers::$ale}}\n";
777
1062
// Get the first character of a string
778
1063
$str = 'This is a test.';
779
1064
$first = $str[0];
1065
+
var_dump($first);
780
1066

781
1067
// Get the third character of a string
782
1068
$third = $str[2];
1069
+
var_dump($third);
783
1070

784
1071
// Get the last character of a string.
785
1072
$str = 'This is still a test.';
786
1073
$last = $str[strlen($str)-1];
1074
+
var_dump($last);
787
1075

788
1076
// Modify the last character of a string
789
1077
$str = 'Look at the sea';
790
1078
$str[strlen($str)-1] = 'e';
791
-

1079
+
var_dump($str);
792
1080
?>
793
1081
]]>
794
1082
</programlisting>
795
1083
</example>
796
1084

797
1085
<para>
798
-
As of PHP 5.4 string offsets have to either be integers or integer-like strings, otherwise a warning
799
-
will be thrown. Previously an offset like <literal>"foo"</literal> was silently cast to <literal>0</literal>.
1086
+
String offsets have to either be integers or integer-like strings,
1087
+
otherwise a warning will be thrown.
800
1088
</para>
801
1089

802
1090
<example>
803
-
<title>Differences between PHP 5.3 and PHP 5.4</title>
1091
+
<title>Example of Illegal String Offsets</title>
804
1092
<programlisting role="php">
805
1093
<![CDATA[
806
1094
<?php
807
1095
$str = 'abc';
808
1096

809
-
var_dump($str['1']);
810
-
var_dump(isset($str['1']));
1097
+
$keys = [ '1', '1.0', 'x', '1x' ];
811
1098

812
-
var_dump($str['1.0']);
813
-
var_dump(isset($str['1.0']));
1099
+
foreach ($keys as $keyToTry) {
1100
+
var_dump(isset($str[$keyToTry]));
814
1101

815
-
var_dump($str['x']);
816
-
var_dump(isset($str['x']));
1102
+
try {
1103
+
var_dump($str[$keyToTry]);
1104
+
} catch (TypeError $e) {
1105
+
echo $e->getMessage(), PHP_EOL;
1106
+
}
817
1107

818
-
var_dump($str['1x']);
819
-
var_dump(isset($str['1x']));
1108
+
echo PHP_EOL;
1109
+
}
820
1110
?>
821
1111
]]>
822
1112
</programlisting>
823
-
&example.outputs.53;
1113
+
&example.outputs;
824
1114
<screen>
825
1115
<![CDATA[
826
-
string(1) "b"
827
-
bool(true)
828
-
string(1) "b"
829
-
bool(true)
830
-
string(1) "a"
831
1116
bool(true)
832
1117
string(1) "b"
833
-
bool(true)
834
-
]]>
835
-
</screen>
836
-
&example.outputs.54;
837
-
<screen>
838
-
<![CDATA[
839
-
string(1) "b"
840
-
bool(true)
841
1118

842
-
Warning: Illegal string offset '1.0' in /tmp/t.php on line 7
843
-
string(1) "b"
844
1119
bool(false)
1120
+
Cannot access offset of type string on string
845
1121

846
-
Warning: Illegal string offset 'x' in /tmp/t.php on line 9
847
-
string(1) "a"
848
1122
bool(false)
849
-
string(1) "b"
1123
+
Cannot access offset of type string on string
1124
+

850
1125
bool(false)
1126
+

1127
+
Warning: Illegal string offset "1x" in Standard input code on line 10
1128
+
string(1) "b"
851
1129
]]>
852
1130
</screen>
853
1131
</example>
...
...
@@ -862,10 +1140,18 @@ bool(false)
862
1140

863
1141
<note>
864
1142
<para>
865
-
PHP 5.5 added support for accessing characters within string literals
1143
+
Characters within string literals can be accessed
866
1144
using <literal>[]</literal> or <literal>{}</literal>.
867
1145
</para>
868
1146
</note>
1147
+

1148
+
<note>
1149
+
<para>
1150
+
Accessing characters within string literals using the
1151
+
<literal>{}</literal> syntax has been deprecated in PHP 7.4.
1152
+
This has been removed in PHP 8.0.
1153
+
</para>
1154
+
</note>
869
1155
</sect3>
870
1156
</sect2><!-- end syntax -->
871
1157

...
...
@@ -885,16 +1171,15 @@ bool(false)
885
1171

886
1172
<simpara>
887
1173
See the <link linkend="ref.strings">string functions section</link> for
888
-
general functions, and the <link linkend="ref.regex">regular expression
889
-
functions</link> or the <link linkend="ref.pcre">Perl-compatible regular
1174
+
general functions, and the <link linkend="ref.pcre">Perl-compatible regular
890
1175
expression functions</link> for advanced find &amp; replace functionality.
891
1176
</simpara>
892
1177

893
1178
<simpara>
894
1179
There are also <link linkend="ref.url">functions for URL strings</link>, and
895
1180
functions to encrypt/decrypt strings
896
-
(<link linkend="ref.mcrypt">mcrypt</link> and
897
-
<link linkend="ref.mhash">mhash</link>).
1181
+
(<link linkend="ref.sodium">Sodium</link> and
1182
+
<link linkend="ref.hash">Hash</link>).
898
1183
</simpara>
899
1184

900
1185
<simpara>
...
...
@@ -919,14 +1204,14 @@ bool(false)
919
1204
</para>
920
1205

921
1206
<para>
922
-
A <type>boolean</type> &true; value is converted to the <type>string</type>
923
-
<literal>"1"</literal>. <type>Boolean</type> &false; is converted to
1207
+
A <type>bool</type> &true; value is converted to the <type>string</type>
1208
+
<literal>"1"</literal>. <type>bool</type> &false; is converted to
924
1209
<literal>""</literal> (the empty string). This allows conversion back and
925
-
forth between <type>boolean</type> and <type>string</type> values.
1210
+
forth between <type>bool</type> and <type>string</type> values.
926
1211
</para>
927
1212

928
1213
<para>
929
-
An <type>integer</type> or <type>float</type> is converted to a
1214
+
An <type>int</type> or <type>float</type> is converted to a
930
1215
<type>string</type> representing the number textually (including the
931
1216
exponent part for <type>float</type>s). Floating point numbers can be
932
1217
converted using exponential notation (<literal>4.1E+6</literal>).
...
...
@@ -934,7 +1219,9 @@ bool(false)
934
1219

935
1220
<note>
936
1221
<para>
937
-
The decimal point character is defined in the script's locale (category
1222
+
As of PHP 8.0.0, the decimal point character is always
1223
+
a period ("<literal>.</literal>"). Prior to PHP 8.0.0,
1224
+
the decimal point character is defined in the script's locale (category
938
1225
LC_NUMERIC). See the <function>setlocale</function> function.
939
1226
</para>
940
1227
</note>
...
...
@@ -949,12 +1236,8 @@ bool(false)
949
1236
</para>
950
1237

951
1238
<para>
952
-
<type>Object</type>s in PHP 4 are always converted to the <type>string</type>
953
-
<literal>"Object"</literal>. To print the values of object properties for
954
-
debugging reasons, read the paragraphs below. To get an object's class name,
955
-
use the <function>get_class</function> function. As of PHP 5, the
956
-
<link linkend="language.oop5.magic">__toString</link> method is used when
957
-
applicable.
1239
+
In order to convert <type>object</type>s to <type>string</type>, the magic
1240
+
method <link linkend="language.oop5.magic">__toString</link> must be used.
958
1241
</para>
959
1242

960
1243
<para>
...
...
@@ -983,80 +1266,7 @@ bool(false)
983
1266
<para>
984
1267
Most PHP values can also be converted to <type>string</type>s for permanent
985
1268
storage. This method is called serialization, and is performed by the
986
-
<function>serialize</function> function. If the PHP engine was built with
987
-
<link linkend="ref.wddx">WDDX</link> support, PHP values can also be
988
-
serialized as well-formed XML text.
989
-
</para>
990
-

991
-
</sect2>
992
-

993
-
<sect2 xml:id="language.types.string.conversion">
994
-
<title>String conversion to numbers</title>
995
-

996
-
<simpara>
997
-
When a <type>string</type> is evaluated in a numeric context, the resulting
998
-
value and type are determined as follows.
999
-
</simpara>
1000
-

1001
-
<simpara>
1002
-
If the <type>string</type> does not contain any of the characters '.', 'e',
1003
-
or 'E' and the numeric value fits into integer type limits (as defined by
1004
-
<constant>PHP_INT_MAX</constant>), the <type>string</type> will be evaluated
1005
-
as an <type>integer</type>. In all other cases it will be evaluated as a
1006
-
<type>float</type>.
1007
-
</simpara>
1008
-

1009
-
<para>
1010
-
The value is given by the initial portion of the <type>string</type>. If the
1011
-
<type>string</type> starts with valid numeric data, this will be the value
1012
-
used. Otherwise, the value will be 0 (zero). Valid numeric data is an
1013
-
optional sign, followed by one or more digits (optionally containing a
1014
-
decimal point), followed by an optional exponent. The exponent is an 'e' or
1015
-
'E' followed by one or more digits.
1016
-
</para>
1017
-

1018
-
<informalexample>
1019
-
<programlisting role="php">
1020
-
<![CDATA[
1021
-
<?php
1022
-
$foo = 1 + "10.5"; // $foo is float (11.5)
1023
-
$foo = 1 + "-1.3e3"; // $foo is float (-1299)
1024
-
$foo = 1 + "bob-1.3e3"; // $foo is integer (1)
1025
-
$foo = 1 + "bob3"; // $foo is integer (1)
1026
-
$foo = 1 + "10 Small Pigs"; // $foo is integer (11)
1027
-
$foo = 4 + "10.2 Little Piggies"; // $foo is float (14.2)
1028
-
$foo = "10.0 pigs " + 1; // $foo is float (11)
1029
-
$foo = "10.0 pigs " + 1.0; // $foo is float (11)
1030
-
?>
1031
-
]]>
1032
-
</programlisting>
1033
-
</informalexample>
1034
-

1035
-
<simpara>
1036
-
For more information on this conversion, see the Unix manual page for
1037
-
strtod(3).
1038
-
</simpara>
1039
-

1040
-
<para>
1041
-
To test any of the examples in this section, cut and paste the examples and
1042
-
insert the following line to see what's going on:
1043
-
</para>
1044
-

1045
-
<informalexample>
1046
-
<programlisting role="php">
1047
-
<![CDATA[
1048
-
<?php
1049
-
echo "\$foo==$foo; type is " . gettype ($foo) . "<br />\n";
1050
-
?>
1051
-
]]>
1052
-
</programlisting>
1053
-
</informalexample>
1054
-

1055
-
<para>
1056
-
Do not expect to get the code of one character by converting it to integer,
1057
-
as is done in C. Use the <function>ord</function> and
1058
-
<function>chr</function> functions to convert between ASCII codes and
1059
-
characters.
1269
+
<function>serialize</function> function.
1060
1270
</para>
1061
1271

1062
1272
</sect2>
...
...
@@ -1091,7 +1301,7 @@ echo "\$foo==$foo; type is " . gettype ($foo) . "<br />\n";
1091
1301
it is encoded in the script file. Thus, if the script is written in
1092
1302
ISO-8859-1, the string will be encoded in ISO-8859-1 and so on. However,
1093
1303
this does not apply if Zend Multibyte is enabled; in that case, the script
1094
-
may be written in an arbitrary encoding (which is explicity declared or is
1304
+
may be written in an arbitrary encoding (which is explicitly declared or is
1095
1305
detected) and then converted to a certain internal encoding, which is then
1096
1306
the encoding that will be used for the string literals.
1097
1307
Note that there are some constraints on the encoding of the script (or on the
...
...
@@ -1129,15 +1339,7 @@ echo "\$foo==$foo; type is " . gettype ($foo) . "<br />\n";
1129
1339
<listitem>
1130
1340
<simpara>
1131
1341
Others use the current locale (see <function>setlocale</function>), but
1132
-
operate byte-by-byte. This is the case of <function>strcasecmp</function>,
1133
-
<function>strtoupper</function> and <function>ucfirst</function>.
1134
-
This means they can be used only with single-byte encodings, as long as
1135
-
the encoding is matched by the locale. For instance
1136
-
<literal>strtoupper("á")</literal> may return <literal>"Á"</literal> if the
1137
-
locale is correctly set and <literal>á</literal> is encoded with a single
1138
-
byte. If it is encoded in UTF-8, the correct result will not be returned
1139
-
and the resulting string may or may not be returned corrupted, depending
1140
-
on the current locale.
1342
+
operate byte-by-byte.
1141
1343
</simpara>
1142
1344
</listitem>
1143
1345
<listitem>
...
...
@@ -1147,9 +1349,6 @@ echo "\$foo==$foo; type is " . gettype ($foo) . "<br />\n";
1147
1349
<link linkend="book.intl">intl</link> extension and in the
1148
1350
<link linkend="book.pcre">PCRE</link> extension
1149
1351
(in the last case, only when the <literal>u</literal> modifier is used).
1150
-
Although this is due to their special purpose, the function
1151
-
<function>utf8_decode</function> assumes a UTF-8 encoding and the
1152
-
function <function>utf8_encode</function> assumes an ISO-8859-1 encoding.
1153
1352
</simpara>
1154
1353
</listitem>
1155
1354
</itemizedlist>
1156
1355