reference/strings/functions/chr.xml
4d3d1ebea1eeecb7f76fb2fa8ecb55ef35d1d518
4d3d1ebea1eeecb7f76fb2fa8ecb55ef35d1d518
...
...
@@ -3,18 +3,21 @@
3
3
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.chr">
4
4
<refnamediv>
5
5
<refname>chr</refname>
6
-
<refpurpose>Return a specific character</refpurpose>
6
+
<refpurpose>Generate a single-byte string from a number</refpurpose>
7
7
</refnamediv>
8
8
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>string</type><methodname>chr</methodname>
13
-
<methodparam><type>int</type><parameter>ascii</parameter></methodparam>
13
+
<methodparam><type>int</type><parameter>codepoint</parameter></methodparam>
14
14
</methodsynopsis>
15
15
<para>
16
16
Returns a one-character string containing the character specified
17
-
by <parameter>ascii</parameter>.
17
+
by interpreting <parameter>codepoint</parameter> as an unsigned integer.
18
+
</para>
19
+
<para>
20
+
This can be used to create a one-character string in a single-byte encoding such as ASCII, ISO-8859, or Windows 1252, by passing the position of a desired character in the encoding's mapping table. However, note that this function is not aware of any string encoding, and in particular cannot be passed a Unicode code point value to generate a string in a multibyte encoding like UTF-8 or UTF-16.
18
21
</para>
19
22
<para>
20
23
This function complements <function>ord</function>.
...
...
@@ -26,10 +29,22 @@
26
29
<para>
27
30
<variablelist>
28
31
<varlistentry>
29
-
<term><parameter>ascii</parameter></term>
32
+
<term><parameter>codepoint</parameter></term>
30
33
<listitem>
31
34
<para>
32
-
The ascii code.
35
+
An integer between 0 and 255.
36
+
</para>
37
+
<para>
38
+
Values outside the valid range (0..255) will be bitwise and'ed with 255,
39
+
which is equivalent to the following algorithm:
40
+
<programlisting role="php">
41
+
<![CDATA[
42
+
while ($bytevalue < 0) {
43
+
$bytevalue += 256;
44
+
}
45
+
$bytevalue %= 256;
46
+
]]>
47
+
</programlisting>
33
48
</para>
34
49
</listitem>
35
50
</varlistentry>
...
...
@@ -40,34 +55,33 @@
40
55
<refsect1 role="returnvalues">
41
56
&reftitle.returnvalues;
42
57
<para>
43
-
Returns the specified character.
58
+
A single-character string containing the specified byte.
44
59
</para>
45
60
</refsect1>
46
-
<!-- FIXME PHP_6
61
+
47
62
<refsect1 role="changelog">
48
63
&reftitle.changelog;
49
-
<para>
50
-
<informaltable>
51
-
<tgroup cols="2">
52
-
<thead>
53
-
<row>
54
-
<entry>&Version;</entry>
55
-
<entry>&Description;</entry>
56
-
</row>
57
-
</thead>
58
-
<tbody>
59
-
<row>
60
-
<entry>6.0.0</entry>
61
-
<entry>
62
-
This function now uses codepoint as input.
63
-
</entry>
64
-
</row>
65
-
</tbody>
66
-
</tgroup>
67
-
</informaltable>
68
-
</para>
64
+
<informaltable>
65
+
<tgroup cols="2">
66
+
<thead>
67
+
<row>
68
+
<entry>&Version;</entry>
69
+
<entry>&Description;</entry>
70
+
</row>
71
+
</thead>
72
+
<tbody>
73
+
<row>
74
+
<entry>7.4.0</entry>
75
+
<entry>
76
+
The function no longer silently accepts unsupported <parameter>codepoint</parameter>s,
77
+
and casts these to <literal>0</literal>.
78
+
</entry>
79
+
</row>
80
+
</tbody>
81
+
</tgroup>
82
+
</informaltable>
69
83
</refsect1>
70
-
-->
84
+
71
85
<refsect1 role="examples">
72
86
&reftitle.examples;
73
87
<para>
...
...
@@ -76,6 +90,8 @@
76
90
<programlisting role="php">
77
91
<![CDATA[
78
92
<?php
93
+
// Assumes the string will be used as ASCII or an ASCII-compatible encoding
94
+
79
95
$str = "The string ends in escape: ";
80
96
$str .= chr(27); /* add an escape character at the end of $str */
81
97
...
...
@@ -86,6 +102,39 @@ $str = sprintf("The string ends in escape: %c", 27);
86
102
]]>
87
103
</programlisting>
88
104
</example>
105
+
<example>
106
+
<title>Overflow behavior</title>
107
+
<programlisting role="php">
108
+
<![CDATA[
109
+
<?php
110
+
echo chr(-159), chr(833), PHP_EOL;
111
+
?>
112
+
]]>
113
+
</programlisting>
114
+
&example.outputs;
115
+
<screen>
116
+
<![CDATA[
117
+
aA
118
+
]]>
119
+
</screen>
120
+
</example>
121
+
</para>
122
+
<para>
123
+
<example>
124
+
<title>Building a UTF-8 string from individual bytes</title>
125
+
<programlisting role="php">
126
+
<![CDATA[
127
+
<?php
128
+
$str = chr(240) . chr(159) . chr(144) . chr(152);
129
+
echo $str;
130
+
?>
131
+
]]>
132
+
</programlisting>
133
+
&example.outputs;
134
+
<screen>
135
+
🐘
136
+
</screen>
137
+
</example>
89
138
</para>
90
139
</refsect1>
91
140
...
...
@@ -96,12 +145,13 @@ $str = sprintf("The string ends in escape: %c", 27);
96
145
<member><function>sprintf</function> with a format string of <literal>%c</literal></member>
97
146
<member><function>ord</function></member>
98
147
<member>An <link xlink:href="&url.asciitable;">ASCII-table</link></member>
148
+
<member><function>mb_chr</function></member>
149
+
<member><function>IntlChar::chr</function></member>
99
150
</simplelist>
100
151
</para>
101
152
</refsect1>
102
153
103
154
</refentry>
104
-
105
155
<!-- Keep this comment at the end of the file
106
156
Local variables:
107
157
mode: sgml
108
158