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