This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
8edbaace85fd3d47adaefdb7cc4906c9bc318678
[perl5.git] / pod / perlunicode.pod
1 =head1 NAME
2
3 perlunicode - Unicode support in Perl
4
5 =head1 DESCRIPTION
6
7 If you haven't already, before reading this document, you should become
8 familiar with both L<perlunitut> and L<perluniintro>.
9
10 Unicode aims to B<UNI>-fy the en-B<CODE>-ings of all the world's
11 character sets into a single Standard.   For quite a few of the various
12 coding standards that existed when Unicode was first created, converting
13 from each to Unicode essentially meant adding a constant to each code
14 point in the original standard, and converting back meant just
15 subtracting that same constant.  For ASCII and ISO-8859-1, the constant
16 is 0.  For ISO-8859-5, (Cyrillic) the constant is 864; for Hebrew
17 (ISO-8859-8), it's 1488; Thai (ISO-8859-11), 3424; and so forth.  This
18 made it easy to do the conversions, and facilitated the adoption of
19 Unicode.
20
21 And it worked; nowadays, those legacy standards are rarely used.  Most
22 everyone uses Unicode.
23
24 Unicode is a comprehensive standard.  It specifies many things outside
25 the scope of Perl, such as how to display sequences of characters.  For
26 a full discussion of all aspects of Unicode, see
27 L<http://www.unicode.org>.
28
29 =head2 Important Caveats
30
31 Even though some of this section may not be understandable to you on
32 first reading, we think it's important enough to highlight some of the
33 gotchas before delving further, so here goes:
34
35 Unicode support is an extensive requirement. While Perl does not
36 implement the Unicode standard or the accompanying technical reports
37 from cover to cover, Perl does support many Unicode features.
38
39 Also, the use of Unicode may present security issues that aren't obvious.
40 Read L<Unicode Security Considerations|http://www.unicode.org/reports/tr36>.
41
42 =over 4
43
44 =item Safest if you C<use feature 'unicode_strings'>
45
46 In order to preserve backward compatibility, Perl does not turn
47 on full internal Unicode support unless the pragma
48 L<S<C<use feature 'unicode_strings'>>|feature/The 'unicode_strings' feature>
49 is specified.  (This is automatically
50 selected if you S<C<use 5.012>> or higher.)  Failure to do this can
51 trigger unexpected surprises.  See L</The "Unicode Bug"> below.
52
53 This pragma doesn't affect I/O.  Nor does it change the internal
54 representation of strings, only their interpretation.  There are still
55 several places where Unicode isn't fully supported, such as in
56 filenames.
57
58 =item Input and Output Layers
59
60 Use the C<:encoding(...)> layer  to read from and write to
61 filehandles using the specified encoding.  (See L<open>.)
62
63 =item You should convert your non-ASCII, non-UTF-8 Perl scripts to be
64 UTF-8.
65
66 See L<encoding>.
67
68 =item C<use utf8> still needed to enable L<UTF-8|/Unicode Encodings> in scripts
69
70 If your Perl script is itself encoded in L<UTF-8|/Unicode Encodings>,
71 the S<C<use utf8>> pragma must be explicitly included to enable
72 recognition of that (in string or regular expression literals, or in
73 identifier names).  B<This is the only time when an explicit S<C<use
74 utf8>> is needed.>  (See L<utf8>).
75
76 =item C<BOM>-marked scripts and L<UTF-16|/Unicode Encodings> scripts autodetected
77
78 However, if a Perl script begins with the Unicode C<BOM> (UTF-16LE,
79 UTF16-BE, or UTF-8), or if the script looks like non-C<BOM>-marked
80 UTF-16 of either endianness, Perl will correctly read in the script as
81 the appropriate Unicode encoding.  (C<BOM>-less UTF-8 cannot be
82 effectively recognized or differentiated from ISO 8859-1 or other
83 eight-bit encodings.)
84
85 =back
86
87 =head2 Byte and Character Semantics
88
89 Before Unicode, most encodings used 8 bits (a single byte) to encode
90 each character.  Thus a character was a byte, and a byte was a
91 character, and there could be only 256 or fewer possible characters.
92 "Byte Semantics" in the title of this section refers to
93 this behavior.  There was no need to distinguish between "Byte" and
94 "Character".
95
96 Then along comes Unicode which has room for over a million characters
97 (and Perl allows for even more).  This means that a character may
98 require more than a single byte to represent it, and so the two terms
99 are no longer equivalent.  What matter are the characters as whole
100 entities, and not usually the bytes that comprise them.  That's what the
101 term "Character Semantics" in the title of this section refers to.
102
103 Perl had to change internally to decouple "bytes" from "characters".
104 It is important that you too change your ideas, if you haven't already,
105 so that "byte" and "character" no longer mean the same thing in your
106 mind.
107
108 The basic building block of Perl strings has always been a "character".
109 The changes basically come down to that the implementation no longer
110 thinks that a character is always just a single byte.
111
112 There are various things to note:
113
114 =over 4
115
116 =item *
117
118 String handling functions, for the most part, continue to operate in
119 terms of characters.  C<length()>, for example, returns the number of
120 characters in a string, just as before.  But that number no longer is
121 necessarily the same as the number of bytes in the string (there may be
122 more bytes than characters).  The other such functions include
123 C<chop()>, C<chomp()>, C<substr()>, C<pos()>, C<index()>, C<rindex()>,
124 C<sort()>, C<sprintf()>, and C<write()>.
125
126 The exceptions are:
127
128 =over 4
129
130 =item *
131
132 the bit-oriented C<vec>
133
134 E<nbsp>
135
136 =item *
137
138 the byte-oriented C<pack>/C<unpack> C<"C"> format
139
140 However, the C<W> specifier does operate on whole characters, as does the
141 C<U> specifier.
142
143 =item *
144
145 some operators that interact with the platform's operating system
146
147 Operators dealing with filenames are examples.
148
149 =item *
150
151 when the functions are called from within the scope of the
152 S<C<L<use bytes|bytes>>> pragma
153
154 Likely, you should use this only for debugging anyway.
155
156 =back
157
158 =item *
159
160 Strings--including hash keys--and regular expression patterns may
161 contain characters that have ordinal values larger than 255.
162
163 If you use a Unicode editor to edit your program, Unicode characters may
164 occur directly within the literal strings in UTF-8 encoding, or UTF-16.
165 (The former requires a C<BOM> or C<use utf8>, the latter requires a C<BOM>.)
166
167 L<perluniintro/Creating Unicode> gives other ways to place non-ASCII
168 characters in your strings.
169
170 =item *
171
172 The C<chr()> and C<ord()> functions work on whole characters.
173
174 =item *
175
176 Regular expressions match whole characters.  For example, C<"."> matches
177 a whole character instead of only a single byte.
178
179 =item *
180
181 The C<tr///> operator translates whole characters.  (Note that the
182 C<tr///CU> functionality has been removed.  For similar functionality to
183 that, see C<pack('U0', ...)> and C<pack('C0', ...)>).
184
185 =item *
186
187 C<scalar reverse()> reverses by character rather than by byte.
188
189 =item *
190
191 The bit string operators, C<& | ^ ~> and (starting in v5.22)
192 C<&. |. ^.  ~.> can operate on characters that don't fit into a byte.
193 However, the current behavior is likely to change.  You should not use
194 these operators on strings that are encoded in UTF-8.  If you're not
195 sure about the encoding of a string, downgrade it before using any of
196 these operators; you can use
197 L<C<utf8::utf8_downgrade()>|utf8/Utility functions>.
198
199 =back
200
201 The bottom line is that Perl has always practiced "Character Semantics",
202 but with the advent of Unicode, that is now different than "Byte
203 Semantics".
204
205 =head2 ASCII Rules versus Unicode Rules
206
207 Before Unicode, when a character was a byte was a character,
208 Perl knew only about the 128 characters defined by ASCII, code points 0
209 through 127 (except for under S<C<use locale>>).  That left the code
210 points 128 to 255 as unassigned, and available for whatever use a
211 program might want.  The only semantics they have is their ordinal
212 numbers, and that they are members of none of the non-negative character
213 classes.  None are considered to match C<\w> for example, but all match
214 C<\W>.
215
216 Unicode, of course, assigns each of those code points a particular
217 meaning (along with ones above 255).  To preserve backward
218 compatibility, Perl only uses the Unicode meanings when there is some
219 indication that Unicode is what is intended; otherwise the non-ASCII
220 code points remain treated as if they are unassigned.
221
222 Here are the ways that Perl knows that a string should be treated as
223 Unicode:
224
225 =over
226
227 =item *
228
229 Within the scope of S<C<use utf8>>
230
231 If the whole program is Unicode (signified by using 8-bit B<U>nicode
232 B<T>ransformation B<F>ormat), then all strings within it must be
233 Unicode.
234
235 =item *
236
237 Within the scope of
238 L<S<C<use feature 'unicode_strings'>>|feature/The 'unicode_strings' feature>
239
240 This pragma was created so you can explicitly tell Perl that operations
241 executed within its scope are to use Unicode rules.  More operations are
242 affected with newer perls.  See L</The "Unicode Bug">.
243
244 =item *
245
246 Within the scope of S<C<use 5.012>> or higher
247
248 This implicitly turns on S<C<use feature 'unicode_strings'>>.
249
250 =item *
251
252 Within the scope of
253 L<S<C<use locale 'not_characters'>>|perllocale/Unicode and UTF-8>,
254 or L<S<C<use locale>>|perllocale> and the current
255 locale is a UTF-8 locale.
256
257 The former is defined to imply Unicode handling; and the latter
258 indicates a Unicode locale, hence a Unicode interpretation of all
259 strings within it.
260
261 =item *
262
263 When the string contains a Unicode-only code point
264
265 Perl has never accepted code points above 255 without them being
266 Unicode, so their use implies Unicode for the whole string.
267
268 =item *
269
270 When the string contains a Unicode named code point C<\N{...}>
271
272 The C<\N{...}> construct explicitly refers to a Unicode code point,
273 even if it is one that is also in ASCII.  Therefore the string
274 containing it must be Unicode.
275
276 =item *
277
278 When the string has come from an external source marked as
279 Unicode
280
281 The L<C<-C>|perlrun/-C [numberE<sol>list]> command line option can
282 specify that certain inputs to the program are Unicode, and the values
283 of this can be read by your Perl code, see L<perlvar/"${^UNICODE}">.
284
285 =item * When the string has been upgraded to UTF-8
286
287 The function L<C<utf8::utf8_upgrade()>|utf8/Utility functions>
288 can be explicitly used to permanently (unless a subsequent
289 C<utf8::utf8_downgrade()> is called) cause a string to be treated as
290 Unicode.
291
292 =item * There are additional methods for regular expression patterns
293
294 A pattern that is compiled with the L<C<E<sol>u>|perlre/E<sol>u> modifier is
295 treated as Unicode.  Under the C</d> modifier, there are several other
296 indications of Unicode; see L<perlre/E<sol>d>.
297
298 =back
299
300 Note that all of the above are overridden within the scope of
301 C<L<use bytes|bytes>>; but you should be using this pragma only for
302 debugging.
303
304 Note also that some interactions with the platform's operating system
305 never use Unicode rules.
306
307 When Unicode rules are in effect:
308
309 =over 4
310
311 =item *
312
313 Case translation operators use the Unicode case translation tables.
314
315 Note that C<uc()>, or C<\U> in interpolated strings, translates to
316 uppercase, while C<ucfirst>, or C<\u> in interpolated strings,
317 translates to titlecase in languages that make the distinction (which is
318 equivalent to uppercase in languages without the distinction).
319
320 There is a CPAN module, C<L<Unicode::Casing>>, which allows you to
321 define your own mappings to be used in C<lc()>, C<lcfirst()>, C<uc()>,
322 C<ucfirst()>, and C<fc> (or their double-quoted string inlined versions
323 such as C<\U>).  (Prior to Perl 5.16, this functionality was partially
324 provided in the Perl core, but suffered from a number of insurmountable
325 drawbacks, so the CPAN module was written instead.)
326
327 =item *
328
329 Character classes in regular expressions match based on the character
330 properties specified in the Unicode properties database.
331
332 C<\w> can be used to match a Japanese ideograph, for instance; and
333 C<[[:digit:]]> a Bengali number.
334
335 =item *
336
337 Named Unicode properties, scripts, and block ranges may be used (like
338 bracketed character classes) by using the C<\p{}> "matches property"
339 construct and the C<\P{}> negation, "doesn't match property".
340
341 See L</"Unicode Character Properties"> for more details.
342
343 You can define your own character properties and use them
344 in the regular expression with the C<\p{}> or C<\P{}> construct.
345 See L</"User-Defined Character Properties"> for more details.
346
347 =back
348
349 =head2 Extended Grapheme Clusters (Logical characters)
350
351 Consider a character, say C<H>.  It could appear with various marks around it,
352 such as an acute accent, or a circumflex, or various hooks, circles, arrows,
353 I<etc.>, above, below, to one side or the other, I<etc>.  There are many
354 possibilities among the world's languages.  The number of combinations is
355 astronomical, and if there were a character for each combination, it would
356 soon exhaust Unicode's more than a million possible characters.  So Unicode
357 took a different approach: there is a character for the base C<H>, and a
358 character for each of the possible marks, and these can be variously combined
359 to get a final logical character.  So a logical character--what appears to be a
360 single character--can be a sequence of more than one individual characters.
361 The Unicode standard calls these "extended grapheme clusters" (which
362 is an improved version of the no-longer much used "grapheme cluster");
363 Perl furnishes the C<\X> regular expression construct to match such
364 sequences in their entirety.
365
366 But Unicode's intent is to unify the existing character set standards and
367 practices, and several pre-existing standards have single characters that
368 mean the same thing as some of these combinations, like ISO-8859-1,
369 which has quite a few of them. For example, C<"LATIN CAPITAL LETTER E
370 WITH ACUTE"> was already in this standard when Unicode came along.
371 Unicode therefore added it to its repertoire as that single character.
372 But this character is considered by Unicode to be equivalent to the
373 sequence consisting of the character C<"LATIN CAPITAL LETTER E">
374 followed by the character C<"COMBINING ACUTE ACCENT">.
375
376 C<"LATIN CAPITAL LETTER E WITH ACUTE"> is called a "pre-composed"
377 character, and its equivalence with the "E" and the "COMBINING ACCENT"
378 sequence is called canonical equivalence.  All pre-composed characters
379 are said to have a decomposition (into the equivalent sequence), and the
380 decomposition type is also called canonical.  A string may be comprised
381 as much as possible of precomposed characters, or it may be comprised of
382 entirely decomposed characters.  Unicode calls these respectively,
383 "Normalization Form Composed" (NFC) and "Normalization Form Decomposed".
384 The C<L<Unicode::Normalize>> module contains functions that convert
385 between the two.  A string may also have both composed characters and
386 decomposed characters; this module can be used to make it all one or the
387 other.
388
389 You may be presented with strings in any of these equivalent forms.
390 There is currently nothing in Perl 5 that ignores the differences.  So
391 you'll have to specially hanlde it.  The usual advice is to convert your
392 inputs to C<NFD> before processing further.
393
394 For more detailed information, see L<http://unicode.org/reports/tr15/>.
395
396 =head2 Unicode Character Properties
397
398 (The only time that Perl considers a sequence of individual code
399 points as a single logical character is in the C<\X> construct, already
400 mentioned above.   Therefore "character" in this discussion means a single
401 Unicode code point.)
402
403 Very nearly all Unicode character properties are accessible through
404 regular expressions by using the C<\p{}> "matches property" construct
405 and the C<\P{}> "doesn't match property" for its negation.
406
407 For instance, C<\p{Uppercase}> matches any single character with the Unicode
408 C<"Uppercase"> property, while C<\p{L}> matches any character with a
409 C<General_Category> of C<"L"> (letter) property (see
410 L</General_Category> below).  Brackets are not
411 required for single letter property names, so C<\p{L}> is equivalent to C<\pL>.
412
413 More formally, C<\p{Uppercase}> matches any single character whose Unicode
414 C<Uppercase> property value is C<True>, and C<\P{Uppercase}> matches any character
415 whose C<Uppercase> property value is C<False>, and they could have been written as
416 C<\p{Uppercase=True}> and C<\p{Uppercase=False}>, respectively.
417
418 This formality is needed when properties are not binary; that is, if they can
419 take on more values than just C<True> and C<False>.  For example, the
420 C<Bidi_Class> property (see L</"Bidirectional Character Types"> below),
421 can take on several different
422 values, such as C<Left>, C<Right>, C<Whitespace>, and others.  To match these, one needs
423 to specify both the property name (C<Bidi_Class>), AND the value being
424 matched against
425 (C<Left>, C<Right>, I<etc.>).  This is done, as in the examples above, by having the
426 two components separated by an equal sign (or interchangeably, a colon), like
427 C<\p{Bidi_Class: Left}>.
428
429 All Unicode-defined character properties may be written in these compound forms
430 of C<\p{I<property>=I<value>}> or C<\p{I<property>:I<value>}>, but Perl provides some
431 additional properties that are written only in the single form, as well as
432 single-form short-cuts for all binary properties and certain others described
433 below, in which you may omit the property name and the equals or colon
434 separator.
435
436 Most Unicode character properties have at least two synonyms (or aliases if you
437 prefer): a short one that is easier to type and a longer one that is more
438 descriptive and hence easier to understand.  Thus the C<"L"> and
439 C<"Letter"> properties above are equivalent and can be used
440 interchangeably.  Likewise, C<"Upper"> is a synonym for C<"Uppercase">,
441 and we could have written C<\p{Uppercase}> equivalently as C<\p{Upper}>.
442 Also, there are typically various synonyms for the values the property
443 can be.   For binary properties, C<"True"> has 3 synonyms: C<"T">,
444 C<"Yes">, and C<"Y">; and C<"False"> has correspondingly C<"F">,
445 C<"No">, and C<"N">.  But be careful.  A short form of a value for one
446 property may not mean the same thing as the same short form for another.
447 Thus, for the C<L</General_Category>> property, C<"L"> means
448 C<"Letter">, but for the L<C<Bidi_Class>|/Bidirectional Character Types>
449 property, C<"L"> means C<"Left">.  A complete list of properties and
450 synonyms is in L<perluniprops>.
451
452 Upper/lower case differences in property names and values are irrelevant;
453 thus C<\p{Upper}> means the same thing as C<\p{upper}> or even C<\p{UpPeR}>.
454 Similarly, you can add or subtract underscores anywhere in the middle of a
455 word, so that these are also equivalent to C<\p{U_p_p_e_r}>.  And white space
456 is irrelevant adjacent to non-word characters, such as the braces and the equals
457 or colon separators, so C<\p{   Upper  }> and C<\p{ Upper_case : Y }> are
458 equivalent to these as well.  In fact, white space and even
459 hyphens can usually be added or deleted anywhere.  So even C<\p{ Up-per case = Yes}> is
460 equivalent.  All this is called "loose-matching" by Unicode.  The few places
461 where stricter matching is used is in the middle of numbers, and in the Perl
462 extension properties that begin or end with an underscore.  Stricter matching
463 cares about white space (except adjacent to non-word characters),
464 hyphens, and non-interior underscores.
465
466 You can also use negation in both C<\p{}> and C<\P{}> by introducing a caret
467 (C<^>) between the first brace and the property name: C<\p{^Tamil}> is
468 equal to C<\P{Tamil}>.
469
470 Almost all properties are immune to case-insensitive matching.  That is,
471 adding a C</i> regular expression modifier does not change what they
472 match.  There are two sets that are affected.
473 The first set is
474 C<Uppercase_Letter>,
475 C<Lowercase_Letter>,
476 and C<Titlecase_Letter>,
477 all of which match C<Cased_Letter> under C</i> matching.
478 And the second set is
479 C<Uppercase>,
480 C<Lowercase>,
481 and C<Titlecase>,
482 all of which match C<Cased> under C</i> matching.
483 This set also includes its subsets C<PosixUpper> and C<PosixLower> both
484 of which under C</i> match C<PosixAlpha>.
485 (The difference between these sets is that some things, such as Roman
486 numerals, come in both upper and lower case so they are C<Cased>, but
487 aren't considered letters, so they aren't C<Cased_Letter>'s.)
488
489 See L</Beyond Unicode code points> for special considerations when
490 matching Unicode properties against non-Unicode code points.
491
492 =head3 B<General_Category>
493
494 Every Unicode character is assigned a general category, which is the "most
495 usual categorization of a character" (from
496 L<http://www.unicode.org/reports/tr44>).
497
498 The compound way of writing these is like C<\p{General_Category=Number}>
499 (short: C<\p{gc:n}>).  But Perl furnishes shortcuts in which everything up
500 through the equal or colon separator is omitted.  So you can instead just write
501 C<\pN>.
502
503 Here are the short and long forms of the values the C<General Category> property
504 can have:
505
506     Short       Long
507
508     L           Letter
509     LC, L&      Cased_Letter (that is: [\p{Ll}\p{Lu}\p{Lt}])
510     Lu          Uppercase_Letter
511     Ll          Lowercase_Letter
512     Lt          Titlecase_Letter
513     Lm          Modifier_Letter
514     Lo          Other_Letter
515
516     M           Mark
517     Mn          Nonspacing_Mark
518     Mc          Spacing_Mark
519     Me          Enclosing_Mark
520
521     N           Number
522     Nd          Decimal_Number (also Digit)
523     Nl          Letter_Number
524     No          Other_Number
525
526     P           Punctuation (also Punct)
527     Pc          Connector_Punctuation
528     Pd          Dash_Punctuation
529     Ps          Open_Punctuation
530     Pe          Close_Punctuation
531     Pi          Initial_Punctuation
532                 (may behave like Ps or Pe depending on usage)
533     Pf          Final_Punctuation
534                 (may behave like Ps or Pe depending on usage)
535     Po          Other_Punctuation
536
537     S           Symbol
538     Sm          Math_Symbol
539     Sc          Currency_Symbol
540     Sk          Modifier_Symbol
541     So          Other_Symbol
542
543     Z           Separator
544     Zs          Space_Separator
545     Zl          Line_Separator
546     Zp          Paragraph_Separator
547
548     C           Other
549     Cc          Control (also Cntrl)
550     Cf          Format
551     Cs          Surrogate
552     Co          Private_Use
553     Cn          Unassigned
554
555 Single-letter properties match all characters in any of the
556 two-letter sub-properties starting with the same letter.
557 C<LC> and C<L&> are special: both are aliases for the set consisting of everything matched by C<Ll>, C<Lu>, and C<Lt>.
558
559 =head3 B<Bidirectional Character Types>
560
561 Because scripts differ in their directionality (Hebrew and Arabic are
562 written right to left, for example) Unicode supplies a C<Bidi_Class> property.
563 Some of the values this property can have are:
564
565     Value       Meaning
566
567     L           Left-to-Right
568     LRE         Left-to-Right Embedding
569     LRO         Left-to-Right Override
570     R           Right-to-Left
571     AL          Arabic Letter
572     RLE         Right-to-Left Embedding
573     RLO         Right-to-Left Override
574     PDF         Pop Directional Format
575     EN          European Number
576     ES          European Separator
577     ET          European Terminator
578     AN          Arabic Number
579     CS          Common Separator
580     NSM         Non-Spacing Mark
581     BN          Boundary Neutral
582     B           Paragraph Separator
583     S           Segment Separator
584     WS          Whitespace
585     ON          Other Neutrals
586
587 This property is always written in the compound form.
588 For example, C<\p{Bidi_Class:R}> matches characters that are normally
589 written right to left.  Unlike the
590 C<L</General_Category>> property, this
591 property can have more values added in a future Unicode release.  Those
592 listed above comprised the complete set for many Unicode releases, but
593 others were added in Unicode 6.3; you can always find what the
594 current ones are in in L<perluniprops>.  And
595 L<http://www.unicode.org/reports/tr9/> describes how to use them.
596
597 =head3 B<Scripts>
598
599 The world's languages are written in many different scripts.  This sentence
600 (unless you're reading it in translation) is written in Latin, while Russian is
601 written in Cyrillic, and Greek is written in, well, Greek; Japanese mainly in
602 Hiragana or Katakana.  There are many more.
603
604 The Unicode C<Script> and C<Script_Extensions> properties give what script a
605 given character is in.  Either property can be specified with the
606 compound form like
607 C<\p{Script=Hebrew}> (short: C<\p{sc=hebr}>), or
608 C<\p{Script_Extensions=Javanese}> (short: C<\p{scx=java}>).
609 In addition, Perl furnishes shortcuts for all
610 C<Script> property names.  You can omit everything up through the equals
611 (or colon), and simply write C<\p{Latin}> or C<\P{Cyrillic}>.
612 (This is not true for C<Script_Extensions>, which is required to be
613 written in the compound form.)
614
615 The difference between these two properties involves characters that are
616 used in multiple scripts.  For example the digits '0' through '9' are
617 used in many parts of the world.  These are placed in a script named
618 C<Common>.  Other characters are used in just a few scripts.  For
619 example, the C<"KATAKANA-HIRAGANA DOUBLE HYPHEN"> is used in both Japanese
620 scripts, Katakana and Hiragana, but nowhere else.  The C<Script>
621 property places all characters that are used in multiple scripts in the
622 C<Common> script, while the C<Script_Extensions> property places those
623 that are used in only a few scripts into each of those scripts; while
624 still using C<Common> for those used in many scripts.  Thus both these
625 match:
626
627  "0" =~ /\p{sc=Common}/     # Matches
628  "0" =~ /\p{scx=Common}/    # Matches
629
630 and only the first of these match:
631
632  "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{sc=Common}  # Matches
633  "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{scx=Common} # No match
634
635 And only the last two of these match:
636
637  "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{sc=Hiragana}  # No match
638  "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{sc=Katakana}  # No match
639  "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{scx=Hiragana} # Matches
640  "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{scx=Katakana} # Matches
641
642 C<Script_Extensions> is thus an improved C<Script>, in which there are
643 fewer characters in the C<Common> script, and correspondingly more in
644 other scripts.  It is new in Unicode version 6.0, and its data are likely
645 to change significantly in later releases, as things get sorted out.
646 New code should probably be using C<Script_Extensions> and not plain
647 C<Script>.
648
649 (Actually, besides C<Common>, the C<Inherited> script, contains
650 characters that are used in multiple scripts.  These are modifier
651 characters which inherit the script value
652 of the controlling character.  Some of these are used in many scripts,
653 and so go into C<Inherited> in both C<Script> and C<Script_Extensions>.
654 Others are used in just a few scripts, so are in C<Inherited> in
655 C<Script>, but not in C<Script_Extensions>.)
656
657 It is worth stressing that there are several different sets of digits in
658 Unicode that are equivalent to 0-9 and are matchable by C<\d> in a
659 regular expression.  If they are used in a single language only, they
660 are in that language's C<Script> and C<Script_Extension>.  If they are
661 used in more than one script, they will be in C<sc=Common>, but only
662 if they are used in many scripts should they be in C<scx=Common>.
663
664 A complete list of scripts and their shortcuts is in L<perluniprops>.
665
666 =head3 B<Use of the C<"Is"> Prefix>
667
668 For backward compatibility (with Perl 5.6), all properties writable
669 without using the compound form mentioned
670 so far may have C<Is> or C<Is_> prepended to their name, so C<\P{Is_Lu}>, for
671 example, is equal to C<\P{Lu}>, and C<\p{IsScript:Arabic}> is equal to
672 C<\p{Arabic}>.
673
674 =head3 B<Blocks>
675
676 In addition to B<scripts>, Unicode also defines B<blocks> of
677 characters.  The difference between scripts and blocks is that the
678 concept of scripts is closer to natural languages, while the concept
679 of blocks is more of an artificial grouping based on groups of Unicode
680 characters with consecutive ordinal values. For example, the C<"Basic Latin">
681 block is all the characters whose ordinals are between 0 and 127, inclusive; in
682 other words, the ASCII characters.  The C<"Latin"> script contains some letters
683 from this as well as several other blocks, like C<"Latin-1 Supplement">,
684 C<"Latin Extended-A">, I<etc.>, but it does not contain all the characters from
685 those blocks. It does not, for example, contain the digits 0-9, because
686 those digits are shared across many scripts, and hence are in the
687 C<Common> script.
688
689 For more about scripts versus blocks, see UAX#24 "Unicode Script Property":
690 L<http://www.unicode.org/reports/tr24>
691
692 The C<Script> or C<Script_Extensions> properties are likely to be the
693 ones you want to use when processing
694 natural language; the C<Block> property may occasionally be useful in working
695 with the nuts and bolts of Unicode.
696
697 Block names are matched in the compound form, like C<\p{Block: Arrows}> or
698 C<\p{Blk=Hebrew}>.  Unlike most other properties, only a few block names have a
699 Unicode-defined short name.  But Perl does provide a (slight, no longer
700 recommended) shortcut:  You can say, for example C<\p{In_Arrows}> or
701 C<\p{In_Hebrew}>.
702
703 For backwards compatibility, the C<In> prefix may be
704 omitted if there is no naming conflict with a script or any other
705 property, and you can even use an C<Is> prefix instead in those cases.
706 But don't do this for new code because your code could break in new
707 releases, and this has already happened: There was a time in very
708 early Unicode releases when C<\p{Hebrew}> would have matched the
709 I<block> Hebrew; now it doesn't.
710
711 Using the C<In> prefix avoids this ambiguity, so far.  But new versions
712 of Unicode continue to add new properties whose names begin with C<In>.
713 There is a possibility that one of them someday will conflict with your
714 usage.  Since this is just a Perl extension, Unicode's name will take
715 precedence and your code will become broken.  Also, Unicode is free to
716 add a script whose name begins with C<In>; that would cause problems.
717
718 So it's clearer and best to use the compound form when specifying
719 blocks.  And be sure that is what you really really want to do.  In most
720 cases scripts are what you want instead.
721
722 A complete list of blocks and their shortcuts is in L<perluniprops>.
723
724 =head3 B<Other Properties>
725
726 There are many more properties than the very basic ones described here.
727 A complete list is in L<perluniprops>.
728
729 Unicode defines all its properties in the compound form, so all single-form
730 properties are Perl extensions.  Most of these are just synonyms for the
731 Unicode ones, but some are genuine extensions, including several that are in
732 the compound form.  And quite a few of these are actually recommended by Unicode
733 (in L<http://www.unicode.org/reports/tr18>).
734
735 This section gives some details on all extensions that aren't just
736 synonyms for compound-form Unicode properties
737 (for those properties, you'll have to refer to the
738 L<Unicode Standard|http://www.unicode.org/reports/tr44>.
739
740 =over
741
742 =item B<C<\p{All}>>
743
744 This matches every possible code point.  It is equivalent to C<qr/./s>.
745 Unlike all the other non-user-defined C<\p{}> property matches, no
746 warning is ever generated if this is property is matched against a
747 non-Unicode code point (see L</Beyond Unicode code points> below).
748
749 =item B<C<\p{Alnum}>>
750
751 This matches any C<\p{Alphabetic}> or C<\p{Decimal_Number}> character.
752
753 =item B<C<\p{Any}>>
754
755 This matches any of the 1_114_112 Unicode code points.  It is a synonym
756 for C<\p{Unicode}>.
757
758 =item B<C<\p{ASCII}>>
759
760 This matches any of the 128 characters in the US-ASCII character set,
761 which is a subset of Unicode.
762
763 =item B<C<\p{Assigned}>>
764
765 This matches any assigned code point; that is, any code point whose L<general
766 category|/General_Category> is not C<Unassigned> (or equivalently, not C<Cn>).
767
768 =item B<C<\p{Blank}>>
769
770 This is the same as C<\h> and C<\p{HorizSpace}>:  A character that changes the
771 spacing horizontally.
772
773 =item B<C<\p{Decomposition_Type: Non_Canonical}>>    (Short: C<\p{Dt=NonCanon}>)
774
775 Matches a character that has a non-canonical decomposition.
776
777 The L</Extended Grapheme Clusters (Logical characters)> section above
778 talked about canonical decompositions.  However, many more characters
779 have a different type of decomposition, a "compatible" or
780 "non-canonical" decomposition.  The sequences that form these
781 decompositions are not considered canonically equivalent to the
782 pre-composed character.  An example is the C<"SUPERSCRIPT ONE">.  It is
783 somewhat like a regular digit 1, but not exactly; its decomposition into
784 the digit 1 is called a "compatible" decomposition, specifically a
785 "super" decomposition.  There are several such compatibility
786 decompositions (see L<http://www.unicode.org/reports/tr44>), including
787 one called "compat", which means some miscellaneous type of
788 decomposition that doesn't fit into the other decomposition categories
789 that Unicode has chosen.
790
791 Note that most Unicode characters don't have a decomposition, so their
792 decomposition type is C<"None">.
793
794 For your convenience, Perl has added the C<Non_Canonical> decomposition
795 type to mean any of the several compatibility decompositions.
796
797 =item B<C<\p{Graph}>>
798
799 Matches any character that is graphic.  Theoretically, this means a character
800 that on a printer would cause ink to be used.
801
802 =item B<C<\p{HorizSpace}>>
803
804 This is the same as C<\h> and C<\p{Blank}>:  a character that changes the
805 spacing horizontally.
806
807 =item B<C<\p{In=*}>>
808
809 This is a synonym for C<\p{Present_In=*}>
810
811 =item B<C<\p{PerlSpace}>>
812
813 This is the same as C<\s>, restricted to ASCII, namely C<S<[ \f\n\r\t]>>
814 and starting in Perl v5.18, a vertical tab.
815
816 Mnemonic: Perl's (original) space
817
818 =item B<C<\p{PerlWord}>>
819
820 This is the same as C<\w>, restricted to ASCII, namely C<[A-Za-z0-9_]>
821
822 Mnemonic: Perl's (original) word.
823
824 =item B<C<\p{Posix...}>>
825
826 There are several of these, which are equivalents, using the C<\p{}>
827 notation, for Posix classes and are described in
828 L<perlrecharclass/POSIX Character Classes>.
829
830 =item B<C<\p{Present_In: *}>>    (Short: C<\p{In=*}>)
831
832 This property is used when you need to know in what Unicode version(s) a
833 character is.
834
835 The "*" above stands for some two digit Unicode version number, such as
836 C<1.1> or C<4.0>; or the "*" can also be C<Unassigned>.  This property will
837 match the code points whose final disposition has been settled as of the
838 Unicode release given by the version number; C<\p{Present_In: Unassigned}>
839 will match those code points whose meaning has yet to be assigned.
840
841 For example, C<U+0041> C<"LATIN CAPITAL LETTER A"> was present in the very first
842 Unicode release available, which is C<1.1>, so this property is true for all
843 valid "*" versions.  On the other hand, C<U+1EFF> was not assigned until version
844 5.1 when it became C<"LATIN SMALL LETTER Y WITH LOOP">, so the only "*" that
845 would match it are 5.1, 5.2, and later.
846
847 Unicode furnishes the C<Age> property from which this is derived.  The problem
848 with Age is that a strict interpretation of it (which Perl takes) has it
849 matching the precise release a code point's meaning is introduced in.  Thus
850 C<U+0041> would match only 1.1; and C<U+1EFF> only 5.1.  This is not usually what
851 you want.
852
853 Some non-Perl implementations of the Age property may change its meaning to be
854 the same as the Perl C<Present_In> property; just be aware of that.
855
856 Another confusion with both these properties is that the definition is not
857 that the code point has been I<assigned>, but that the meaning of the code point
858 has been I<determined>.  This is because 66 code points will always be
859 unassigned, and so the C<Age> for them is the Unicode version in which the decision
860 to make them so was made.  For example, C<U+FDD0> is to be permanently
861 unassigned to a character, and the decision to do that was made in version 3.1,
862 so C<\p{Age=3.1}> matches this character, as also does C<\p{Present_In: 3.1}> and up.
863
864 =item B<C<\p{Print}>>
865
866 This matches any character that is graphical or blank, except controls.
867
868 =item B<C<\p{SpacePerl}>>
869
870 This is the same as C<\s>, including beyond ASCII.
871
872 Mnemonic: Space, as modified by Perl.  (It doesn't include the vertical tab
873 until v5.18, which both the Posix standard and Unicode consider white space.)
874
875 =item B<C<\p{Title}>> and  B<C<\p{Titlecase}>>
876
877 Under case-sensitive matching, these both match the same code points as
878 C<\p{General Category=Titlecase_Letter}> (C<\p{gc=lt}>).  The difference
879 is that under C</i> caseless matching, these match the same as
880 C<\p{Cased}>, whereas C<\p{gc=lt}> matches C<\p{Cased_Letter>).
881
882 =item B<C<\p{Unicode}>>
883
884 This matches any of the 1_114_112 Unicode code points.
885 C<\p{Any}>.
886
887 =item B<C<\p{VertSpace}>>
888
889 This is the same as C<\v>:  A character that changes the spacing vertically.
890
891 =item B<C<\p{Word}>>
892
893 This is the same as C<\w>, including over 100_000 characters beyond ASCII.
894
895 =item B<C<\p{XPosix...}>>
896
897 There are several of these, which are the standard Posix classes
898 extended to the full Unicode range.  They are described in
899 L<perlrecharclass/POSIX Character Classes>.
900
901 =back
902
903
904 =head2 User-Defined Character Properties
905
906 You can define your own binary character properties by defining subroutines
907 whose names begin with C<"In"> or C<"Is">.  (The experimental feature
908 L<perlre/(?[ ])> provides an alternative which allows more complex
909 definitions.)  The subroutines can be defined in any
910 package.  The user-defined properties can be used in the regular expression
911 C<\p{}> and C<\P{}> constructs; if you are using a user-defined property from a
912 package other than the one you are in, you must specify its package in the
913 C<\p{}> or C<\P{}> construct.
914
915     # assuming property Is_Foreign defined in Lang::
916     package main;  # property package name required
917     if ($txt =~ /\p{Lang::IsForeign}+/) { ... }
918
919     package Lang;  # property package name not required
920     if ($txt =~ /\p{IsForeign}+/) { ... }
921
922
923 Note that the effect is compile-time and immutable once defined.
924 However, the subroutines are passed a single parameter, which is 0 if
925 case-sensitive matching is in effect and non-zero if caseless matching
926 is in effect.  The subroutine may return different values depending on
927 the value of the flag, and one set of values will immutably be in effect
928 for all case-sensitive matches, and the other set for all case-insensitive
929 matches.
930
931 Note that if the regular expression is tainted, then Perl will die rather
932 than calling the subroutine when the name of the subroutine is
933 determined by the tainted data.
934
935 The subroutines must return a specially-formatted string, with one
936 or more newline-separated lines.  Each line must be one of the following:
937
938 =over 4
939
940 =item *
941
942 A single hexadecimal number denoting a code point to include.
943
944 =item *
945
946 Two hexadecimal numbers separated by horizontal whitespace (space or
947 tabular characters) denoting a range of code points to include.
948
949 =item *
950
951 Something to include, prefixed by C<"+">: a built-in character
952 property (prefixed by C<"utf8::">) or a fully qualified (including package
953 name) user-defined character property,
954 to represent all the characters in that property; two hexadecimal code
955 points for a range; or a single hexadecimal code point.
956
957 =item *
958
959 Something to exclude, prefixed by C<"-">: an existing character
960 property (prefixed by C<"utf8::">) or a fully qualified (including package
961 name) user-defined character property,
962 to represent all the characters in that property; two hexadecimal code
963 points for a range; or a single hexadecimal code point.
964
965 =item *
966
967 Something to negate, prefixed C<"!">: an existing character
968 property (prefixed by C<"utf8::">) or a fully qualified (including package
969 name) user-defined character property,
970 to represent all the characters in that property; two hexadecimal code
971 points for a range; or a single hexadecimal code point.
972
973 =item *
974
975 Something to intersect with, prefixed by C<"&">: an existing character
976 property (prefixed by C<"utf8::">) or a fully qualified (including package
977 name) user-defined character property,
978 for all the characters except the characters in the property; two
979 hexadecimal code points for a range; or a single hexadecimal code point.
980
981 =back
982
983 For example, to define a property that covers both the Japanese
984 syllabaries (hiragana and katakana), you can define
985
986     sub InKana {
987         return <<END;
988     3040\t309F
989     30A0\t30FF
990     END
991     }
992
993 Imagine that the here-doc end marker is at the beginning of the line.
994 Now you can use C<\p{InKana}> and C<\P{InKana}>.
995
996 You could also have used the existing block property names:
997
998     sub InKana {
999         return <<'END';
1000     +utf8::InHiragana
1001     +utf8::InKatakana
1002     END
1003     }
1004
1005 Suppose you wanted to match only the allocated characters,
1006 not the raw block ranges: in other words, you want to remove
1007 the unassigned characters:
1008
1009     sub InKana {
1010         return <<'END';
1011     +utf8::InHiragana
1012     +utf8::InKatakana
1013     -utf8::IsCn
1014     END
1015     }
1016
1017 The negation is useful for defining (surprise!) negated classes.
1018
1019     sub InNotKana {
1020         return <<'END';
1021     !utf8::InHiragana
1022     -utf8::InKatakana
1023     +utf8::IsCn
1024     END
1025     }
1026
1027 This will match all non-Unicode code points, since every one of them is
1028 not in Kana.  You can use intersection to exclude these, if desired, as
1029 this modified example shows:
1030
1031     sub InNotKana {
1032         return <<'END';
1033     !utf8::InHiragana
1034     -utf8::InKatakana
1035     +utf8::IsCn
1036     &utf8::Any
1037     END
1038     }
1039
1040 C<&utf8::Any> must be the last line in the definition.
1041
1042 Intersection is used generally for getting the common characters matched
1043 by two (or more) classes.  It's important to remember not to use C<"&"> for
1044 the first set; that would be intersecting with nothing, resulting in an
1045 empty set.
1046
1047 Unlike non-user-defined C<\p{}> property matches, no warning is ever
1048 generated if these properties are matched against a non-Unicode code
1049 point (see L</Beyond Unicode code points> below).
1050
1051 =head2 User-Defined Case Mappings (for serious hackers only)
1052
1053 B<This feature has been removed as of Perl 5.16.>
1054 The CPAN module C<L<Unicode::Casing>> provides better functionality without
1055 the drawbacks that this feature had.  If you are using a Perl earlier
1056 than 5.16, this feature was most fully documented in the 5.14 version of
1057 this pod:
1058 L<http://perldoc.perl.org/5.14.0/perlunicode.html#User-Defined-Case-Mappings-%28for-serious-hackers-only%29>
1059
1060 =head2 Character Encodings for Input and Output
1061
1062 See L<Encode>.
1063
1064 =head2 Unicode Regular Expression Support Level
1065
1066 The following list of Unicode supported features for regular expressions describes
1067 all features currently directly supported by core Perl.  The references to "Level N"
1068 and the section numbers refer to the Unicode Technical Standard #18,
1069 "Unicode Regular Expressions", version 13, from August 2008.
1070
1071 =over 4
1072
1073 =item *
1074
1075 Level 1 - Basic Unicode Support
1076
1077  RL1.1   Hex Notation                     - done          [1]
1078  RL1.2   Properties                       - done          [2][3]
1079  RL1.2a  Compatibility Properties         - done          [4]
1080  RL1.3   Subtraction and Intersection     - experimental  [5]
1081  RL1.4   Simple Word Boundaries           - done          [6]
1082  RL1.5   Simple Loose Matches             - done          [7]
1083  RL1.6   Line Boundaries                  - MISSING       [8][9]
1084  RL1.7   Supplementary Code Points        - done          [10]
1085
1086 =over 4
1087
1088 =item [1] C<\N{U+...}> and C<\x{...}>
1089
1090 =item [2] C<\p{...}> C<\P{...}>
1091
1092 =item [3] supports not only minimal list, but all Unicode character
1093 properties (see Unicode Character Properties above)
1094
1095 =item [4] C<\d> C<\D> C<\s> C<\S> C<\w> C<\W> C<\X> C<[:I<prop>:]>
1096 C<[:^I<prop>:]>
1097
1098 =item [5] The experimental feature starting in v5.18 C<"(?[...])"> accomplishes
1099 this.
1100
1101 See L<perlre/(?[ ])>.  If you don't want to use an experimental
1102 feature, you can use one of the following:
1103
1104 =over 4
1105
1106 =item *
1107
1108 Regular expression look-ahead
1109
1110 You can mimic class subtraction using lookahead.
1111 For example, what UTS#18 might write as
1112
1113     [{Block=Greek}-[{UNASSIGNED}]]
1114
1115 in Perl can be written as:
1116
1117     (?!\p{Unassigned})\p{Block=Greek}
1118     (?=\p{Assigned})\p{Block=Greek}
1119
1120 But in this particular example, you probably really want
1121
1122     \p{Greek}
1123
1124 which will match assigned characters known to be part of the Greek script.
1125
1126 =item *
1127
1128 CPAN module C<L<Unicode::Regex::Set>>
1129
1130 It does implement the full UTS#18 grouping, intersection, union, and
1131 removal (subtraction) syntax.
1132
1133 =item *
1134
1135 L</"User-Defined Character Properties">
1136
1137 C<"+"> for union, C<"-"> for removal (set-difference), C<"&"> for intersection
1138
1139 =back
1140
1141 =item [6] C<\b> C<\B>
1142
1143 =item [7]
1144 Note that Perl does Full case-folding in matching, not Simple:
1145
1146 For example C<U+1F88> is equivalent to C<U+1F00 U+03B9>, instead of just
1147 C<U+1F80>.  This difference matters mainly for certain Greek capital
1148 letters with certain modifiers: the Full case-folding decomposes the
1149 letter, while the Simple case-folding would map it to a single
1150 character.
1151
1152 =item [8]
1153 Perl treats C<\n> as the start- and end-line delimiter.  Unicode
1154 specifies more characters that should be so-interpreted.
1155
1156 These are:
1157
1158  VT   U+000B  (\v in C)
1159  FF   U+000C  (\f)
1160  CR   U+000D  (\r)
1161  NEL  U+0085
1162  LS   U+2028
1163  PS   U+2029
1164
1165 C<^> and C<$> in regular expression patterns are supposed to match all
1166 these, but don't.
1167 These characters also don't, but should, affect C<< <> >> C<$.>, and
1168 script line numbers.
1169
1170 Also, lines should not be split within C<CRLF> (i.e. there is no
1171 empty line between C<\r> and C<\n>).  For C<CRLF>, try the C<:crlf>
1172 layer (see L<PerlIO>).
1173
1174 =item [9] But C<L<Unicode::LineBreak>> is available.
1175
1176 This module supplies line breaking conformant with
1177 L<UAX#14 "Unicode Line Breaking Algorithm"|http://www.unicode.org/reports/tr14>.
1178
1179 =item [10]
1180 UTF-8/UTF-EBDDIC used in Perl allows not only C<U+10000> to
1181 C<U+10FFFF> but also beyond C<U+10FFFF>
1182
1183 =back
1184
1185 =item *
1186
1187 Level 2 - Extended Unicode Support
1188
1189  RL2.1   Canonical Equivalents           - MISSING       [10][11]
1190  RL2.2   Default Grapheme Clusters       - MISSING       [12]
1191  RL2.3   Default Word Boundaries         - DONE          [14]
1192  RL2.4   Default Loose Matches           - MISSING       [15]
1193  RL2.5   Name Properties                 - DONE
1194  RL2.6   Wildcard Properties             - MISSING
1195
1196  [10] see UAX#15 "Unicode Normalization Forms"
1197  [11] have Unicode::Normalize but not integrated to regexes
1198  [12] have \X and \b{gcb} but we don't have a "Grapheme Cluster
1199       Mode"
1200  [14] see UAX#29, Word Boundaries
1201  [15] This is covered in Chapter 3.13 (in Unicode 6.0)
1202
1203 =item *
1204
1205 Level 3 - Tailored Support
1206
1207  RL3.1   Tailored Punctuation            - MISSING
1208  RL3.2   Tailored Grapheme Clusters      - MISSING       [17][18]
1209  RL3.3   Tailored Word Boundaries        - MISSING
1210  RL3.4   Tailored Loose Matches          - MISSING
1211  RL3.5   Tailored Ranges                 - MISSING
1212  RL3.6   Context Matching                - MISSING       [19]
1213  RL3.7   Incremental Matches             - MISSING
1214       ( RL3.8   Unicode Set Sharing )
1215  RL3.9   Possible Match Sets             - MISSING
1216  RL3.10  Folded Matching                 - MISSING       [20]
1217  RL3.11  Submatchers                     - MISSING
1218
1219  [17] see UAX#10 "Unicode Collation Algorithms"
1220  [18] have Unicode::Collate but not integrated to regexes
1221  [19] have (?<=x) and (?=x), but look-aheads or look-behinds
1222       should see outside of the target substring
1223  [20] need insensitive matching for linguistic features other
1224       than case; for example, hiragana to katakana, wide and
1225       narrow, simplified Han to traditional Han (see UTR#30
1226       "Character Foldings")
1227
1228 =back
1229
1230 =head2 Unicode Encodings
1231
1232 Unicode characters are assigned to I<code points>, which are abstract
1233 numbers.  To use these numbers, various encodings are needed.
1234
1235 =over 4
1236
1237 =item *
1238
1239 UTF-8
1240
1241 UTF-8 is a variable-length (1 to 4 bytes), byte-order independent
1242 encoding.  In most of Perl's documentation, including elsewhere in this
1243 document, the term "UTF-8" means also "UTF-EBCDIC".  But in this section,
1244 "UTF-8" refers only to the encoding used on ASCII platforms.  It is a
1245 superset of 7-bit US-ASCII, so anything encoded in ASCII has the
1246 identical representation when encoded in UTF-8.
1247
1248 The following table is from Unicode 3.2.
1249
1250  Code Points            1st Byte  2nd Byte  3rd Byte 4th Byte
1251
1252    U+0000..U+007F       00..7F
1253    U+0080..U+07FF     * C2..DF    80..BF
1254    U+0800..U+0FFF       E0      * A0..BF    80..BF
1255    U+1000..U+CFFF       E1..EC    80..BF    80..BF
1256    U+D000..U+D7FF       ED        80..9F    80..BF
1257    U+D800..U+DFFF       +++++ utf16 surrogates, not legal utf8 +++++
1258    U+E000..U+FFFF       EE..EF    80..BF    80..BF
1259   U+10000..U+3FFFF      F0      * 90..BF    80..BF    80..BF
1260   U+40000..U+FFFFF      F1..F3    80..BF    80..BF    80..BF
1261  U+100000..U+10FFFF     F4        80..8F    80..BF    80..BF
1262
1263 Note the gaps marked by "*" before several of the byte entries above.  These are
1264 caused by legal UTF-8 avoiding non-shortest encodings: it is technically
1265 possible to UTF-8-encode a single code point in different ways, but that is
1266 explicitly forbidden, and the shortest possible encoding should always be used
1267 (and that is what Perl does).
1268
1269 Another way to look at it is via bits:
1270
1271                 Code Points  1st Byte  2nd Byte  3rd Byte  4th Byte
1272
1273                    0aaaaaaa  0aaaaaaa
1274            00000bbbbbaaaaaa  110bbbbb  10aaaaaa
1275            ccccbbbbbbaaaaaa  1110cccc  10bbbbbb  10aaaaaa
1276  00000dddccccccbbbbbbaaaaaa  11110ddd  10cccccc  10bbbbbb  10aaaaaa
1277
1278 As you can see, the continuation bytes all begin with C<"10">, and the
1279 leading bits of the start byte tell how many bytes there are in the
1280 encoded character.
1281
1282 The original UTF-8 specification allowed up to 6 bytes, to allow
1283 encoding of numbers up to C<0x7FFF_FFFF>.  Perl continues to allow those,
1284 and has extended that up to 13 bytes to encode code points up to what
1285 can fit in a 64-bit word.  However, Perl will warn if you output any of
1286 these as being non-portable; and under strict UTF-8 input protocols,
1287 they are forbidden.
1288
1289 =item *
1290
1291 UTF-EBCDIC
1292
1293 Like UTF-8, but EBCDIC-safe, in the way that UTF-8 is ASCII-safe.
1294 This means that all the basic characters (which includes all
1295 those that have ASCII equivalents (like C<"A">, C<"0">, C<"%">, I<etc.>)
1296 are the same in both EBCDIC and UTF-EBCDIC.)
1297
1298 UTF-EBCDIC is used on EBCDIC platforms.  The largest Unicode code points
1299 take 5 bytes to represent (instead of 4 in UTF-8), and Perl extends it
1300 to a maximum of 7 bytes to encode pode points up to what can fit in a
1301 32-bit word (instead of 13 bytes and a 64-bit word in UTF-8).
1302
1303 =item *
1304
1305 UTF-16, UTF-16BE, UTF-16LE, Surrogates, and C<BOM>'s (Byte Order Marks)
1306
1307 The followings items are mostly for reference and general Unicode
1308 knowledge, Perl doesn't use these constructs internally.
1309
1310 Like UTF-8, UTF-16 is a variable-width encoding, but where
1311 UTF-8 uses 8-bit code units, UTF-16 uses 16-bit code units.
1312 All code points occupy either 2 or 4 bytes in UTF-16: code points
1313 C<U+0000..U+FFFF> are stored in a single 16-bit unit, and code
1314 points C<U+10000..U+10FFFF> in two 16-bit units.  The latter case is
1315 using I<surrogates>, the first 16-bit unit being the I<high
1316 surrogate>, and the second being the I<low surrogate>.
1317
1318 Surrogates are code points set aside to encode the C<U+10000..U+10FFFF>
1319 range of Unicode code points in pairs of 16-bit units.  The I<high
1320 surrogates> are the range C<U+D800..U+DBFF> and the I<low surrogates>
1321 are the range C<U+DC00..U+DFFF>.  The surrogate encoding is
1322
1323     $hi = ($uni - 0x10000) / 0x400 + 0xD800;
1324     $lo = ($uni - 0x10000) % 0x400 + 0xDC00;
1325
1326 and the decoding is
1327
1328     $uni = 0x10000 + ($hi - 0xD800) * 0x400 + ($lo - 0xDC00);
1329
1330 Because of the 16-bitness, UTF-16 is byte-order dependent.  UTF-16
1331 itself can be used for in-memory computations, but if storage or
1332 transfer is required either UTF-16BE (big-endian) or UTF-16LE
1333 (little-endian) encodings must be chosen.
1334
1335 This introduces another problem: what if you just know that your data
1336 is UTF-16, but you don't know which endianness?  Byte Order Marks, or
1337 C<BOM>'s, are a solution to this.  A special character has been reserved
1338 in Unicode to function as a byte order marker: the character with the
1339 code point C<U+FEFF> is the C<BOM>.
1340
1341 The trick is that if you read a C<BOM>, you will know the byte order,
1342 since if it was written on a big-endian platform, you will read the
1343 bytes C<0xFE 0xFF>, but if it was written on a little-endian platform,
1344 you will read the bytes C<0xFF 0xFE>.  (And if the originating platform
1345 was writing in ASCII platform UTF-8, you will read the bytes
1346 C<0xEF 0xBB 0xBF>.)
1347
1348 The way this trick works is that the character with the code point
1349 C<U+FFFE> is not supposed to be in input streams, so the
1350 sequence of bytes C<0xFF 0xFE> is unambiguously "C<BOM>, represented in
1351 little-endian format" and cannot be C<U+FFFE>, represented in big-endian
1352 format".
1353
1354 Surrogates have no meaning in Unicode outside their use in pairs to
1355 represent other code points.  However, Perl allows them to be
1356 represented individually internally, for example by saying
1357 C<chr(0xD801)>, so that all code points, not just those valid for open
1358 interchange, are
1359 representable.  Unicode does define semantics for them, such as their
1360 C<L</General_Category>> is C<"Cs">.  But because their use is somewhat dangerous,
1361 Perl will warn (using the warning category C<"surrogate">, which is a
1362 sub-category of C<"utf8">) if an attempt is made
1363 to do things like take the lower case of one, or match
1364 case-insensitively, or to output them.  (But don't try this on Perls
1365 before 5.14.)
1366
1367 =item *
1368
1369 UTF-32, UTF-32BE, UTF-32LE
1370
1371 The UTF-32 family is pretty much like the UTF-16 family, except that
1372 the units are 32-bit, and therefore the surrogate scheme is not
1373 needed.  UTF-32 is a fixed-width encoding.  The C<BOM> signatures are
1374 C<0x00 0x00 0xFE 0xFF> for BE and C<0xFF 0xFE 0x00 0x00> for LE.
1375
1376 =item *
1377
1378 UCS-2, UCS-4
1379
1380 Legacy, fixed-width encodings defined by the ISO 10646 standard.  UCS-2 is a 16-bit
1381 encoding.  Unlike UTF-16, UCS-2 is not extensible beyond C<U+FFFF>,
1382 because it does not use surrogates.  UCS-4 is a 32-bit encoding,
1383 functionally identical to UTF-32 (the difference being that
1384 UCS-4 forbids neither surrogates nor code points larger than C<0x10_FFFF>).
1385
1386 =item *
1387
1388 UTF-7
1389
1390 A seven-bit safe (non-eight-bit) encoding, which is useful if the
1391 transport or storage is not eight-bit safe.  Defined by RFC 2152.
1392
1393 =back
1394
1395 =head2 Noncharacter code points
1396
1397 66 code points are set aside in Unicode as "noncharacter code points".
1398 These all have the C<Unassigned> (C<Cn>) C<L</General_Category>>, and
1399 no character will ever be assigned to any of them.  They are the 32 code
1400 points between C<U+FDD0> and C<U+FDEF> inclusive, and the 34 code
1401 points:
1402
1403  U+FFFE   U+FFFF
1404  U+1FFFE  U+1FFFF
1405  U+2FFFE  U+2FFFF
1406  ...
1407  U+EFFFE  U+EFFFF
1408  U+FFFFE  U+FFFFF
1409  U+10FFFE U+10FFFF
1410
1411 Until Unicode 7.0, the noncharacters were "B<forbidden> for use in open
1412 interchange of Unicode text data", so that code that processed those
1413 streams could use these code points as sentinels that could be mixed in
1414 with character data, and would always be distinguishable from that data.
1415 (Emphasis above and in the next paragraph are added in this document.)
1416
1417 Unicode 7.0 changed the wording so that they are "B<not recommended> for
1418 use in open interchange of Unicode text data".  The 7.0 Standard goes on
1419 to say:
1420
1421 =over 4
1422
1423 "If a noncharacter is received in open interchange, an application is
1424 not required to interpret it in any way.  It is good practice, however,
1425 to recognize it as a noncharacter and to take appropriate action, such
1426 as replacing it with C<U+FFFD> replacement character, to indicate the
1427 problem in the text.  It is not recommended to simply delete
1428 noncharacter code points from such text, because of the potential
1429 security issues caused by deleting uninterpreted characters.  (See
1430 conformance clause C7 in Section 3.2, Conformance Requirements, and
1431 L<Unicode Technical Report #36, "Unicode Security
1432 Considerations"|http://www.unicode.org/reports/tr36/#Substituting_for_Ill_Formed_Subsequences>)."
1433
1434 =back
1435
1436 This change was made because it was found that various commercial tools
1437 like editors, or for things like source code control, had been written
1438 so that they would not handle program files that used these code points,
1439 effectively precluding their use almost entirely!  And that was never
1440 the intent.  They've always been meant to be usable within an
1441 application, or cooperating set of applications, at will.
1442
1443 If you're writing code, such as an editor, that is supposed to be able
1444 to handle any Unicode text data, then you shouldn't be using these code
1445 points yourself, and instead allow them in the input.  If you need
1446 sentinels, they should instead be something that isn't legal Unicode.
1447 For UTF-8 data, you can use the bytes 0xC1 and 0xC2 as sentinels, as
1448 they never appear in well-formed UTF-8.  (There are equivalents for
1449 UTF-EBCDIC).  You can also store your Unicode code points in integer
1450 variables and use negative values as sentinels.
1451
1452 If you're not writing such a tool, then whether you accept noncharacters
1453 as input is up to you (though the Standard recommends that you not).  If
1454 you do strict input stream checking with Perl, these code points
1455 continue to be forbidden.  This is to maintain backward compatibility
1456 (otherwise potential security holes could open up, as an unsuspecting
1457 application that was written assuming the noncharacters would be
1458 filtered out before getting to it, could now, without warning, start
1459 getting them).  To do strict checking, you can use the layer
1460 C<:encoding('UTF-8')>.
1461
1462 Perl continues to warn (using the warning category C<"nonchar">, which
1463 is a sub-category of C<"utf8">) if an attempt is made to output
1464 noncharacters.
1465
1466 =head2 Beyond Unicode code points
1467
1468 The maximum Unicode code point is C<U+10FFFF>, and Unicode only defines
1469 operations on code points up through that.  But Perl works on code
1470 points up to the maximum permissible unsigned number available on the
1471 platform.  However, Perl will not accept these from input streams unless
1472 lax rules are being used, and will warn (using the warning category
1473 C<"non_unicode">, which is a sub-category of C<"utf8">) if any are output.
1474
1475 Since Unicode rules are not defined on these code points, if a
1476 Unicode-defined operation is done on them, Perl uses what we believe are
1477 sensible rules, while generally warning, using the C<"non_unicode">
1478 category.  For example, C<uc("\x{11_0000}")> will generate such a
1479 warning, returning the input parameter as its result, since Perl defines
1480 the uppercase of every non-Unicode code point to be the code point
1481 itself.  (All the case changing operations, not just uppercasing, work
1482 this way.)
1483
1484 The situation with matching Unicode properties in regular expressions,
1485 the C<\p{}> and C<\P{}> constructs, against these code points is not as
1486 clear cut, and how these are handled has changed as we've gained
1487 experience.
1488
1489 One possibility is to treat any match against these code points as
1490 undefined.  But since Perl doesn't have the concept of a match being
1491 undefined, it converts this to failing or C<FALSE>.  This is almost, but
1492 not quite, what Perl did from v5.14 (when use of these code points
1493 became generally reliable) through v5.18.  The difference is that Perl
1494 treated all C<\p{}> matches as failing, but all C<\P{}> matches as
1495 succeeding.
1496
1497 One problem with this is that it leads to unexpected, and confusting
1498 results in some cases:
1499
1500  chr(0x110000) =~ \p{ASCII_Hex_Digit=True}      # Failed on <= v5.18
1501  chr(0x110000) =~ \p{ASCII_Hex_Digit=False}     # Failed! on <= v5.18
1502
1503 That is, it treated both matches as undefined, and converted that to
1504 false (raising a warning on each).  The first case is the expected
1505 result, but the second is likely counterintuitive: "How could both be
1506 false when they are complements?"  Another problem was that the
1507 implementation optimized many Unicode property matches down to already
1508 existing simpler, faster operations, which don't raise the warning.  We
1509 chose to not forgo those optimizations, which help the vast majority of
1510 matches, just to generate a warning for the unlikely event that an
1511 above-Unicode code point is being matched against.
1512
1513 As a result of these problems, starting in v5.20, what Perl does is
1514 to treat non-Unicode code points as just typical unassigned Unicode
1515 characters, and matches accordingly.  (Note: Unicode has atypical
1516 unassigned code points.  For example, it has noncharacter code points,
1517 and ones that, when they do get assigned, are destined to be written
1518 Right-to-left, as Arabic and Hebrew are.  Perl assumes that no
1519 non-Unicode code point has any atypical properties.)
1520
1521 Perl, in most cases, will raise a warning when matching an above-Unicode
1522 code point against a Unicode property when the result is C<TRUE> for
1523 C<\p{}>, and C<FALSE> for C<\P{}>.  For example:
1524
1525  chr(0x110000) =~ \p{ASCII_Hex_Digit=True}      # Fails, no warning
1526  chr(0x110000) =~ \p{ASCII_Hex_Digit=False}     # Succeeds, with warning
1527
1528 In both these examples, the character being matched is non-Unicode, so
1529 Unicode doesn't define how it should match.  It clearly isn't an ASCII
1530 hex digit, so the first example clearly should fail, and so it does,
1531 with no warning.  But it is arguable that the second example should have
1532 an undefined, hence C<FALSE>, result.  So a warning is raised for it.
1533
1534 Thus the warning is raised for many fewer cases than in earlier Perls,
1535 and only when what the result is could be arguable.  It turns out that
1536 none of the optimizations made by Perl (or are ever likely to be made)
1537 cause the warning to be skipped, so it solves both problems of Perl's
1538 earlier approach.  The most commonly used property that is affected by
1539 this change is C<\p{Unassigned}> which is a short form for
1540 C<\p{General_Category=Unassigned}>.  Starting in v5.20, all non-Unicode
1541 code points are considered C<Unassigned>.  In earlier releases the
1542 matches failed because the result was considered undefined.
1543
1544 The only place where the warning is not raised when it might ought to
1545 have been is if optimizations cause the whole pattern match to not even
1546 be attempted.  For example, Perl may figure out that for a string to
1547 match a certain regular expression pattern, the string has to contain
1548 the substring C<"foobar">.  Before attempting the match, Perl may look
1549 for that substring, and if not found, immediately fail the match without
1550 actually trying it; so no warning gets generated even if the string
1551 contains an above-Unicode code point.
1552
1553 This behavior is more "Do what I mean" than in earlier Perls for most
1554 applications.  But it catches fewer issues for code that needs to be
1555 strictly Unicode compliant.  Therefore there is an additional mode of
1556 operation available to accommodate such code.  This mode is enabled if a
1557 regular expression pattern is compiled within the lexical scope where
1558 the C<"non_unicode"> warning class has been made fatal, say by:
1559
1560  use warnings FATAL => "non_unicode"
1561
1562 (see L<warnings>).  In this mode of operation, Perl will raise the
1563 warning for all matches against a non-Unicode code point (not just the
1564 arguable ones), and it skips the optimizations that might cause the
1565 warning to not be output.  (It currently still won't warn if the match
1566 isn't even attempted, like in the C<"foobar"> example above.)
1567
1568 In summary, Perl now normally treats non-Unicode code points as typical
1569 Unicode unassigned code points for regular expression matches, raising a
1570 warning only when it is arguable what the result should be.  However, if
1571 this warning has been made fatal, it isn't skipped.
1572
1573 There is one exception to all this.  C<\p{All}> looks like a Unicode
1574 property, but it is a Perl extension that is defined to be true for all
1575 possible code points, Unicode or not, so no warning is ever generated
1576 when matching this against a non-Unicode code point.  (Prior to v5.20,
1577 it was an exact synonym for C<\p{Any}>, matching code points C<0>
1578 through C<0x10FFFF>.)
1579
1580 =head2 Security Implications of Unicode
1581
1582 First, read
1583 L<Unicode Security Considerations|http://www.unicode.org/reports/tr36>.
1584
1585 Also, note the following:
1586
1587 =over 4
1588
1589 =item *
1590
1591 Malformed UTF-8
1592
1593 Unfortunately, the original specification of UTF-8 leaves some room for
1594 interpretation of how many bytes of encoded output one should generate
1595 from one input Unicode character.  Strictly speaking, the shortest
1596 possible sequence of UTF-8 bytes should be generated,
1597 because otherwise there is potential for an input buffer overflow at
1598 the receiving end of a UTF-8 connection.  Perl always generates the
1599 shortest length UTF-8, and with warnings on, Perl will warn about
1600 non-shortest length UTF-8 along with other malformations, such as the
1601 surrogates, which are not Unicode code points valid for interchange.
1602
1603 =item *
1604
1605 Regular expression pattern matching may surprise you if you're not
1606 accustomed to Unicode.  Starting in Perl 5.14, several pattern
1607 modifiers are available to control this, called the character set
1608 modifiers.  Details are given in L<perlre/Character set modifiers>.
1609
1610 =back
1611
1612 As discussed elsewhere, Perl has one foot (two hooves?) planted in
1613 each of two worlds: the old world of ASCII and single-byte locales, and
1614 the new world of Unicode, upgrading when necessary.
1615 If your legacy code does not explicitly use Unicode, no automatic
1616 switch-over to Unicode should happen.
1617
1618 =head2 Unicode in Perl on EBCDIC
1619
1620 Unicode is supported on EBCDIC platforms.  See L<perlebcdic>.
1621
1622 Unless ASCII vs. EBCDIC issues are specifically being discussed,
1623 references to UTF-8 encoding in this document and elsewhere should be
1624 read as meaning UTF-EBCDIC on EBCDIC platforms.
1625 See L<perlebcdic/Unicode and UTF>.
1626
1627 Because UTF-EBCDIC is so similar to UTF-8, the differences are mostly
1628 hidden from you; S<C<use utf8>> (and NOT something like
1629 S<C<use utfebcdic>>) declares the the script is in the platform's
1630 "native" 8-bit encoding of Unicode.  (Similarly for the C<":utf8">
1631 layer.)
1632
1633 =head2 Locales
1634
1635 See L<perllocale/Unicode and UTF-8>
1636
1637 =head2 When Unicode Does Not Happen
1638
1639 There are still many places where Unicode (in some encoding or
1640 another) could be given as arguments or received as results, or both in
1641 Perl, but it is not, in spite of Perl having extensive ways to input and
1642 output in Unicode, and a few other "entry points" like the C<@ARGV>
1643 array (which can sometimes be interpreted as UTF-8).
1644
1645 The following are such interfaces.  Also, see L</The "Unicode Bug">.
1646 For all of these interfaces Perl
1647 currently (as of v5.16.0) simply assumes byte strings both as arguments
1648 and results, or UTF-8 strings if the (deprecated) C<encoding> pragma has been used.
1649
1650 One reason that Perl does not attempt to resolve the role of Unicode in
1651 these situations is that the answers are highly dependent on the operating
1652 system and the file system(s).  For example, whether filenames can be
1653 in Unicode and in exactly what kind of encoding, is not exactly a
1654 portable concept.  Similarly for C<qx> and C<system>: how well will the
1655 "command-line interface" (and which of them?) handle Unicode?
1656
1657 =over 4
1658
1659 =item *
1660
1661 C<chdir>, C<chmod>, C<chown>, C<chroot>, C<exec>, C<link>, C<lstat>, C<mkdir>,
1662 C<rename>, C<rmdir>, C<stat>, C<symlink>, C<truncate>, C<unlink>, C<utime>, C<-X>
1663
1664 =item *
1665
1666 C<%ENV>
1667
1668 =item *
1669
1670 C<glob> (aka the C<E<lt>*E<gt>>)
1671
1672 =item *
1673
1674 C<open>, C<opendir>, C<sysopen>
1675
1676 =item *
1677
1678 C<qx> (aka the backtick operator), C<system>
1679
1680 =item *
1681
1682 C<readdir>, C<readlink>
1683
1684 =back
1685
1686 =head2 The "Unicode Bug"
1687
1688 The term, "Unicode bug" has been applied to an inconsistency with the
1689 code points in the C<Latin-1 Supplement> block, that is, between
1690 128 and 255.  Without a locale specified, unlike all other characters or
1691 code points, these characters can have very different semantics
1692 depending on the rules in effect.  (Characters whose code points are
1693 above 255 force Unicode rules; whereas the rules for ASCII characters
1694 are the same under both ASCII and Unicode rules.)
1695
1696 Under Unicode rules, these upper-Latin1 characters are interpreted as
1697 Unicode code points, which means they have the same semantics as Latin-1
1698 (ISO-8859-1) and C1 controls.
1699
1700 As explained in L</ASCII Rules versus Unicode Rules>, under ASCII rules,
1701 they are considered to be unassigned characters.
1702
1703 This can lead to unexpected results.  For example, a string's
1704 semantics can suddenly change if a code point above 255 is appended to
1705 it, which changes the rules from ASCII to Unicode.  As an
1706 example, consider the following program and its output:
1707
1708  $ perl -le'
1709      no feature 'unicode_strings';
1710      $s1 = "\xC2";
1711      $s2 = "\x{2660}";
1712      for ($s1, $s2, $s1.$s2) {
1713          print /\w/ || 0;
1714      }
1715  '
1716  0
1717  0
1718  1
1719
1720 If there's no C<\w> in C<s1> nor in C<s2>, why does their concatenation
1721 have one?
1722
1723 This anomaly stems from Perl's attempt to not disturb older programs that
1724 didn't use Unicode, along with Perl's desire to add Unicode support
1725 seamlessly.  But the result turned out to not be seamless.  (By the way,
1726 you can choose to be warned when things like this happen.  See
1727 C<L<encoding::warnings>>.)
1728
1729 L<S<C<use feature 'unicode_strings'>>|feature/The 'unicode_strings' feature>
1730 was added, starting in Perl v5.12, to address this problem.  It affects
1731 these things:
1732
1733 =over 4
1734
1735 =item *
1736
1737 Changing the case of a scalar, that is, using C<uc()>, C<ucfirst()>, C<lc()>,
1738 and C<lcfirst()>, or C<\L>, C<\U>, C<\u> and C<\l> in double-quotish
1739 contexts, such as regular expression substitutions.
1740
1741 Under C<unicode_strings> starting in Perl 5.12.0, Unicode rules are
1742 generally used.  See L<perlfunc/lc> for details on how this works
1743 in combination with various other pragmas.
1744
1745 =item *
1746
1747 Using caseless (C</i>) regular expression matching.
1748
1749 Starting in Perl 5.14.0, regular expressions compiled within
1750 the scope of C<unicode_strings> use Unicode rules
1751 even when executed or compiled into larger
1752 regular expressions outside the scope.
1753
1754 =item *
1755
1756 Matching any of several properties in regular expressions.
1757
1758 These properties are C<\b> (without braces), C<\B> (without braces),
1759 C<\s>, C<\S>, C<\w>, C<\W>, and all the Posix character classes
1760 I<except> C<[[:ascii:]]>.
1761
1762 Starting in Perl 5.14.0, regular expressions compiled within
1763 the scope of C<unicode_strings> use Unicode rules
1764 even when executed or compiled into larger
1765 regular expressions outside the scope.
1766
1767 =item *
1768
1769 In C<quotemeta> or its inline equivalent C<\Q>.
1770
1771 Starting in Perl 5.16.0, consistent quoting rules are used within the
1772 scope of C<unicode_strings>, as described in L<perlfunc/quotemeta>.
1773 Prior to that, or outside its scope, no code points above 127 are quoted
1774 in UTF-8 encoded strings, but in byte encoded strings, code points
1775 between 128-255 are always quoted.
1776
1777 =back
1778
1779 You can see from the above that the effect of C<unicode_strings>
1780 increased over several Perl releases.  (And Perl's support for Unicode
1781 continues to improve; it's best to use the latest available release in
1782 order to get the most complete and accurate results possible.)  Note that
1783 C<unicode_strings> is automatically chosen if you S<C<use 5.012>> or
1784 higher.
1785
1786 For Perls earlier than those described above, or when a string is passed
1787 to a function outside the scope of C<unicode_strings>, see the next section.
1788
1789 =head2 Forcing Unicode in Perl (Or Unforcing Unicode in Perl)
1790
1791 Sometimes (see L</"When Unicode Does Not Happen"> or L</The "Unicode Bug">)
1792 there are situations where you simply need to force a byte
1793 string into UTF-8, or vice versa.  The standard module L<Encode> can be
1794 used for this, or the low-level calls
1795 L<C<utf8::upgrade($bytestring)>|utf8/Utility functions> and
1796 L<C<utf8::downgrade($utf8string[, FAIL_OK])>|utf8/Utility functions>.
1797
1798 Note that C<utf8::downgrade()> can fail if the string contains characters
1799 that don't fit into a byte.
1800
1801 Calling either function on a string that already is in the desired state is a
1802 no-op.
1803
1804 L</ASCII Rules versus Unicode Rules> gives all the ways that a string is
1805 made to use Unicode rules.
1806
1807 =head2 Using Unicode in XS
1808
1809 See L<perlguts/"Unicode Support"> for an introduction to Unicode at
1810 the XS level, and L<perlapi/Unicode Support> for the API details.
1811
1812 =head2 Hacking Perl to work on earlier Unicode versions (for very serious hackers only)
1813
1814 Perl by default comes with the latest supported Unicode version built-in, but
1815 the goal is to allow you to change to use any earlier one.  In Perls
1816 v5.20 and v5.22, however, the earliest usable version is Unicode 5.1.
1817 Perl v5.18 is able to handle all earlier versions.
1818
1819 Download the files in the desired version of Unicode from the Unicode web
1820 site L<http://www.unicode.org>).  These should replace the existing files in
1821 F<lib/unicore> in the Perl source tree.  Follow the instructions in
1822 F<README.perl> in that directory to change some of their names, and then build
1823 perl (see L<INSTALL>).
1824
1825 =head2 Porting code from perl-5.6.X
1826
1827 Perls starting in 5.8 have a different Unicode model from 5.6. In 5.6 the
1828 programmer was required to use the C<utf8> pragma to declare that a
1829 given scope expected to deal with Unicode data and had to make sure that
1830 only Unicode data were reaching that scope. If you have code that is
1831 working with 5.6, you will need some of the following adjustments to
1832 your code. The examples are written such that the code will continue to
1833 work under 5.6, so you should be safe to try them out.
1834
1835 =over 3
1836
1837 =item *
1838
1839 A filehandle that should read or write UTF-8
1840
1841   if ($] > 5.008) {
1842     binmode $fh, ":encoding(utf8)";
1843   }
1844
1845 =item *
1846
1847 A scalar that is going to be passed to some extension
1848
1849 Be it C<Compress::Zlib>, C<Apache::Request> or any extension that has no
1850 mention of Unicode in the manpage, you need to make sure that the
1851 UTF8 flag is stripped off. Note that at the time of this writing
1852 (January 2012) the mentioned modules are not UTF-8-aware. Please
1853 check the documentation to verify if this is still true.
1854
1855   if ($] > 5.008) {
1856     require Encode;
1857     $val = Encode::encode_utf8($val); # make octets
1858   }
1859
1860 =item *
1861
1862 A scalar we got back from an extension
1863
1864 If you believe the scalar comes back as UTF-8, you will most likely
1865 want the UTF8 flag restored:
1866
1867   if ($] > 5.008) {
1868     require Encode;
1869     $val = Encode::decode_utf8($val);
1870   }
1871
1872 =item *
1873
1874 Same thing, if you are really sure it is UTF-8
1875
1876   if ($] > 5.008) {
1877     require Encode;
1878     Encode::_utf8_on($val);
1879   }
1880
1881 =item *
1882
1883 A wrapper for L<DBI> C<fetchrow_array> and C<fetchrow_hashref>
1884
1885 When the database contains only UTF-8, a wrapper function or method is
1886 a convenient way to replace all your C<fetchrow_array> and
1887 C<fetchrow_hashref> calls. A wrapper function will also make it easier to
1888 adapt to future enhancements in your database driver. Note that at the
1889 time of this writing (January 2012), the DBI has no standardized way
1890 to deal with UTF-8 data. Please check the L<DBI documentation|DBI> to verify if
1891 that is still true.
1892
1893   sub fetchrow {
1894     # $what is one of fetchrow_{array,hashref}
1895     my($self, $sth, $what) = @_;
1896     if ($] < 5.008) {
1897       return $sth->$what;
1898     } else {
1899       require Encode;
1900       if (wantarray) {
1901         my @arr = $sth->$what;
1902         for (@arr) {
1903           defined && /[^\000-\177]/ && Encode::_utf8_on($_);
1904         }
1905         return @arr;
1906       } else {
1907         my $ret = $sth->$what;
1908         if (ref $ret) {
1909           for my $k (keys %$ret) {
1910             defined
1911             && /[^\000-\177]/
1912             && Encode::_utf8_on($_) for $ret->{$k};
1913           }
1914           return $ret;
1915         } else {
1916           defined && /[^\000-\177]/ && Encode::_utf8_on($_) for $ret;
1917           return $ret;
1918         }
1919       }
1920     }
1921   }
1922
1923
1924 =item *
1925
1926 A large scalar that you know can only contain ASCII
1927
1928 Scalars that contain only ASCII and are marked as UTF-8 are sometimes
1929 a drag to your program. If you recognize such a situation, just remove
1930 the UTF8 flag:
1931
1932   utf8::downgrade($val) if $] > 5.008;
1933
1934 =back
1935
1936 =head1 BUGS
1937
1938 See also L</The "Unicode Bug"> above.
1939
1940 =head2 Interaction with Extensions
1941
1942 When Perl exchanges data with an extension, the extension should be
1943 able to understand the UTF8 flag and act accordingly. If the
1944 extension doesn't recognize that flag, it's likely that the extension
1945 will return incorrectly-flagged data.
1946
1947 So if you're working with Unicode data, consult the documentation of
1948 every module you're using if there are any issues with Unicode data
1949 exchange. If the documentation does not talk about Unicode at all,
1950 suspect the worst and probably look at the source to learn how the
1951 module is implemented. Modules written completely in Perl shouldn't
1952 cause problems. Modules that directly or indirectly access code written
1953 in other programming languages are at risk.
1954
1955 For affected functions, the simple strategy to avoid data corruption is
1956 to always make the encoding of the exchanged data explicit. Choose an
1957 encoding that you know the extension can handle. Convert arguments passed
1958 to the extensions to that encoding and convert results back from that
1959 encoding. Write wrapper functions that do the conversions for you, so
1960 you can later change the functions when the extension catches up.
1961
1962 To provide an example, let's say the popular C<Foo::Bar::escape_html>
1963 function doesn't deal with Unicode data yet. The wrapper function
1964 would convert the argument to raw UTF-8 and convert the result back to
1965 Perl's internal representation like so:
1966
1967     sub my_escape_html ($) {
1968         my($what) = shift;
1969         return unless defined $what;
1970         Encode::decode_utf8(Foo::Bar::escape_html(
1971                                          Encode::encode_utf8($what)));
1972     }
1973
1974 Sometimes, when the extension does not convert data but just stores
1975 and retrieves it, you will be able to use the otherwise
1976 dangerous L<C<Encode::_utf8_on()>|Encode/_utf8_on> function. Let's say
1977 the popular C<Foo::Bar> extension, written in C, provides a C<param>
1978 method that lets you store and retrieve data according to these prototypes:
1979
1980     $self->param($name, $value);            # set a scalar
1981     $value = $self->param($name);           # retrieve a scalar
1982
1983 If it does not yet provide support for any encoding, one could write a
1984 derived class with such a C<param> method:
1985
1986     sub param {
1987       my($self,$name,$value) = @_;
1988       utf8::upgrade($name);     # make sure it is UTF-8 encoded
1989       if (defined $value) {
1990         utf8::upgrade($value);  # make sure it is UTF-8 encoded
1991         return $self->SUPER::param($name,$value);
1992       } else {
1993         my $ret = $self->SUPER::param($name);
1994         Encode::_utf8_on($ret); # we know, it is UTF-8 encoded
1995         return $ret;
1996       }
1997     }
1998
1999 Some extensions provide filters on data entry/exit points, such as
2000 C<DB_File::filter_store_key> and family. Look out for such filters in
2001 the documentation of your extensions; they can make the transition to
2002 Unicode data much easier.
2003
2004 =head2 Speed
2005
2006 Some functions are slower when working on UTF-8 encoded strings than
2007 on byte encoded strings.  All functions that need to hop over
2008 characters such as C<length()>, C<substr()> or C<index()>, or matching
2009 regular expressions can work B<much> faster when the underlying data are
2010 byte-encoded.
2011
2012 In Perl 5.8.0 the slowness was often quite spectacular; in Perl 5.8.1
2013 a caching scheme was introduced which improved the situation.  In general,
2014 operations with UTF-8 encoded strings are still slower. As an example,
2015 the Unicode properties (character classes) like C<\p{Nd}> are known to
2016 be quite a bit slower (5-20 times) than their simpler counterparts
2017 like C<[0-9]> (then again, there are hundreds of Unicode characters matching
2018 C<Nd> compared with the 10 ASCII characters matching C<[0-9]>).
2019
2020 =head1 SEE ALSO
2021
2022 L<perlunitut>, L<perluniintro>, L<perluniprops>, L<Encode>, L<open>, L<utf8>, L<bytes>,
2023 L<perlretut>, L<perlvar/"${^UNICODE}">,
2024 L<http://www.unicode.org/reports/tr44>).
2025
2026 =cut