Re: [MacOS X] consider useshrplib='false' by default
[perl.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 =over 4
14
15 =item Input and Output Layers
16
17 Perl knows when a filehandle uses Perl's internal Unicode encodings
18 (UTF-8, or UTF-EBCDIC if in EBCDIC) if the filehandle is opened with
19 the ":utf8" layer.  Other encodings can be converted to Perl's
20 encoding on input or from Perl's encoding on output by use of the
21 ":encoding(...)"  layer.  See L<open>.
22
23 To indicate that Perl source itself is using a particular encoding,
24 see L<encoding>.
25
26 =item Regular Expressions
27
28 The regular expression compiler produces polymorphic opcodes.  That is,
29 the pattern adapts to the data and automatically switches to the Unicode
30 character scheme when presented with Unicode data--or instead uses
31 a traditional byte scheme when presented with byte data.
32
33 =item C<use utf8> still needed to enable UTF-8/UTF-EBCDIC in scripts
34
35 As a compatibility measure, the C<use utf8> pragma must be explicitly
36 included to enable recognition of UTF-8 in the Perl scripts themselves
37 (in string or regular expression literals, or in identifier names) on
38 ASCII-based machines or to recognize UTF-EBCDIC on EBCDIC-based
39 machines.  B<These are the only times when an explicit C<use utf8>
40 is needed.>  See L<utf8>.
41
42 You can also use the C<encoding> pragma to change the default encoding
43 of the data in your script; see L<encoding>.
44
45 =back
46
47 =head2 Byte and Character Semantics
48
49 Beginning with version 5.6, Perl uses logically-wide characters to
50 represent strings internally.
51
52 In future, Perl-level operations will be expected to work with
53 characters rather than bytes.
54
55 However, as an interim compatibility measure, Perl aims to
56 provide a safe migration path from byte semantics to character
57 semantics for programs.  For operations where Perl can unambiguously
58 decide that the input data are characters, Perl switches to
59 character semantics.  For operations where this determination cannot
60 be made without additional information from the user, Perl decides in
61 favor of compatibility and chooses to use byte semantics.
62
63 This behavior preserves compatibility with earlier versions of Perl,
64 which allowed byte semantics in Perl operations only if
65 none of the program's inputs were marked as being as source of Unicode
66 character data.  Such data may come from filehandles, from calls to
67 external programs, from information provided by the system (such as %ENV),
68 or from literals and constants in the source text.
69
70 The C<bytes> pragma will always, regardless of platform, force byte
71 semantics in a particular lexical scope.  See L<bytes>.
72
73 The C<utf8> pragma is primarily a compatibility device that enables
74 recognition of UTF-(8|EBCDIC) in literals encountered by the parser.
75 Note that this pragma is only required while Perl defaults to byte
76 semantics; when character semantics become the default, this pragma
77 may become a no-op.  See L<utf8>.
78
79 Unless explicitly stated, Perl operators use character semantics
80 for Unicode data and byte semantics for non-Unicode data.
81 The decision to use character semantics is made transparently.  If
82 input data comes from a Unicode source--for example, if a character
83 encoding layer is added to a filehandle or a literal Unicode
84 string constant appears in a program--character semantics apply.
85 Otherwise, byte semantics are in effect.  The C<bytes> pragma should
86 be used to force byte semantics on Unicode data.
87
88 If strings operating under byte semantics and strings with Unicode
89 character data are concatenated, the new string will be upgraded to
90 I<ISO 8859-1 (Latin-1)>, even if the old Unicode string used EBCDIC.
91 This translation is done without regard to the system's native 8-bit
92 encoding, so to change this for systems with non-Latin-1 and 
93 non-EBCDIC native encodings use the C<encoding> pragma.  See
94 L<encoding>.
95
96 Under character semantics, many operations that formerly operated on
97 bytes now operate on characters. A character in Perl is
98 logically just a number ranging from 0 to 2**31 or so. Larger
99 characters may encode into longer sequences of bytes internally, but
100 this internal detail is mostly hidden for Perl code.
101 See L<perluniintro> for more.
102
103 =head2 Effects of Character Semantics
104
105 Character semantics have the following effects:
106
107 =over 4
108
109 =item *
110
111 Strings--including hash keys--and regular expression patterns may
112 contain characters that have an ordinal value larger than 255.
113
114 If you use a Unicode editor to edit your program, Unicode characters
115 may occur directly within the literal strings in one of the various
116 Unicode encodings (UTF-8, UTF-EBCDIC, UCS-2, etc.), but will be recognized
117 as such and converted to Perl's internal representation only if the
118 appropriate L<encoding> is specified.
119
120 Unicode characters can also be added to a string by using the
121 C<\x{...}> notation.  The Unicode code for the desired character, in
122 hexadecimal, should be placed in the braces. For instance, a smiley
123 face is C<\x{263A}>.  This encoding scheme only works for characters
124 with a code of 0x100 or above.
125
126 Additionally, if you
127
128    use charnames ':full';
129
130 you can use the C<\N{...}> notation and put the official Unicode
131 character name within the braces, such as C<\N{WHITE SMILING FACE}>.
132
133
134 =item *
135
136 If an appropriate L<encoding> is specified, identifiers within the
137 Perl script may contain Unicode alphanumeric characters, including
138 ideographs.  Perl does not currently attempt to canonicalize variable
139 names.
140
141 =item *
142
143 Regular expressions match characters instead of bytes.  "." matches
144 a character instead of a byte.  The C<\C> pattern is provided to force
145 a match a single byte--a C<char> in C, hence C<\C>.
146
147 =item *
148
149 Character classes in regular expressions match characters instead of
150 bytes and match against the character properties specified in the
151 Unicode properties database.  C<\w> can be used to match a Japanese
152 ideograph, for instance.
153
154 =item *
155
156 Named Unicode properties, scripts, and block ranges may be used like
157 character classes via the C<\p{}> "matches property" construct and
158 the  C<\P{}> negation, "doesn't match property".
159
160 For instance, C<\p{Lu}> matches any character with the Unicode "Lu"
161 (Letter, uppercase) property, while C<\p{M}> matches any character
162 with an "M" (mark--accents and such) property.  Brackets are not
163 required for single letter properties, so C<\p{M}> is equivalent to
164 C<\pM>. Many predefined properties are available, such as
165 C<\p{Mirrored}> and C<\p{Tibetan}>.
166
167 The official Unicode script and block names have spaces and dashes as
168 separators, but for convenience you can use dashes, spaces, or
169 underbars, and case is unimportant. It is recommended, however, that
170 for consistency you use the following naming: the official Unicode
171 script, property, or block name (see below for the additional rules
172 that apply to block names) with whitespace and dashes removed, and the
173 words "uppercase-first-lowercase-rest". C<Latin-1 Supplement> thus
174 becomes C<Latin1Supplement>.
175
176 You can also use negation in both C<\p{}> and C<\P{}> by introducing a caret
177 (^) between the first brace and the property name: C<\p{^Tamil}> is
178 equal to C<\P{Tamil}>.
179
180 Here are the basic Unicode General Category properties, followed by their
181 long form.  You can use either; C<\p{Lu}> and C<\p{UppercaseLetter}>,
182 for instance, are identical.
183
184     Short       Long
185
186     L           Letter
187     Lu          UppercaseLetter
188     Ll          LowercaseLetter
189     Lt          TitlecaseLetter
190     Lm          ModifierLetter
191     Lo          OtherLetter
192
193     M           Mark
194     Mn          NonspacingMark
195     Mc          SpacingMark
196     Me          EnclosingMark
197
198     N           Number
199     Nd          DecimalNumber
200     Nl          LetterNumber
201     No          OtherNumber
202
203     P           Punctuation
204     Pc          ConnectorPunctuation
205     Pd          DashPunctuation
206     Ps          OpenPunctuation
207     Pe          ClosePunctuation
208     Pi          InitialPunctuation
209                 (may behave like Ps or Pe depending on usage)
210     Pf          FinalPunctuation
211                 (may behave like Ps or Pe depending on usage)
212     Po          OtherPunctuation
213
214     S           Symbol
215     Sm          MathSymbol
216     Sc          CurrencySymbol
217     Sk          ModifierSymbol
218     So          OtherSymbol
219
220     Z           Separator
221     Zs          SpaceSeparator
222     Zl          LineSeparator
223     Zp          ParagraphSeparator
224
225     C           Other
226     Cc          Control
227     Cf          Format
228     Cs          Surrogate   (not usable)
229     Co          PrivateUse
230     Cn          Unassigned
231
232 Single-letter properties match all characters in any of the
233 two-letter sub-properties starting with the same letter.
234 C<L&> is a special case, which is an alias for C<Ll>, C<Lu>, and C<Lt>.
235
236 Because Perl hides the need for the user to understand the internal
237 representation of Unicode characters, there is no need to implement
238 the somewhat messy concept of surrogates. C<Cs> is therefore not
239 supported.
240
241 Because scripts differ in their directionality--Hebrew is
242 written right to left, for example--Unicode supplies these properties:
243
244     Property    Meaning
245
246     BidiL       Left-to-Right
247     BidiLRE     Left-to-Right Embedding
248     BidiLRO     Left-to-Right Override
249     BidiR       Right-to-Left
250     BidiAL      Right-to-Left Arabic
251     BidiRLE     Right-to-Left Embedding
252     BidiRLO     Right-to-Left Override
253     BidiPDF     Pop Directional Format
254     BidiEN      European Number
255     BidiES      European Number Separator
256     BidiET      European Number Terminator
257     BidiAN      Arabic Number
258     BidiCS      Common Number Separator
259     BidiNSM     Non-Spacing Mark
260     BidiBN      Boundary Neutral
261     BidiB       Paragraph Separator
262     BidiS       Segment Separator
263     BidiWS      Whitespace
264     BidiON      Other Neutrals
265
266 For example, C<\p{BidiR}> matches characters that are normally
267 written right to left.
268
269 =back
270
271 =head2 Scripts
272
273 The script names which can be used by C<\p{...}> and C<\P{...}>,
274 such as in C<\p{Latin}> or C<\p{Cyrillic}>, are as follows:
275
276     Arabic
277     Armenian
278     Bengali
279     Bopomofo
280     Buhid
281     CanadianAboriginal
282     Cherokee
283     Cyrillic
284     Deseret
285     Devanagari
286     Ethiopic
287     Georgian
288     Gothic
289     Greek
290     Gujarati
291     Gurmukhi
292     Han
293     Hangul
294     Hanunoo
295     Hebrew
296     Hiragana
297     Inherited
298     Kannada
299     Katakana
300     Khmer
301     Lao
302     Latin
303     Malayalam
304     Mongolian
305     Myanmar
306     Ogham
307     OldItalic
308     Oriya
309     Runic
310     Sinhala
311     Syriac
312     Tagalog
313     Tagbanwa
314     Tamil
315     Telugu
316     Thaana
317     Thai
318     Tibetan
319     Yi
320
321 Extended property classes can supplement the basic
322 properties, defined by the F<PropList> Unicode database:
323
324     ASCIIHexDigit
325     BidiControl
326     Dash
327     Deprecated
328     Diacritic
329     Extender
330     GraphemeLink
331     HexDigit
332     Hyphen
333     Ideographic
334     IDSBinaryOperator
335     IDSTrinaryOperator
336     JoinControl
337     LogicalOrderException
338     NoncharacterCodePoint
339     OtherAlphabetic
340     OtherDefaultIgnorableCodePoint
341     OtherGraphemeExtend
342     OtherLowercase
343     OtherMath
344     OtherUppercase
345     QuotationMark
346     Radical
347     SoftDotted
348     TerminalPunctuation
349     UnifiedIdeograph
350     WhiteSpace
351
352 and there are further derived properties:
353
354     Alphabetic      Lu + Ll + Lt + Lm + Lo + OtherAlphabetic
355     Lowercase       Ll + OtherLowercase
356     Uppercase       Lu + OtherUppercase
357     Math            Sm + OtherMath
358
359     ID_Start        Lu + Ll + Lt + Lm + Lo + Nl
360     ID_Continue     ID_Start + Mn + Mc + Nd + Pc
361
362     Any             Any character
363     Assigned        Any non-Cn character (i.e. synonym for \P{Cn})
364     Unassigned      Synonym for \p{Cn}
365     Common          Any character (or unassigned code point)
366                     not explicitly assigned to a script
367
368 For backward compatibility (with Perl 5.6), all properties mentioned
369 so far may have C<Is> prepended to their name, so C<\P{IsLu}>, for
370 example, is equal to C<\P{Lu}>.
371
372 =head2 Blocks
373
374 In addition to B<scripts>, Unicode also defines B<blocks> of
375 characters.  The difference between scripts and blocks is that the
376 concept of scripts is closer to natural languages, while the concept
377 of blocks is more of an artificial grouping based on groups of 256
378 Unicode characters. For example, the C<Latin> script contains letters
379 from many blocks but does not contain all the characters from those
380 blocks. It does not, for example, contain digits, because digits are
381 shared across many scripts. Digits and similar groups, like
382 punctuation, are in a category called C<Common>.
383
384 For more about scripts, see the UTR #24:
385
386    http://www.unicode.org/unicode/reports/tr24/
387
388 For more about blocks, see:
389
390    http://www.unicode.org/Public/UNIDATA/Blocks.txt
391
392 Block names are given with the C<In> prefix. For example, the
393 Katakana block is referenced via C<\p{InKatakana}>.  The C<In>
394 prefix may be omitted if there is no naming conflict with a script
395 or any other property, but it is recommended that C<In> always be used
396 for block tests to avoid confusion.
397
398 These block names are supported:
399
400     InAlphabeticPresentationForms
401     InArabic
402     InArabicPresentationFormsA
403     InArabicPresentationFormsB
404     InArmenian
405     InArrows
406     InBasicLatin
407     InBengali
408     InBlockElements
409     InBopomofo
410     InBopomofoExtended
411     InBoxDrawing
412     InBraillePatterns
413     InBuhid
414     InByzantineMusicalSymbols
415     InCJKCompatibility
416     InCJKCompatibilityForms
417     InCJKCompatibilityIdeographs
418     InCJKCompatibilityIdeographsSupplement
419     InCJKRadicalsSupplement
420     InCJKSymbolsAndPunctuation
421     InCJKUnifiedIdeographs
422     InCJKUnifiedIdeographsExtensionA
423     InCJKUnifiedIdeographsExtensionB
424     InCherokee
425     InCombiningDiacriticalMarks
426     InCombiningDiacriticalMarksforSymbols
427     InCombiningHalfMarks
428     InControlPictures
429     InCurrencySymbols
430     InCyrillic
431     InCyrillicSupplementary
432     InDeseret
433     InDevanagari
434     InDingbats
435     InEnclosedAlphanumerics
436     InEnclosedCJKLettersAndMonths
437     InEthiopic
438     InGeneralPunctuation
439     InGeometricShapes
440     InGeorgian
441     InGothic
442     InGreekExtended
443     InGreekAndCoptic
444     InGujarati
445     InGurmukhi
446     InHalfwidthAndFullwidthForms
447     InHangulCompatibilityJamo
448     InHangulJamo
449     InHangulSyllables
450     InHanunoo
451     InHebrew
452     InHighPrivateUseSurrogates
453     InHighSurrogates
454     InHiragana
455     InIPAExtensions
456     InIdeographicDescriptionCharacters
457     InKanbun
458     InKangxiRadicals
459     InKannada
460     InKatakana
461     InKatakanaPhoneticExtensions
462     InKhmer
463     InLao
464     InLatin1Supplement
465     InLatinExtendedA
466     InLatinExtendedAdditional
467     InLatinExtendedB
468     InLetterlikeSymbols
469     InLowSurrogates
470     InMalayalam
471     InMathematicalAlphanumericSymbols
472     InMathematicalOperators
473     InMiscellaneousMathematicalSymbolsA
474     InMiscellaneousMathematicalSymbolsB
475     InMiscellaneousSymbols
476     InMiscellaneousTechnical
477     InMongolian
478     InMusicalSymbols
479     InMyanmar
480     InNumberForms
481     InOgham
482     InOldItalic
483     InOpticalCharacterRecognition
484     InOriya
485     InPrivateUseArea
486     InRunic
487     InSinhala
488     InSmallFormVariants
489     InSpacingModifierLetters
490     InSpecials
491     InSuperscriptsAndSubscripts
492     InSupplementalArrowsA
493     InSupplementalArrowsB
494     InSupplementalMathematicalOperators
495     InSupplementaryPrivateUseAreaA
496     InSupplementaryPrivateUseAreaB
497     InSyriac
498     InTagalog
499     InTagbanwa
500     InTags
501     InTamil
502     InTelugu
503     InThaana
504     InThai
505     InTibetan
506     InUnifiedCanadianAboriginalSyllabics
507     InVariationSelectors
508     InYiRadicals
509     InYiSyllables
510
511 =over 4
512
513 =item *
514
515 The special pattern C<\X> matches any extended Unicode
516 sequence--"a combining character sequence" in Standardese--where the
517 first character is a base character and subsequent characters are mark
518 characters that apply to the base character.  C<\X> is equivalent to
519 C<(?:\PM\pM*)>.
520
521 =item *
522
523 The C<tr///> operator translates characters instead of bytes.  Note
524 that the C<tr///CU> functionality has been removed.  For similar
525 functionality see pack('U0', ...) and pack('C0', ...).
526
527 =item *
528
529 Case translation operators use the Unicode case translation tables
530 when character input is provided.  Note that C<uc()>, or C<\U> in
531 interpolated strings, translates to uppercase, while C<ucfirst>,
532 or C<\u> in interpolated strings, translates to titlecase in languages
533 that make the distinction.
534
535 =item *
536
537 Most operators that deal with positions or lengths in a string will
538 automatically switch to using character positions, including
539 C<chop()>, C<substr()>, C<pos()>, C<index()>, C<rindex()>,
540 C<sprintf()>, C<write()>, and C<length()>.  Operators that
541 specifically do not switch include C<vec()>, C<pack()>, and
542 C<unpack()>.  Operators that really don't care include C<chomp()>,
543 operators that treats strings as a bucket of bits such as C<sort()>,
544 and operators dealing with filenames.
545
546 =item *
547
548 The C<pack()>/C<unpack()> letters C<c> and C<C> do I<not> change,
549 since they are often used for byte-oriented formats.  Again, think
550 C<char> in the C language.
551
552 There is a new C<U> specifier that converts between Unicode characters
553 and code points.
554
555 =item *
556
557 The C<chr()> and C<ord()> functions work on characters, similar to
558 C<pack("U")> and C<unpack("U")>, I<not> C<pack("C")> and
559 C<unpack("C")>.  C<pack("C")> and C<unpack("C")> are methods for
560 emulating byte-oriented C<chr()> and C<ord()> on Unicode strings.
561 While these methods reveal the internal encoding of Unicode strings,
562 that is not something one normally needs to care about at all.
563
564 =item *
565
566 The bit string operators, C<& | ^ ~>, can operate on character data.
567 However, for backward compatibility, such as when using bit string
568 operations when characters are all less than 256 in ordinal value, one
569 should not use C<~> (the bit complement) with characters of both
570 values less than 256 and values greater than 256.  Most importantly,
571 DeMorgan's laws (C<~($x|$y) eq ~$x&~$y> and C<~($x&$y) eq ~$x|~$y>)
572 will not hold.  The reason for this mathematical I<faux pas> is that
573 the complement cannot return B<both> the 8-bit (byte-wide) bit
574 complement B<and> the full character-wide bit complement.
575
576 =item *
577
578 lc(), uc(), lcfirst(), and ucfirst() work for the following cases:
579
580 =over 8
581
582 =item *
583
584 the case mapping is from a single Unicode character to another
585 single Unicode character, or
586
587 =item *
588
589 the case mapping is from a single Unicode character to more
590 than one Unicode character.
591
592 =back
593
594 Things to do with locales (Lithuanian, Turkish, Azeri) do B<not> work
595 since Perl does not understand the concept of Unicode locales.
596
597 See the Unicode Technical Report #21, Case Mappings, for more details.
598
599 =back
600
601 =over 4
602
603 =item *
604
605 And finally, C<scalar reverse()> reverses by character rather than by byte.
606
607 =back
608
609 =head2 User-Defined Character Properties
610
611 You can define your own character properties by defining subroutines
612 whose names begin with "In" or "Is".  The subroutines must be defined
613 in the C<main> package.  The user-defined properties can be used in the
614 regular expression C<\p> and C<\P> constructs.  Note that the effect
615 is compile-time and immutable once defined.
616
617 The subroutines must return a specially-formatted string, with one
618 or more newline-separated lines.  Each line must be one of the following:
619
620 =over 4
621
622 =item *
623
624 Two hexadecimal numbers separated by horizontal whitespace (space or
625 tabular characters) denoting a range of Unicode code points to include.
626
627 =item *
628
629 Something to include, prefixed by "+": a built-in character
630 property (prefixed by "utf8::"), to represent all the characters in that
631 property; two hexadecimal code points for a range; or a single
632 hexadecimal code point.
633
634 =item *
635
636 Something to exclude, prefixed by "-": an existing character
637 property (prefixed by "utf8::"), for all the characters in that
638 property; two hexadecimal code points for a range; or a single
639 hexadecimal code point.
640
641 =item *
642
643 Something to negate, prefixed "!": an existing character
644 property (prefixed by "utf8::") for all the characters except the
645 characters in the property; two hexadecimal code points for a range;
646 or a single hexadecimal code point.
647
648 =back
649
650 For example, to define a property that covers both the Japanese
651 syllabaries (hiragana and katakana), you can define
652
653     sub InKana {
654         return <<END;
655     3040\t309F
656     30A0\t30FF
657     END
658     }
659
660 Imagine that the here-doc end marker is at the beginning of the line.
661 Now you can use C<\p{InKana}> and C<\P{InKana}>.
662
663 You could also have used the existing block property names:
664
665     sub InKana {
666         return <<'END';
667     +utf8::InHiragana
668     +utf8::InKatakana
669     END
670     }
671
672 Suppose you wanted to match only the allocated characters,
673 not the raw block ranges: in other words, you want to remove
674 the non-characters:
675
676     sub InKana {
677         return <<'END';
678     +utf8::InHiragana
679     +utf8::InKatakana
680     -utf8::IsCn
681     END
682     }
683
684 The negation is useful for defining (surprise!) negated classes.
685
686     sub InNotKana {
687         return <<'END';
688     !utf8::InHiragana
689     -utf8::InKatakana
690     +utf8::IsCn
691     END
692     }
693
694 You can also define your own mappings to be used in the lc(),
695 lcfirst(), uc(), and ucfirst() (or their string-inlined versions).
696 The principle is the same: define subroutines in the C<main> package
697 with names like C<ToLower> (for lc() and lcfirst()), C<ToTitle> (for
698 the first character in ucfirst()), and C<ToUpper> (for uc(), and the
699 rest of the characters in ucfirst()).
700
701 The string returned by the subroutines needs now to be three
702 hexadecimal numbers separated by tabulators: start of the source
703 range, end of the source range, and start of the destination range.
704 For example:
705
706     sub ToUpper {
707         return <<END;
708     0061\t0063\t0041
709     END
710     }
711
712 defines an uc() mapping that causes only the characters "a", "b", and
713 "c" to be mapped to "A", "B", "C", all other characters will remain
714 unchanged.
715
716 If there is no source range to speak of, that is, the mapping is from
717 a single character to another single character, leave the end of the
718 source range empty, but the two tabulator characters are still needed.
719 For example:
720
721     sub ToLower {
722         return <<END;
723     0041\t\t0061
724     END
725     }
726
727 defines a lc() mapping that causes only "A" to be mapped to "a", all
728 other characters will remain unchanged.
729
730 (For serious hackers only)  If you want to introspect the default
731 mappings, you can find the data in the directory
732 C<$Config{privlib}>/F<unicore/To/>.  The mapping data is returned as
733 the here-document, and the C<utf8::ToSpecFoo> are special exception
734 mappings derived from <$Config{privlib}>/F<unicore/SpecialCasing.txt>.
735 The C<Digit> and C<Fold> mappings that one can see in the directory
736 are not directly user-accessible, one can use either the
737 C<Unicode::UCD> module, or just match case-insensitively (that's when
738 the C<Fold> mapping is used).
739
740 A final note on the user-defined property tests and mappings: they
741 will be used only if the scalar has been marked as having Unicode
742 characters.  Old byte-style strings will not be affected.
743
744 =head2 Character Encodings for Input and Output
745
746 See L<Encode>.
747
748 =head2 Unicode Regular Expression Support Level
749
750 The following list of Unicode support for regular expressions describes
751 all the features currently supported.  The references to "Level N"
752 and the section numbers refer to the Unicode Technical Report 18,
753 "Unicode Regular Expression Guidelines".
754
755 =over 4
756
757 =item *
758
759 Level 1 - Basic Unicode Support
760
761         2.1 Hex Notation                        - done          [1]
762             Named Notation                      - done          [2]
763         2.2 Categories                          - done          [3][4]
764         2.3 Subtraction                         - MISSING       [5][6]
765         2.4 Simple Word Boundaries              - done          [7]
766         2.5 Simple Loose Matches                - done          [8]
767         2.6 End of Line                         - MISSING       [9][10]
768
769         [ 1] \x{...}
770         [ 2] \N{...}
771         [ 3] . \p{...} \P{...}
772         [ 4] now scripts (see UTR#24 Script Names) in addition to blocks
773         [ 5] have negation
774         [ 6] can use regular expression look-ahead [a]
775              or user-defined character properties [b] to emulate subtraction
776         [ 7] include Letters in word characters
777         [ 8] note that Perl does Full case-folding in matching, not Simple:
778              for example U+1F88 is equivalent with U+1F00 U+03B9,
779              not with 1F80.  This difference matters for certain Greek
780              capital letters with certain modifiers: the Full case-folding
781              decomposes the letter, while the Simple case-folding would map
782              it to a single character.
783         [ 9] see UTR#13 Unicode Newline Guidelines
784         [10] should do ^ and $ also on \x{85}, \x{2028} and \x{2029}
785              (should also affect <>, $., and script line numbers)
786              (the \x{85}, \x{2028} and \x{2029} do match \s)
787
788 [a] You can mimic class subtraction using lookahead.
789 For example, what TR18 might write as
790
791     [{Greek}-[{UNASSIGNED}]]
792
793 in Perl can be written as:
794
795     (?!\p{Unassigned})\p{InGreekAndCoptic}
796     (?=\p{Assigned})\p{InGreekAndCoptic}
797
798 But in this particular example, you probably really want
799
800     \p{GreekAndCoptic}
801
802 which will match assigned characters known to be part of the Greek script.
803
804 [b] See L</"User-Defined Character Properties">.
805
806 =item *
807
808 Level 2 - Extended Unicode Support
809
810         3.1 Surrogates                          - MISSING       [11]
811         3.2 Canonical Equivalents               - MISSING       [12][13]
812         3.3 Locale-Independent Graphemes        - MISSING       [14]
813         3.4 Locale-Independent Words            - MISSING       [15]
814         3.5 Locale-Independent Loose Matches    - MISSING       [16]
815
816         [11] Surrogates are solely a UTF-16 concept and Perl's internal
817              representation is UTF-8.  The Encode module does UTF-16, though.
818         [12] see UTR#15 Unicode Normalization
819         [13] have Unicode::Normalize but not integrated to regexes
820         [14] have \X but at this level . should equal that
821         [15] need three classes, not just \w and \W
822         [16] see UTR#21 Case Mappings
823
824 =item *
825
826 Level 3 - Locale-Sensitive Support
827
828         4.1 Locale-Dependent Categories         - MISSING
829         4.2 Locale-Dependent Graphemes          - MISSING       [16][17]
830         4.3 Locale-Dependent Words              - MISSING
831         4.4 Locale-Dependent Loose Matches      - MISSING
832         4.5 Locale-Dependent Ranges             - MISSING
833
834         [16] see UTR#10 Unicode Collation Algorithms
835         [17] have Unicode::Collate but not integrated to regexes
836
837 =back
838
839 =head2 Unicode Encodings
840
841 Unicode characters are assigned to I<code points>, which are abstract
842 numbers.  To use these numbers, various encodings are needed.
843
844 =over 4
845
846 =item *
847
848 UTF-8
849
850 UTF-8 is a variable-length (1 to 6 bytes, current character allocations
851 require 4 bytes), byte-order independent encoding. For ASCII (and we
852 really do mean 7-bit ASCII, not another 8-bit encoding), UTF-8 is
853 transparent.
854
855 The following table is from Unicode 3.2.
856
857  Code Points            1st Byte  2nd Byte  3rd Byte  4th Byte
858
859    U+0000..U+007F       00..7F
860    U+0080..U+07FF       C2..DF    80..BF
861    U+0800..U+0FFF       E0        A0..BF    80..BF
862    U+1000..U+CFFF       E1..EC    80..BF    80..BF
863    U+D000..U+D7FF       ED        80..9F    80..BF
864    U+D800..U+DFFF       ******* ill-formed *******
865    U+E000..U+FFFF       EE..EF    80..BF    80..BF
866   U+10000..U+3FFFF      F0        90..BF    80..BF    80..BF
867   U+40000..U+FFFFF      F1..F3    80..BF    80..BF    80..BF
868  U+100000..U+10FFFF     F4        80..8F    80..BF    80..BF
869
870 Note the C<A0..BF> in C<U+0800..U+0FFF>, the C<80..9F> in
871 C<U+D000...U+D7FF>, the C<90..B>F in C<U+10000..U+3FFFF>, and the
872 C<80...8F> in C<U+100000..U+10FFFF>.  The "gaps" are caused by legal
873 UTF-8 avoiding non-shortest encodings: it is technically possible to
874 UTF-8-encode a single code point in different ways, but that is
875 explicitly forbidden, and the shortest possible encoding should always
876 be used.  So that's what Perl does.
877
878 Another way to look at it is via bits:
879
880  Code Points                    1st Byte   2nd Byte  3rd Byte  4th Byte
881
882                     0aaaaaaa     0aaaaaaa
883             00000bbbbbaaaaaa     110bbbbb  10aaaaaa
884             ccccbbbbbbaaaaaa     1110cccc  10bbbbbb  10aaaaaa
885   00000dddccccccbbbbbbaaaaaa     11110ddd  10cccccc  10bbbbbb  10aaaaaa
886
887 As you can see, the continuation bytes all begin with C<10>, and the
888 leading bits of the start byte tell how many bytes the are in the
889 encoded character.
890
891 =item *
892
893 UTF-EBCDIC
894
895 Like UTF-8 but EBCDIC-safe, in the way that UTF-8 is ASCII-safe.
896
897 =item *
898
899 UTF-16, UTF-16BE, UTF16-LE, Surrogates, and BOMs (Byte Order Marks)
900
901 The followings items are mostly for reference and general Unicode
902 knowledge, Perl doesn't use these constructs internally.
903
904 UTF-16 is a 2 or 4 byte encoding.  The Unicode code points
905 C<U+0000..U+FFFF> are stored in a single 16-bit unit, and the code
906 points C<U+10000..U+10FFFF> in two 16-bit units.  The latter case is
907 using I<surrogates>, the first 16-bit unit being the I<high
908 surrogate>, and the second being the I<low surrogate>.
909
910 Surrogates are code points set aside to encode the C<U+10000..U+10FFFF>
911 range of Unicode code points in pairs of 16-bit units.  The I<high
912 surrogates> are the range C<U+D800..U+DBFF>, and the I<low surrogates>
913 are the range C<U+DC00..U+DFFF>.  The surrogate encoding is
914
915         $hi = ($uni - 0x10000) / 0x400 + 0xD800;
916         $lo = ($uni - 0x10000) % 0x400 + 0xDC00;
917
918 and the decoding is
919
920         $uni = 0x10000 + ($hi - 0xD800) * 0x400 + ($lo - 0xDC00);
921
922 If you try to generate surrogates (for example by using chr()), you
923 will get a warning if warnings are turned on, because those code
924 points are not valid for a Unicode character.
925
926 Because of the 16-bitness, UTF-16 is byte-order dependent.  UTF-16
927 itself can be used for in-memory computations, but if storage or
928 transfer is required either UTF-16BE (big-endian) or UTF-16LE
929 (little-endian) encodings must be chosen.
930
931 This introduces another problem: what if you just know that your data
932 is UTF-16, but you don't know which endianness?  Byte Order Marks, or
933 BOMs, are a solution to this.  A special character has been reserved
934 in Unicode to function as a byte order marker: the character with the
935 code point C<U+FEFF> is the BOM.
936
937 The trick is that if you read a BOM, you will know the byte order,
938 since if it was written on a big-endian platform, you will read the
939 bytes C<0xFE 0xFF>, but if it was written on a little-endian platform,
940 you will read the bytes C<0xFF 0xFE>.  (And if the originating platform
941 was writing in UTF-8, you will read the bytes C<0xEF 0xBB 0xBF>.)
942
943 The way this trick works is that the character with the code point
944 C<U+FFFE> is guaranteed not to be a valid Unicode character, so the
945 sequence of bytes C<0xFF 0xFE> is unambiguously "BOM, represented in
946 little-endian format" and cannot be C<U+FFFE>, represented in big-endian
947 format".
948
949 =item *
950
951 UTF-32, UTF-32BE, UTF32-LE
952
953 The UTF-32 family is pretty much like the UTF-16 family, expect that
954 the units are 32-bit, and therefore the surrogate scheme is not
955 needed.  The BOM signatures will be C<0x00 0x00 0xFE 0xFF> for BE and
956 C<0xFF 0xFE 0x00 0x00> for LE.
957
958 =item *
959
960 UCS-2, UCS-4
961
962 Encodings defined by the ISO 10646 standard.  UCS-2 is a 16-bit
963 encoding.  Unlike UTF-16, UCS-2 is not extensible beyond C<U+FFFF>,
964 because it does not use surrogates.  UCS-4 is a 32-bit encoding,
965 functionally identical to UTF-32.
966
967 =item *
968
969 UTF-7
970
971 A seven-bit safe (non-eight-bit) encoding, which is useful if the
972 transport or storage is not eight-bit safe.  Defined by RFC 2152.
973
974 =back
975
976 =head2 Security Implications of Unicode
977
978 =over 4
979
980 =item *
981
982 Malformed UTF-8
983
984 Unfortunately, the specification of UTF-8 leaves some room for
985 interpretation of how many bytes of encoded output one should generate
986 from one input Unicode character.  Strictly speaking, the shortest
987 possible sequence of UTF-8 bytes should be generated,
988 because otherwise there is potential for an input buffer overflow at
989 the receiving end of a UTF-8 connection.  Perl always generates the
990 shortest length UTF-8, and with warnings on Perl will warn about
991 non-shortest length UTF-8 along with other malformations, such as the
992 surrogates, which are not real Unicode code points.
993
994 =item *
995
996 Regular expressions behave slightly differently between byte data and
997 character (Unicode) data.  For example, the "word character" character
998 class C<\w> will work differently depending on if data is eight-bit bytes
999 or Unicode.
1000
1001 In the first case, the set of C<\w> characters is either small--the
1002 default set of alphabetic characters, digits, and the "_"--or, if you
1003 are using a locale (see L<perllocale>), the C<\w> might contain a few
1004 more letters according to your language and country.
1005
1006 In the second case, the C<\w> set of characters is much, much larger.
1007 Most importantly, even in the set of the first 256 characters, it will
1008 probably match different characters: unlike most locales, which are
1009 specific to a language and country pair, Unicode classifies all the
1010 characters that are letters I<somewhere> as C<\w>.  For example, your
1011 locale might not think that LATIN SMALL LETTER ETH is a letter (unless
1012 you happen to speak Icelandic), but Unicode does.
1013
1014 As discussed elsewhere, Perl has one foot (two hooves?) planted in
1015 each of two worlds: the old world of bytes and the new world of
1016 characters, upgrading from bytes to characters when necessary.
1017 If your legacy code does not explicitly use Unicode, no automatic
1018 switch-over to characters should happen.  Characters shouldn't get
1019 downgraded to bytes, either.  It is possible to accidentally mix bytes
1020 and characters, however (see L<perluniintro>), in which case C<\w> in
1021 regular expressions might start behaving differently.  Review your
1022 code.  Use warnings and the C<strict> pragma.
1023
1024 =back
1025
1026 =head2 Unicode in Perl on EBCDIC
1027
1028 The way Unicode is handled on EBCDIC platforms is still
1029 experimental.  On such platforms, references to UTF-8 encoding in this
1030 document and elsewhere should be read as meaning the UTF-EBCDIC
1031 specified in Unicode Technical Report 16, unless ASCII vs. EBCDIC issues
1032 are specifically discussed. There is no C<utfebcdic> pragma or
1033 ":utfebcdic" layer; rather, "utf8" and ":utf8" are reused to mean
1034 the platform's "natural" 8-bit encoding of Unicode. See L<perlebcdic>
1035 for more discussion of the issues.
1036
1037 =head2 Locales
1038
1039 Usually locale settings and Unicode do not affect each other, but
1040 there are a couple of exceptions:
1041
1042 =over 4
1043
1044 =item *
1045
1046 You can enable automatic UTF-8-ification of your standard file
1047 handles, default C<open()> layer, and C<@ARGV> by using either
1048 the C<-C> command line switch or the C<PERL_UNICODE> environment
1049 variable, see L<perlrun> for the documentation of the C<-C> switch.
1050
1051 =item *
1052
1053 Perl tries really hard to work both with Unicode and the old
1054 byte-oriented world. Most often this is nice, but sometimes Perl's
1055 straddling of the proverbial fence causes problems.
1056
1057 =back
1058
1059 =head2 When Unicode Does Not Happen
1060
1061 While Perl does have extensive ways to input and output in Unicode,
1062 and few other 'entry points' like the @ARGV which can be interpreted
1063 as Unicode (UTF-8), there still are many places where Unicode (in some
1064 encoding or another) could be given as arguments or received as
1065 results, or both, but it is not.
1066
1067 The following are such interfaces.  For all of these Perl currently
1068 (as of 5.8.1) simply assumes byte strings both as arguments and results.
1069
1070 One reason why Perl does not attempt to resolve the role of Unicode in
1071 this cases is that the answers are highly dependent on the operating
1072 system and the file system(s).  For example, whether filenames can be
1073 in Unicode, and in exactly what kind of encoding, is not exactly a
1074 portable concept.  Similarly for the qx and system: how well will the
1075 'command line interface' (and which of them?) handle Unicode?
1076
1077 =over 4
1078
1079 =item chmod, chmod, chown, chroot, exec, link, mkdir, rename, rmdir, stat, symlink, truncate, unlink, utime
1080
1081 =item %ENV
1082
1083 =item glob (aka the <*>)
1084
1085 =item open, opendir, sysopen
1086
1087 =item qx (aka the backtick operator), system
1088
1089 =item readdir, readlink
1090
1091 =back
1092
1093 =head2 Forcing Unicode in Perl (Or Unforcing Unicode in Perl)
1094
1095 Sometimes (see L</"When Unicode Does Not Happen">) there are
1096 situations where you simply need to force Perl to believe that a byte
1097 string is UTF-8, or vice versa.  The low-level calls
1098 utf8::upgrade($bytestring) and utf8::downgrade($utf8string) are
1099 the answers.
1100
1101 Do not use them without careful thought, though: Perl may easily get
1102 very confused, angry, or even crash, if you suddenly change the 'nature'
1103 of scalar like that.  Especially careful you have to be if you use the
1104 utf8::upgrade(): any random byte string is not valid UTF-8.
1105
1106 =head2 Using Unicode in XS
1107
1108 If you want to handle Perl Unicode in XS extensions, you may find the
1109 following C APIs useful.  See also L<perlguts/"Unicode Support"> for an
1110 explanation about Unicode at the XS level, and L<perlapi> for the API
1111 details.
1112
1113 =over 4
1114
1115 =item *
1116
1117 C<DO_UTF8(sv)> returns true if the C<UTF8> flag is on and the bytes
1118 pragma is not in effect.  C<SvUTF8(sv)> returns true is the C<UTF8>
1119 flag is on; the bytes pragma is ignored.  The C<UTF8> flag being on
1120 does B<not> mean that there are any characters of code points greater
1121 than 255 (or 127) in the scalar or that there are even any characters
1122 in the scalar.  What the C<UTF8> flag means is that the sequence of
1123 octets in the representation of the scalar is the sequence of UTF-8
1124 encoded code points of the characters of a string.  The C<UTF8> flag
1125 being off means that each octet in this representation encodes a
1126 single character with code point 0..255 within the string.  Perl's
1127 Unicode model is not to use UTF-8 until it is absolutely necessary.
1128
1129 =item *
1130
1131 C<uvuni_to_utf8(buf, chr>) writes a Unicode character code point into
1132 a buffer encoding the code point as UTF-8, and returns a pointer
1133 pointing after the UTF-8 bytes.
1134
1135 =item *
1136
1137 C<utf8_to_uvuni(buf, lenp)> reads UTF-8 encoded bytes from a buffer and
1138 returns the Unicode character code point and, optionally, the length of
1139 the UTF-8 byte sequence.
1140
1141 =item *
1142
1143 C<utf8_length(start, end)> returns the length of the UTF-8 encoded buffer
1144 in characters.  C<sv_len_utf8(sv)> returns the length of the UTF-8 encoded
1145 scalar.
1146
1147 =item *
1148
1149 C<sv_utf8_upgrade(sv)> converts the string of the scalar to its UTF-8
1150 encoded form.  C<sv_utf8_downgrade(sv)> does the opposite, if
1151 possible.  C<sv_utf8_encode(sv)> is like sv_utf8_upgrade except that
1152 it does not set the C<UTF8> flag.  C<sv_utf8_decode()> does the
1153 opposite of C<sv_utf8_encode()>.  Note that none of these are to be
1154 used as general-purpose encoding or decoding interfaces: C<use Encode>
1155 for that.  C<sv_utf8_upgrade()> is affected by the encoding pragma
1156 but C<sv_utf8_downgrade()> is not (since the encoding pragma is
1157 designed to be a one-way street).
1158
1159 =item *
1160
1161 C<is_utf8_char(s)> returns true if the pointer points to a valid UTF-8
1162 character.
1163
1164 =item *
1165
1166 C<is_utf8_string(buf, len)> returns true if C<len> bytes of the buffer
1167 are valid UTF-8.
1168
1169 =item *
1170
1171 C<UTF8SKIP(buf)> will return the number of bytes in the UTF-8 encoded
1172 character in the buffer.  C<UNISKIP(chr)> will return the number of bytes
1173 required to UTF-8-encode the Unicode character code point.  C<UTF8SKIP()>
1174 is useful for example for iterating over the characters of a UTF-8
1175 encoded buffer; C<UNISKIP()> is useful, for example, in computing
1176 the size required for a UTF-8 encoded buffer.
1177
1178 =item *
1179
1180 C<utf8_distance(a, b)> will tell the distance in characters between the
1181 two pointers pointing to the same UTF-8 encoded buffer.
1182
1183 =item *
1184
1185 C<utf8_hop(s, off)> will return a pointer to an UTF-8 encoded buffer
1186 that is C<off> (positive or negative) Unicode characters displaced
1187 from the UTF-8 buffer C<s>.  Be careful not to overstep the buffer:
1188 C<utf8_hop()> will merrily run off the end or the beginning of the
1189 buffer if told to do so.
1190
1191 =item *
1192
1193 C<pv_uni_display(dsv, spv, len, pvlim, flags)> and
1194 C<sv_uni_display(dsv, ssv, pvlim, flags)> are useful for debugging the
1195 output of Unicode strings and scalars.  By default they are useful
1196 only for debugging--they display B<all> characters as hexadecimal code
1197 points--but with the flags C<UNI_DISPLAY_ISPRINT>,
1198 C<UNI_DISPLAY_BACKSLASH>, and C<UNI_DISPLAY_QQ> you can make the
1199 output more readable.
1200
1201 =item *
1202
1203 C<ibcmp_utf8(s1, pe1, u1, l1, u1, s2, pe2, l2, u2)> can be used to
1204 compare two strings case-insensitively in Unicode.  For case-sensitive
1205 comparisons you can just use C<memEQ()> and C<memNE()> as usual.
1206
1207 =back
1208
1209 For more information, see L<perlapi>, and F<utf8.c> and F<utf8.h>
1210 in the Perl source code distribution.
1211
1212 =head1 BUGS
1213
1214 =head2 Interaction with Locales
1215
1216 Use of locales with Unicode data may lead to odd results.  Currently,
1217 Perl attempts to attach 8-bit locale info to characters in the range
1218 0..255, but this technique is demonstrably incorrect for locales that
1219 use characters above that range when mapped into Unicode.  Perl's
1220 Unicode support will also tend to run slower.  Use of locales with
1221 Unicode is discouraged.
1222
1223 =head2 Interaction with Extensions
1224
1225 When Perl exchanges data with an extension, the extension should be
1226 able to understand the UTF-8 flag and act accordingly. If the
1227 extension doesn't know about the flag, it's likely that the extension
1228 will return incorrectly-flagged data.
1229
1230 So if you're working with Unicode data, consult the documentation of
1231 every module you're using if there are any issues with Unicode data
1232 exchange. If the documentation does not talk about Unicode at all,
1233 suspect the worst and probably look at the source to learn how the
1234 module is implemented. Modules written completely in Perl shouldn't
1235 cause problems. Modules that directly or indirectly access code written
1236 in other programming languages are at risk.
1237
1238 For affected functions, the simple strategy to avoid data corruption is
1239 to always make the encoding of the exchanged data explicit. Choose an
1240 encoding that you know the extension can handle. Convert arguments passed
1241 to the extensions to that encoding and convert results back from that
1242 encoding. Write wrapper functions that do the conversions for you, so
1243 you can later change the functions when the extension catches up.
1244
1245 To provide an example, let's say the popular Foo::Bar::escape_html
1246 function doesn't deal with Unicode data yet. The wrapper function
1247 would convert the argument to raw UTF-8 and convert the result back to
1248 Perl's internal representation like so:
1249
1250     sub my_escape_html ($) {
1251       my($what) = shift;
1252       return unless defined $what;
1253       Encode::decode_utf8(Foo::Bar::escape_html(Encode::encode_utf8($what)));
1254     }
1255
1256 Sometimes, when the extension does not convert data but just stores
1257 and retrieves them, you will be in a position to use the otherwise
1258 dangerous Encode::_utf8_on() function. Let's say the popular
1259 C<Foo::Bar> extension, written in C, provides a C<param> method that
1260 lets you store and retrieve data according to these prototypes:
1261
1262     $self->param($name, $value);            # set a scalar
1263     $value = $self->param($name);           # retrieve a scalar
1264
1265 If it does not yet provide support for any encoding, one could write a
1266 derived class with such a C<param> method:
1267
1268     sub param {
1269       my($self,$name,$value) = @_;
1270       utf8::upgrade($name);     # make sure it is UTF-8 encoded
1271       if (defined $value)
1272         utf8::upgrade($value);  # make sure it is UTF-8 encoded
1273         return $self->SUPER::param($name,$value);
1274       } else {
1275         my $ret = $self->SUPER::param($name);
1276         Encode::_utf8_on($ret); # we know, it is UTF-8 encoded
1277         return $ret;
1278       }
1279     }
1280
1281 Some extensions provide filters on data entry/exit points, such as
1282 DB_File::filter_store_key and family. Look out for such filters in
1283 the documentation of your extensions, they can make the transition to
1284 Unicode data much easier.
1285
1286 =head2 Speed
1287
1288 Some functions are slower when working on UTF-8 encoded strings than
1289 on byte encoded strings.  All functions that need to hop over
1290 characters such as length(), substr() or index(), or matching regular
1291 expressions can work B<much> faster when the underlying data are
1292 byte-encoded.
1293
1294 In Perl 5.8.0 the slowness was often quite spectacular; in Perl 5.8.1
1295 a caching scheme was introduced which will hopefully make the slowness
1296 somewhat less spectacular.  Operations with UTF-8 encoded strings are
1297 still slower, though.
1298
1299 =head2 Porting code from perl-5.6.X
1300
1301 Perl 5.8 has a different Unicode model from 5.6. In 5.6 the programmer
1302 was required to use the C<utf8> pragma to declare that a given scope
1303 expected to deal with Unicode data and had to make sure that only
1304 Unicode data were reaching that scope. If you have code that is
1305 working with 5.6, you will need some of the following adjustments to
1306 your code. The examples are written such that the code will continue
1307 to work under 5.6, so you should be safe to try them out.
1308
1309 =over 4
1310
1311 =item *
1312
1313 A filehandle that should read or write UTF-8
1314
1315   if ($] > 5.007) {
1316     binmode $fh, ":utf8";
1317   }
1318
1319 =item *
1320
1321 A scalar that is going to be passed to some extension
1322
1323 Be it Compress::Zlib, Apache::Request or any extension that has no
1324 mention of Unicode in the manpage, you need to make sure that the
1325 UTF-8 flag is stripped off. Note that at the time of this writing
1326 (October 2002) the mentioned modules are not UTF-8-aware. Please
1327 check the documentation to verify if this is still true.
1328
1329   if ($] > 5.007) {
1330     require Encode;
1331     $val = Encode::encode_utf8($val); # make octets
1332   }
1333
1334 =item *
1335
1336 A scalar we got back from an extension
1337
1338 If you believe the scalar comes back as UTF-8, you will most likely
1339 want the UTF-8 flag restored:
1340
1341   if ($] > 5.007) {
1342     require Encode;
1343     $val = Encode::decode_utf8($val);
1344   }
1345
1346 =item *
1347
1348 Same thing, if you are really sure it is UTF-8
1349
1350   if ($] > 5.007) {
1351     require Encode;
1352     Encode::_utf8_on($val);
1353   }
1354
1355 =item *
1356
1357 A wrapper for fetchrow_array and fetchrow_hashref
1358
1359 When the database contains only UTF-8, a wrapper function or method is
1360 a convenient way to replace all your fetchrow_array and
1361 fetchrow_hashref calls. A wrapper function will also make it easier to
1362 adapt to future enhancements in your database driver. Note that at the
1363 time of this writing (October 2002), the DBI has no standardized way
1364 to deal with UTF-8 data. Please check the documentation to verify if
1365 that is still true.
1366
1367   sub fetchrow {
1368     my($self, $sth, $what) = @_; # $what is one of fetchrow_{array,hashref}
1369     if ($] < 5.007) {
1370       return $sth->$what;
1371     } else {
1372       require Encode;
1373       if (wantarray) {
1374         my @arr = $sth->$what;
1375         for (@arr) {
1376           defined && /[^\000-\177]/ && Encode::_utf8_on($_);
1377         }
1378         return @arr;
1379       } else {
1380         my $ret = $sth->$what;
1381         if (ref $ret) {
1382           for my $k (keys %$ret) {
1383             defined && /[^\000-\177]/ && Encode::_utf8_on($_) for $ret->{$k};
1384           }
1385           return $ret;
1386         } else {
1387           defined && /[^\000-\177]/ && Encode::_utf8_on($_) for $ret;
1388           return $ret;
1389         }
1390       }
1391     }
1392   }
1393
1394
1395 =item *
1396
1397 A large scalar that you know can only contain ASCII
1398
1399 Scalars that contain only ASCII and are marked as UTF-8 are sometimes
1400 a drag to your program. If you recognize such a situation, just remove
1401 the UTF-8 flag:
1402
1403   utf8::downgrade($val) if $] > 5.007;
1404
1405 =back
1406
1407 =head1 SEE ALSO
1408
1409 L<perluniintro>, L<encoding>, L<Encode>, L<open>, L<utf8>, L<bytes>,
1410 L<perlretut>, L<perlvar/"${^UNICODE}">
1411
1412 =cut