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