This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
c69dedf71bc6881214c91427142666cd91dcb33d
[perl5.git] / pod / perluniintro.pod
1 =head1 NAME
2
3 perluniintro - Perl Unicode introduction
4
5 =head1 DESCRIPTION
6
7 This document gives a general idea of Unicode and how to use Unicode
8 in Perl.  See L</Further Resources> for references to more in-depth
9 treatments of Unicode.
10
11 =head2 Unicode
12
13 Unicode is a character set standard which plans to codify all of the
14 writing systems of the world, plus many other symbols.
15
16 Unicode and ISO/IEC 10646 are coordinated standards that unify
17 almost all other modern character set standards,
18 covering more than 80 writing systems and hundreds of languages,
19 including all commercially-important modern languages.  All characters
20 in the largest Chinese, Japanese, and Korean dictionaries are also
21 encoded. The standards will eventually cover almost all characters in
22 more than 250 writing systems and thousands of languages.
23 Unicode 1.0 was released in October 1991, and 6.0 in October 2010.
24
25 A Unicode I<character> is an abstract entity.  It is not bound to any
26 particular integer width, especially not to the C language C<char>.
27 Unicode is language-neutral and display-neutral: it does not encode the
28 language of the text, and it does not generally define fonts or other graphical
29 layout details.  Unicode operates on characters and on text built from
30 those characters.
31
32 Unicode defines characters like C<LATIN CAPITAL LETTER A> or C<GREEK
33 SMALL LETTER ALPHA> and unique numbers for the characters, in this
34 case 0x0041 and 0x03B1, respectively.  These unique numbers are called
35 I<code points>.  A code point is essentially the position of the
36 character within the set of all possible Unicode characters, and thus in
37 Perl, the term I<ordinal> is often used interchangeably with it.
38
39 The Unicode standard prefers using hexadecimal notation for the code
40 points.  If numbers like C<0x0041> are unfamiliar to you, take a peek
41 at a later section, L</"Hexadecimal Notation">.  The Unicode standard
42 uses the notation C<U+0041 LATIN CAPITAL LETTER A>, to give the
43 hexadecimal code point and the normative name of the character.
44
45 Unicode also defines various I<properties> for the characters, like
46 "uppercase" or "lowercase", "decimal digit", or "punctuation";
47 these properties are independent of the names of the characters.
48 Furthermore, various operations on the characters like uppercasing,
49 lowercasing, and collating (sorting) are defined.
50
51 A Unicode I<logical> "character" can actually consist of more than one internal
52 I<actual> "character" or code point.  For Western languages, this is adequately
53 modelled by a I<base character> (like C<LATIN CAPITAL LETTER A>) followed
54 by one or more I<modifiers> (like C<COMBINING ACUTE ACCENT>).  This sequence of
55 base character and modifiers is called a I<combining character
56 sequence>.  Some non-western languages require more complicated
57 models, so Unicode created the I<grapheme cluster> concept, which was
58 later further refined into the I<extended grapheme cluster>.  For
59 example, a Korean Hangul syllable is considered a single logical
60 character, but most often consists of three actual
61 Unicode characters: a leading consonant followed by an interior vowel followed
62 by a trailing consonant.
63
64 Whether to call these extended grapheme clusters "characters" depends on your
65 point of view. If you are a programmer, you probably would tend towards seeing
66 each element in the sequences as one unit, or "character".  However from
67 the user's point of view, the whole sequence could be seen as one
68 "character" since that's probably what it looks like in the context of the
69 user's language.  In this document, we take the programmer's point of
70 view: one "character" is one Unicode code point.
71
72 For some combinations of base character and modifiers, there are
73 I<precomposed> characters.  There is a single character equivalent, for
74 example, to the sequence C<LATIN CAPITAL LETTER A> followed by
75 C<COMBINING ACUTE ACCENT>.  It is called  C<LATIN CAPITAL LETTER A WITH
76 ACUTE>.  These precomposed characters are, however, only available for
77 some combinations, and are mainly meant to support round-trip
78 conversions between Unicode and legacy standards (like ISO 8859).  Using
79 sequences, as Unicode does, allows for needing fewer basic building blocks
80 (code points) to express many more potential grapheme clusters.  To
81 support conversion between equivalent forms, various I<normalization
82 forms> are also defined.  Thus, C<LATIN CAPITAL LETTER A WITH ACUTE> is
83 in I<Normalization Form Composed>, (abbreviated NFC), and the sequence
84 C<LATIN CAPITAL LETTER A> followed by C<COMBINING ACUTE ACCENT>
85 represents the same character in I<Normalization Form Decomposed> (NFD).
86
87 Because of backward compatibility with legacy encodings, the "a unique
88 number for every character" idea breaks down a bit: instead, there is
89 "at least one number for every character".  The same character could
90 be represented differently in several legacy encodings.  The
91 converse is not also true: some code points do not have an assigned
92 character.  Firstly, there are unallocated code points within
93 otherwise used blocks.  Secondly, there are special Unicode control
94 characters that do not represent true characters.
95
96 When Unicode was first conceived, it was thought that all the world's
97 characters could be represented using a 16-bit word; that is a maximum of
98 C<0x10000> (or 65536) characters from C<0x0000> to C<0xFFFF> would be
99 needed.  This soon proved to be false, and since Unicode 2.0 (July
100 1996), Unicode has been defined all the way up to 21 bits (C<0x10FFFF>),
101 and Unicode 3.1 (March 2001) defined the first characters above C<0xFFFF>.
102 The first C<0x10000> characters are called the I<Plane 0>, or the
103 I<Basic Multilingual Plane> (BMP).  With Unicode 3.1, 17 (yes,
104 seventeen) planes in all were defined--but they are nowhere near full of
105 defined characters, yet.
106
107 When a new language is being encoded, Unicode generally will choose a
108 C<block> of consecutive unallocated code points for its characters.  So
109 far, the number of code points in these blocks has always been evenly
110 divisible by 16.  Extras in a block, not currently needed, are left
111 unallocated, for future growth.  But there have been occasions when
112 a later relase needed more code points than available extras, and a new
113 block had to allocated somewhere else, not contiguous to the initial one
114 to handle the overflow.  Thus, it became apparent early on that "block"
115 wasn't an adequate organizing principal, and so the C<script> property
116 was created.  Those code points that are in overflow blocks can still
117 have the same script as the original ones.  The script concept fits more
118 closely with natural language: there is C<Latin> script, C<Greek>
119 script, and so on; and there are several artificial scripts, like
120 C<Common> for characters that are used in multiple scripts, such as
121 mathematical symbols.  Scripts usually span varied parts of several
122 blocks.  For more information about scripts, see L<perlunicode/Scripts>.
123 The division into blocks exists, but it is almost completely
124 accidental--an artifact of how the characters have been and still are
125 allocated.  (Note that this paragraph has oversimplified things for the
126 sake of this being an introduction.  Unicode doesn't really encode
127 languages, but the writing systems for them--their scripts; and one
128 script can be used by many languages.  Unicode also encodes things that
129 aren't really about languages, such as symbols like C<BAGGAGE CLAIM>.)
130
131 The Unicode code points are just abstract numbers.  To input and
132 output these abstract numbers, the numbers must be I<encoded> or
133 I<serialised> somehow.  Unicode defines several I<character encoding
134 forms>, of which I<UTF-8> is perhaps the most popular.  UTF-8 is a
135 variable length encoding that encodes Unicode characters as 1 to 6
136 bytes.  Other encodings
137 include UTF-16 and UTF-32 and their big- and little-endian variants
138 (UTF-8 is byte-order independent) The ISO/IEC 10646 defines the UCS-2
139 and UCS-4 encoding forms.
140
141 For more information about encodings--for instance, to learn what
142 I<surrogates> and I<byte order marks> (BOMs) are--see L<perlunicode>.
143
144 =head2 Perl's Unicode Support
145
146 Starting from Perl 5.6.0, Perl has had the capacity to handle Unicode
147 natively.  Perl 5.8.0, however, is the first recommended release for
148 serious Unicode work.  The maintenance release 5.6.1 fixed many of the
149 problems of the initial Unicode implementation, but for example
150 regular expressions still do not work with Unicode in 5.6.1.
151 Perl 5.14.0 is the first release where Unicode support is
152 (almost) seamlessly integrable without some gotchas (the exception being
153 some differences in L<quotemeta|perlfunc/quotemeta>).   To enable this
154 seamless support, you should C<use feature 'unicode_strings'> (which is
155 automatically selected if you C<use 5.012> or higher).  See L<feature>.
156 (5.14 also fixes a number of bugs and departures from the Unicode
157 standard.)
158
159 Before Perl 5.8.0, the use of C<use utf8> was used to declare
160 that operations in the current block or file would be Unicode-aware.
161 This model was found to be wrong, or at least clumsy: the "Unicodeness"
162 is now carried with the data, instead of being attached to the
163 operations.
164 Starting with Perl 5.8.0, only one case remains where an explicit C<use
165 utf8> is needed: if your Perl script itself is encoded in UTF-8, you can
166 use UTF-8 in your identifier names, and in string and regular expression
167 literals, by saying C<use utf8>.  This is not the default because
168 scripts with legacy 8-bit data in them would break.  See L<utf8>.
169
170 =head2 Perl's Unicode Model
171
172 Perl supports both pre-5.6 strings of eight-bit native bytes, and
173 strings of Unicode characters.  The general principle is that Perl tries
174 to keep its data as eight-bit bytes for as long as possible, but as soon
175 as Unicodeness cannot be avoided, the data is transparently upgraded
176 to Unicode.  Prior to Perl 5.14, the upgrade was not completely
177 transparent (see L<perlunicode/The "Unicode Bug">), and for backwards
178 compatibility, full transparency is not gained unless C<use feature
179 'unicode_strings'> (see L<feature>) or C<use 5.012> (or higher) is
180 selected.
181
182 Internally, Perl currently uses either whatever the native eight-bit
183 character set of the platform (for example Latin-1) is, defaulting to
184 UTF-8, to encode Unicode strings. Specifically, if all code points in
185 the string are C<0xFF> or less, Perl uses the native eight-bit
186 character set.  Otherwise, it uses UTF-8.
187
188 A user of Perl does not normally need to know nor care how Perl
189 happens to encode its internal strings, but it becomes relevant when
190 outputting Unicode strings to a stream without a PerlIO layer (one with
191 the "default" encoding).  In such a case, the raw bytes used internally
192 (the native character set or UTF-8, as appropriate for each string)
193 will be used, and a "Wide character" warning will be issued if those
194 strings contain a character beyond 0x00FF.
195
196 For example,
197
198       perl -e 'print "\x{DF}\n", "\x{0100}\x{DF}\n"'
199
200 produces a fairly useless mixture of native bytes and UTF-8, as well
201 as a warning:
202
203      Wide character in print at ...
204
205 To output UTF-8, use the C<:encoding> or C<:utf8> output layer.  Prepending
206
207       binmode(STDOUT, ":utf8");
208
209 to this sample program ensures that the output is completely UTF-8,
210 and removes the program's warning.
211
212 You can enable automatic UTF-8-ification of your standard file
213 handles, default C<open()> layer, and C<@ARGV> by using either
214 the C<-C> command line switch or the C<PERL_UNICODE> environment
215 variable, see L<perlrun> for the documentation of the C<-C> switch.
216
217 Note that this means that Perl expects other software to work the same
218 way:
219 if Perl has been led to believe that STDIN should be UTF-8, but then
220 STDIN coming in from another command is not UTF-8, Perl will likely
221 complain about the malformed UTF-8.
222
223 All features that combine Unicode and I/O also require using the new
224 PerlIO feature.  Almost all Perl 5.8 platforms do use PerlIO, though:
225 you can see whether yours is by running "perl -V" and looking for
226 C<useperlio=define>.
227
228 =head2 Unicode and EBCDIC
229
230 Perl 5.8.0 also supports Unicode on EBCDIC platforms.  There,
231 Unicode support is somewhat more complex to implement since
232 additional conversions are needed at every step.
233
234 Later Perl releases have added code that will not work on EBCDIC platforms, and
235 no one has complained, so the divergence has continued.  If you want to run
236 Perl on an EBCDIC platform, send email to perlbug@perl.org
237
238 On EBCDIC platforms, the internal Unicode encoding form is UTF-EBCDIC
239 instead of UTF-8.  The difference is that as UTF-8 is "ASCII-safe" in
240 that ASCII characters encode to UTF-8 as-is, while UTF-EBCDIC is
241 "EBCDIC-safe".
242
243 =head2 Creating Unicode
244
245 To create Unicode characters in literals for code points above C<0xFF>,
246 use the C<\x{...}> notation in double-quoted strings:
247
248     my $smiley = "\x{263a}";
249
250 Similarly, it can be used in regular expression literals
251
252     $smiley =~ /\x{263a}/;
253
254 At run-time you can use C<chr()>:
255
256     my $hebrew_alef = chr(0x05d0);
257
258 See L</"Further Resources"> for how to find all these numeric codes.
259
260 Naturally, C<ord()> will do the reverse: it turns a character into
261 a code point.
262
263 Note that C<\x..> (no C<{}> and only two hexadecimal digits), C<\x{...}>,
264 and C<chr(...)> for arguments less than C<0x100> (decimal 256)
265 generate an eight-bit character for backward compatibility with older
266 Perls.  For arguments of C<0x100> or more, Unicode characters are
267 always produced. If you want to force the production of Unicode
268 characters regardless of the numeric value, use C<pack("U", ...)>
269 instead of C<\x..>, C<\x{...}>, or C<chr()>.
270
271 You can also use the C<charnames> pragma to invoke characters
272 by name in double-quoted strings:
273
274     use charnames ':full';
275     my $arabic_alef = "\N{ARABIC LETTER ALEF}";
276
277 And, as mentioned above, you can also C<pack()> numbers into Unicode
278 characters:
279
280    my $georgian_an  = pack("U", 0x10a0);
281
282 Note that both C<\x{...}> and C<\N{...}> are compile-time string
283 constants: you cannot use variables in them.  if you want similar
284 run-time functionality, use C<chr()> and C<charnames::string_vianame()>.
285
286 If you want to force the result to Unicode characters, use the special
287 C<"U0"> prefix.  It consumes no arguments but causes the following bytes
288 to be interpreted as the UTF-8 encoding of Unicode characters:
289
290    my $chars = pack("U0W*", 0x80, 0x42);
291
292 Likewise, you can stop such UTF-8 interpretation by using the special
293 C<"C0"> prefix.
294
295 =head2 Handling Unicode
296
297 Handling Unicode is for the most part transparent: just use the
298 strings as usual.  Functions like C<index()>, C<length()>, and
299 C<substr()> will work on the Unicode characters; regular expressions
300 will work on the Unicode characters (see L<perlunicode> and L<perlretut>).
301
302 Note that Perl considers grapheme clusters to be separate characters, so for
303 example
304
305     use charnames ':full';
306     print length("\N{LATIN CAPITAL LETTER A}\N{COMBINING ACUTE ACCENT}"), "\n";
307
308 will print 2, not 1.  The only exception is that regular expressions
309 have C<\X> for matching an extended grapheme cluster.  (Thus C<\X> in a
310 regular expression would match the entire sequence of both the example
311 characters.)
312
313 Life is not quite so transparent, however, when working with legacy
314 encodings, I/O, and certain special cases:
315
316 =head2 Legacy Encodings
317
318 When you combine legacy data and Unicode, the legacy data needs
319 to be upgraded to Unicode.  Normally the legacy data is assumed to be
320 ISO 8859-1 (or EBCDIC, if applicable).
321
322 The C<Encode> module knows about many encodings and has interfaces
323 for doing conversions between those encodings:
324
325     use Encode 'decode';
326     $data = decode("iso-8859-3", $data); # convert from legacy to utf-8
327
328 =head2 Unicode I/O
329
330 Normally, writing out Unicode data
331
332     print FH $some_string_with_unicode, "\n";
333
334 produces raw bytes that Perl happens to use to internally encode the
335 Unicode string.  Perl's internal encoding depends on the system as
336 well as what characters happen to be in the string at the time. If
337 any of the characters are at code points C<0x100> or above, you will get
338 a warning.  To ensure that the output is explicitly rendered in the
339 encoding you desire--and to avoid the warning--open the stream with
340 the desired encoding. Some examples:
341
342     open FH, ">:utf8", "file";
343
344     open FH, ">:encoding(ucs2)",      "file";
345     open FH, ">:encoding(UTF-8)",     "file";
346     open FH, ">:encoding(shift_jis)", "file";
347
348 and on already open streams, use C<binmode()>:
349
350     binmode(STDOUT, ":utf8");
351
352     binmode(STDOUT, ":encoding(ucs2)");
353     binmode(STDOUT, ":encoding(UTF-8)");
354     binmode(STDOUT, ":encoding(shift_jis)");
355
356 The matching of encoding names is loose: case does not matter, and
357 many encodings have several aliases.  Note that the C<:utf8> layer
358 must always be specified exactly like that; it is I<not> subject to
359 the loose matching of encoding names. Also note that currently C<:utf8> is unsafe for
360 input, because it accepts the data without validating that it is indeed valid
361 UTF-8; you should instead use C<:encoding(utf-8)> (with or without a
362 hyphen).
363
364 See L<PerlIO> for the C<:utf8> layer, L<PerlIO::encoding> and
365 L<Encode::PerlIO> for the C<:encoding()> layer, and
366 L<Encode::Supported> for many encodings supported by the C<Encode>
367 module.
368
369 Reading in a file that you know happens to be encoded in one of the
370 Unicode or legacy encodings does not magically turn the data into
371 Unicode in Perl's eyes.  To do that, specify the appropriate
372 layer when opening files
373
374     open(my $fh,'<:encoding(utf8)', 'anything');
375     my $line_of_unicode = <$fh>;
376
377     open(my $fh,'<:encoding(Big5)', 'anything');
378     my $line_of_unicode = <$fh>;
379
380 The I/O layers can also be specified more flexibly with
381 the C<open> pragma.  See L<open>, or look at the following example.
382
383     use open ':encoding(utf8)'; # input/output default encoding will be
384                                 # UTF-8
385     open X, ">file";
386     print X chr(0x100), "\n";
387     close X;
388     open Y, "<file";
389     printf "%#x\n", ord(<Y>); # this should print 0x100
390     close Y;
391
392 With the C<open> pragma you can use the C<:locale> layer
393
394     BEGIN { $ENV{LC_ALL} = $ENV{LANG} = 'ru_RU.KOI8-R' }
395     # the :locale will probe the locale environment variables like
396     # LC_ALL
397     use open OUT => ':locale'; # russki parusski
398     open(O, ">koi8");
399     print O chr(0x430); # Unicode CYRILLIC SMALL LETTER A = KOI8-R 0xc1
400     close O;
401     open(I, "<koi8");
402     printf "%#x\n", ord(<I>), "\n"; # this should print 0xc1
403     close I;
404
405 These methods install a transparent filter on the I/O stream that
406 converts data from the specified encoding when it is read in from the
407 stream.  The result is always Unicode.
408
409 The L<open> pragma affects all the C<open()> calls after the pragma by
410 setting default layers.  If you want to affect only certain
411 streams, use explicit layers directly in the C<open()> call.
412
413 You can switch encodings on an already opened stream by using
414 C<binmode()>; see L<perlfunc/binmode>.
415
416 The C<:locale> does not currently (as of Perl 5.8.0) work with
417 C<open()> and C<binmode()>, only with the C<open> pragma.  The
418 C<:utf8> and C<:encoding(...)> methods do work with all of C<open()>,
419 C<binmode()>, and the C<open> pragma.
420
421 Similarly, you may use these I/O layers on output streams to
422 automatically convert Unicode to the specified encoding when it is
423 written to the stream. For example, the following snippet copies the
424 contents of the file "text.jis" (encoded as ISO-2022-JP, aka JIS) to
425 the file "text.utf8", encoded as UTF-8:
426
427     open(my $nihongo, '<:encoding(iso-2022-jp)', 'text.jis');
428     open(my $unicode, '>:utf8',                  'text.utf8');
429     while (<$nihongo>) { print $unicode $_ }
430
431 The naming of encodings, both by the C<open()> and by the C<open>
432 pragma allows for flexible names: C<koi8-r> and C<KOI8R> will both be
433 understood.
434
435 Common encodings recognized by ISO, MIME, IANA, and various other
436 standardisation organisations are recognised; for a more detailed
437 list see L<Encode::Supported>.
438
439 C<read()> reads characters and returns the number of characters.
440 C<seek()> and C<tell()> operate on byte counts, as do C<sysread()>
441 and C<sysseek()>.
442
443 Notice that because of the default behaviour of not doing any
444 conversion upon input if there is no default layer,
445 it is easy to mistakenly write code that keeps on expanding a file
446 by repeatedly encoding the data:
447
448     # BAD CODE WARNING
449     open F, "file";
450     local $/; ## read in the whole file of 8-bit characters
451     $t = <F>;
452     close F;
453     open F, ">:encoding(utf8)", "file";
454     print F $t; ## convert to UTF-8 on output
455     close F;
456
457 If you run this code twice, the contents of the F<file> will be twice
458 UTF-8 encoded.  A C<use open ':encoding(utf8)'> would have avoided the
459 bug, or explicitly opening also the F<file> for input as UTF-8.
460
461 B<NOTE>: the C<:utf8> and C<:encoding> features work only if your
462 Perl has been built with the new PerlIO feature (which is the default
463 on most systems).
464
465 =head2 Displaying Unicode As Text
466
467 Sometimes you might want to display Perl scalars containing Unicode as
468 simple ASCII (or EBCDIC) text.  The following subroutine converts
469 its argument so that Unicode characters with code points greater than
470 255 are displayed as C<\x{...}>, control characters (like C<\n>) are
471 displayed as C<\x..>, and the rest of the characters as themselves:
472
473  sub nice_string {
474      join("",
475        map { $_ > 255 ?                  # if wide character...
476               sprintf("\\x{%04X}", $_) :  # \x{...}
477               chr($_) =~ /[[:cntrl:]]/ ?  # else if control character ...
478               sprintf("\\x%02X", $_) :    # \x..
479               quotemeta(chr($_))          # else quoted or as themselves
480          } unpack("W*", $_[0]));           # unpack Unicode characters
481    }
482
483 For example,
484
485    nice_string("foo\x{100}bar\n")
486
487 returns the string
488
489    'foo\x{0100}bar\x0A'
490
491 which is ready to be printed.
492
493 =head2 Special Cases
494
495 =over 4
496
497 =item *
498
499 Bit Complement Operator ~ And vec()
500
501 The bit complement operator C<~> may produce surprising results if
502 used on strings containing characters with ordinal values above
503 255. In such a case, the results are consistent with the internal
504 encoding of the characters, but not with much else. So don't do
505 that. Similarly for C<vec()>: you will be operating on the
506 internally-encoded bit patterns of the Unicode characters, not on
507 the code point values, which is very probably not what you want.
508
509 =item *
510
511 Peeking At Perl's Internal Encoding
512
513 Normal users of Perl should never care how Perl encodes any particular
514 Unicode string (because the normal ways to get at the contents of a
515 string with Unicode--via input and output--should always be via
516 explicitly-defined I/O layers). But if you must, there are two
517 ways of looking behind the scenes.
518
519 One way of peeking inside the internal encoding of Unicode characters
520 is to use C<unpack("C*", ...> to get the bytes of whatever the string
521 encoding happens to be, or C<unpack("U0..", ...)> to get the bytes of the
522 UTF-8 encoding:
523
524     # this prints  c4 80  for the UTF-8 bytes 0xc4 0x80
525     print join(" ", unpack("U0(H2)*", pack("U", 0x100))), "\n";
526
527 Yet another way would be to use the Devel::Peek module:
528
529     perl -MDevel::Peek -e 'Dump(chr(0x100))'
530
531 That shows the C<UTF8> flag in FLAGS and both the UTF-8 bytes
532 and Unicode characters in C<PV>.  See also later in this document
533 the discussion about the C<utf8::is_utf8()> function.
534
535 =back
536
537 =head2 Advanced Topics
538
539 =over 4
540
541 =item *
542
543 String Equivalence
544
545 The question of string equivalence turns somewhat complicated
546 in Unicode: what do you mean by "equal"?
547
548 (Is C<LATIN CAPITAL LETTER A WITH ACUTE> equal to
549 C<LATIN CAPITAL LETTER A>?)
550
551 The short answer is that by default Perl compares equivalence (C<eq>,
552 C<ne>) based only on code points of the characters.  In the above
553 case, the answer is no (because 0x00C1 != 0x0041).  But sometimes, any
554 CAPITAL LETTER A's should be considered equal, or even A's of any case.
555
556 The long answer is that you need to consider character normalization
557 and casing issues: see L<Unicode::Normalize>, Unicode Technical Report #15,
558 L<Unicode Normalization Forms|http://www.unicode.org/unicode/reports/tr15> and
559 sections on case mapping in the L<Unicode Standard|http://www.unicode.org>.
560
561 As of Perl 5.8.0, the "Full" case-folding of I<Case
562 Mappings/SpecialCasing> is implemented, but bugs remain in C<qr//i> with them,
563 mostly fixed by 5.14.
564
565 =item *
566
567 String Collation
568
569 People like to see their strings nicely sorted--or as Unicode
570 parlance goes, collated.  But again, what do you mean by collate?
571
572 (Does C<LATIN CAPITAL LETTER A WITH ACUTE> come before or after
573 C<LATIN CAPITAL LETTER A WITH GRAVE>?)
574
575 The short answer is that by default, Perl compares strings (C<lt>,
576 C<le>, C<cmp>, C<ge>, C<gt>) based only on the code points of the
577 characters.  In the above case, the answer is "after", since
578 C<0x00C1> > C<0x00C0>.
579
580 The long answer is that "it depends", and a good answer cannot be
581 given without knowing (at the very least) the language context.
582 See L<Unicode::Collate>, and I<Unicode Collation Algorithm>
583 L<http://www.unicode.org/unicode/reports/tr10/>
584
585 =back
586
587 =head2 Miscellaneous
588
589 =over 4
590
591 =item *
592
593 Character Ranges and Classes
594
595 Character ranges in regular expression bracketed character classes ( e.g.,
596 C</[a-z]/>) and in the C<tr///> (also known as C<y///>) operator are not
597 magically Unicode-aware.  What this means is that C<[A-Za-z]> will not
598 magically start to mean "all alphabetic letters" (not that it does mean that
599 even for 8-bit characters; for those, if you are using locales (L<perllocale>),
600 use C</[[:alpha:]]/>; and if not, use the 8-bit-aware property C<\p{alpha}>).
601
602 All the properties that begin with C<\p> (and its inverse C<\P>) are actually
603 character classes that are Unicode-aware.  There are dozens of them, see
604 L<perluniprops>.
605
606 You can use Unicode code points as the end points of character ranges, and the
607 range will include all Unicode code points that lie between those end points.
608
609 =item *
610
611 String-To-Number Conversions
612
613 Unicode does define several other decimal--and numeric--characters
614 besides the familiar 0 to 9, such as the Arabic and Indic digits.
615 Perl does not support string-to-number conversion for digits other
616 than ASCII 0 to 9 (and ASCII a to f for hexadecimal).
617 To get safe conversions from any Unicode string, use
618 L<Unicode::UCDE<sol>num()|Unicode::UCD/num>.
619
620 =back
621
622 =head2 Questions With Answers
623
624 =over 4
625
626 =item *
627
628 Will My Old Scripts Break?
629
630 Very probably not.  Unless you are generating Unicode characters
631 somehow, old behaviour should be preserved.  About the only behaviour
632 that has changed and which could start generating Unicode is the old
633 behaviour of C<chr()> where supplying an argument more than 255
634 produced a character modulo 255.  C<chr(300)>, for example, was equal
635 to C<chr(45)> or "-" (in ASCII), now it is LATIN CAPITAL LETTER I WITH
636 BREVE.
637
638 =item *
639
640 How Do I Make My Scripts Work With Unicode?
641
642 Very little work should be needed since nothing changes until you
643 generate Unicode data.  The most important thing is getting input as
644 Unicode; for that, see the earlier I/O discussion.
645 To get full seamless Unicode support, add
646 C<use feature 'unicode_strings'> (or C<use 5.012> or higher) to your
647 script.
648
649 =item *
650
651 How Do I Know Whether My String Is In Unicode?
652
653 You shouldn't have to care.  But you may if your Perl is before 5.14.0
654 or you haven't specified C<use feature 'unicode_strings'> or C<use
655 5.012> (or higher) because otherwise the semantics of the code points
656 in the range 128 to 255 are different depending on
657 whether the string they are contained within is in Unicode or not.
658 (See L<perlunicode/When Unicode Does Not Happen>.)
659
660 To determine if a string is in Unicode, use:
661
662     print utf8::is_utf8($string) ? 1 : 0, "\n";
663
664 But note that this doesn't mean that any of the characters in the
665 string are necessary UTF-8 encoded, or that any of the characters have
666 code points greater than 0xFF (255) or even 0x80 (128), or that the
667 string has any characters at all.  All the C<is_utf8()> does is to
668 return the value of the internal "utf8ness" flag attached to the
669 C<$string>.  If the flag is off, the bytes in the scalar are interpreted
670 as a single byte encoding.  If the flag is on, the bytes in the scalar
671 are interpreted as the (variable-length, potentially multi-byte) UTF-8 encoded
672 code points of the characters.  Bytes added to a UTF-8 encoded string are
673 automatically upgraded to UTF-8.  If mixed non-UTF-8 and UTF-8 scalars
674 are merged (double-quoted interpolation, explicit concatenation, or
675 printf/sprintf parameter substitution), the result will be UTF-8 encoded
676 as if copies of the byte strings were upgraded to UTF-8: for example,
677
678     $a = "ab\x80c";
679     $b = "\x{100}";
680     print "$a = $b\n";
681
682 the output string will be UTF-8-encoded C<ab\x80c = \x{100}\n>, but
683 C<$a> will stay byte-encoded.
684
685 Sometimes you might really need to know the byte length of a string
686 instead of the character length. For that use either the
687 C<Encode::encode_utf8()> function or the C<bytes> pragma
688 and the C<length()> function:
689
690     my $unicode = chr(0x100);
691     print length($unicode), "\n"; # will print 1
692     require Encode;
693     print length(Encode::encode_utf8($unicode)), "\n"; # will print 2
694     use bytes;
695     print length($unicode), "\n"; # will also print 2
696                                   # (the 0xC4 0x80 of the UTF-8)
697     no bytes;
698
699 =item *
700
701 How Do I Find Out What Encoding a File Has?
702
703 You might try L<Encode::Guess>, but it has a number of limitations.
704
705 =item *
706
707 How Do I Detect Data That's Not Valid In a Particular Encoding?
708
709 Use the C<Encode> package to try converting it.
710 For example,
711
712     use Encode 'decode_utf8';
713
714     if (eval { decode_utf8($string, Encode::FB_CROAK); 1 }) {
715         # $string is valid utf8
716     } else {
717         # $string is not valid utf8
718     }
719
720 Or use C<unpack> to try decoding it:
721
722     use warnings;
723     @chars = unpack("C0U*", $string_of_bytes_that_I_think_is_utf8);
724
725 If invalid, a C<Malformed UTF-8 character> warning is produced. The "C0" means
726 "process the string character per character".  Without that, the
727 C<unpack("U*", ...)> would work in C<U0> mode (the default if the format
728 string starts with C<U>) and it would return the bytes making up the UTF-8
729 encoding of the target string, something that will always work.
730
731 =item *
732
733 How Do I Convert Binary Data Into a Particular Encoding, Or Vice Versa?
734
735 This probably isn't as useful as you might think.
736 Normally, you shouldn't need to.
737
738 In one sense, what you are asking doesn't make much sense: encodings
739 are for characters, and binary data are not "characters", so converting
740 "data" into some encoding isn't meaningful unless you know in what
741 character set and encoding the binary data is in, in which case it's
742 not just binary data, now is it?
743
744 If you have a raw sequence of bytes that you know should be
745 interpreted via a particular encoding, you can use C<Encode>:
746
747     use Encode 'from_to';
748     from_to($data, "iso-8859-1", "utf-8"); # from latin-1 to utf-8
749
750 The call to C<from_to()> changes the bytes in C<$data>, but nothing
751 material about the nature of the string has changed as far as Perl is
752 concerned.  Both before and after the call, the string C<$data>
753 contains just a bunch of 8-bit bytes. As far as Perl is concerned,
754 the encoding of the string remains as "system-native 8-bit bytes".
755
756 You might relate this to a fictional 'Translate' module:
757
758    use Translate;
759    my $phrase = "Yes";
760    Translate::from_to($phrase, 'english', 'deutsch');
761    ## phrase now contains "Ja"
762
763 The contents of the string changes, but not the nature of the string.
764 Perl doesn't know any more after the call than before that the
765 contents of the string indicates the affirmative.
766
767 Back to converting data.  If you have (or want) data in your system's
768 native 8-bit encoding (e.g. Latin-1, EBCDIC, etc.), you can use
769 pack/unpack to convert to/from Unicode.
770
771     $native_string  = pack("W*", unpack("U*", $Unicode_string));
772     $Unicode_string = pack("U*", unpack("W*", $native_string));
773
774 If you have a sequence of bytes you B<know> is valid UTF-8,
775 but Perl doesn't know it yet, you can make Perl a believer, too:
776
777     use Encode 'decode_utf8';
778     $Unicode = decode_utf8($bytes);
779
780 or:
781
782     $Unicode = pack("U0a*", $bytes);
783
784 You can find the bytes that make up a UTF-8 sequence with
785
786     @bytes = unpack("C*", $Unicode_string)
787
788 and you can create well-formed Unicode with
789
790     $Unicode_string = pack("U*", 0xff, ...)
791
792 =item *
793
794 How Do I Display Unicode?  How Do I Input Unicode?
795
796 See L<http://www.alanwood.net/unicode/> and
797 L<http://www.cl.cam.ac.uk/~mgk25/unicode.html>
798
799 =item *
800
801 How Does Unicode Work With Traditional Locales?
802
803 Perl tries to keep the two separated.  Code points that are above 255
804 are treated as Unicode; those below 256, generally as locale.  This
805 works reasonably well except in some case-insensitive regular expression
806 pattern matches that in Unicode would cross the 255/256 boundary.  These
807 are disallowed.
808 Also, the C<\p{}> and C<\N{}> constructs silently assume Unicode values
809 even for code points below 256.
810 See also L<perlrun> for the
811 description of the C<-C> switch and its environment counterpart,
812 C<$ENV{PERL_UNICODE}> to see how to enable various Unicode features,
813 for example by using locale settings.
814
815 =back
816
817 =head2 Hexadecimal Notation
818
819 The Unicode standard prefers using hexadecimal notation because
820 that more clearly shows the division of Unicode into blocks of 256 characters.
821 Hexadecimal is also simply shorter than decimal.  You can use decimal
822 notation, too, but learning to use hexadecimal just makes life easier
823 with the Unicode standard.  The C<U+HHHH> notation uses hexadecimal,
824 for example.
825
826 The C<0x> prefix means a hexadecimal number, the digits are 0-9 I<and>
827 a-f (or A-F, case doesn't matter).  Each hexadecimal digit represents
828 four bits, or half a byte.  C<print 0x..., "\n"> will show a
829 hexadecimal number in decimal, and C<printf "%x\n", $decimal> will
830 show a decimal number in hexadecimal.  If you have just the
831 "hex digits" of a hexadecimal number, you can use the C<hex()> function.
832
833     print 0x0009, "\n";    # 9
834     print 0x000a, "\n";    # 10
835     print 0x000f, "\n";    # 15
836     print 0x0010, "\n";    # 16
837     print 0x0011, "\n";    # 17
838     print 0x0100, "\n";    # 256
839
840     print 0x0041, "\n";    # 65
841
842     printf "%x\n",  65;    # 41
843     printf "%#x\n", 65;    # 0x41
844
845     print hex("41"), "\n"; # 65
846
847 =head2 Further Resources
848
849 =over 4
850
851 =item *
852
853 Unicode Consortium
854
855 L<http://www.unicode.org/>
856
857 =item *
858
859 Unicode FAQ
860
861 L<http://www.unicode.org/unicode/faq/>
862
863 =item *
864
865 Unicode Glossary
866
867 L<http://www.unicode.org/glossary/>
868
869 =item *
870
871 Unicode Recommended Reading List
872
873 The Unicode Consortium has a list of articles and books, some of which
874 give a much more in depth treatment of Unicode:
875 L<http://unicode.org/resources/readinglist.html>
876
877 =item *
878
879 Unicode Useful Resources
880
881 L<http://www.unicode.org/unicode/onlinedat/resources.html>
882
883 =item *
884
885 Unicode and Multilingual Support in HTML, Fonts, Web Browsers and Other Applications
886
887 L<http://www.alanwood.net/unicode/>
888
889 =item *
890
891 UTF-8 and Unicode FAQ for Unix/Linux
892
893 L<http://www.cl.cam.ac.uk/~mgk25/unicode.html>
894
895 =item *
896
897 Legacy Character Sets
898
899 L<http://www.czyborra.com/>
900 L<http://www.eki.ee/letter/>
901
902 =item *
903
904 You can explore various information from the Unicode data files using
905 the C<Unicode::UCD> module.
906
907 =back
908
909 =head1 UNICODE IN OLDER PERLS
910
911 If you cannot upgrade your Perl to 5.8.0 or later, you can still
912 do some Unicode processing by using the modules C<Unicode::String>,
913 C<Unicode::Map8>, and C<Unicode::Map>, available from CPAN.
914 If you have the GNU recode installed, you can also use the
915 Perl front-end C<Convert::Recode> for character conversions.
916
917 The following are fast conversions from ISO 8859-1 (Latin-1) bytes
918 to UTF-8 bytes and back, the code works even with older Perl 5 versions.
919
920     # ISO 8859-1 to UTF-8
921     s/([\x80-\xFF])/chr(0xC0|ord($1)>>6).chr(0x80|ord($1)&0x3F)/eg;
922
923     # UTF-8 to ISO 8859-1
924     s/([\xC2\xC3])([\x80-\xBF])/chr(ord($1)<<6&0xC0|ord($2)&0x3F)/eg;
925
926 =head1 SEE ALSO
927
928 L<perlunitut>, L<perlunicode>, L<Encode>, L<open>, L<utf8>, L<bytes>,
929 L<perlretut>, L<perlrun>, L<Unicode::Collate>, L<Unicode::Normalize>,
930 L<Unicode::UCD>
931
932 =head1 ACKNOWLEDGMENTS
933
934 Thanks to the kind readers of the perl5-porters@perl.org,
935 perl-unicode@perl.org, linux-utf8@nl.linux.org, and unicore@unicode.org
936 mailing lists for their valuable feedback.
937
938 =head1 AUTHOR, COPYRIGHT, AND LICENSE
939
940 Copyright 2001-2011 Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>
941
942 This document may be distributed under the same terms as Perl itself.