This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
bbf87e462b715709c53a372635e81f293b0aec69
[perl5.git] / lib / Unicode / UCD.pm
1 package Unicode::UCD;
2
3 use strict;
4 use warnings;
5 no warnings 'surrogate';    # surrogates can be inputs to this
6 use charnames ();
7
8 our $VERSION = '0.62';
9
10 require Exporter;
11
12 our @ISA = qw(Exporter);
13
14 our @EXPORT_OK = qw(charinfo
15                     charblock charscript
16                     charblocks charscripts
17                     charinrange
18                     charprop
19                     charprops_all
20                     general_categories bidi_types
21                     compexcl
22                     casefold all_casefolds casespec
23                     namedseq
24                     num
25                     prop_aliases
26                     prop_value_aliases
27                     prop_values
28                     prop_invlist
29                     prop_invmap
30                     search_invlist
31                     MAX_CP
32                 );
33
34 use Carp;
35
36 sub IS_ASCII_PLATFORM { ord("A") == 65 }
37
38 =head1 NAME
39
40 Unicode::UCD - Unicode character database
41
42 =head1 SYNOPSIS
43
44     use Unicode::UCD 'charinfo';
45     my $charinfo   = charinfo($codepoint);
46
47     use Unicode::UCD 'charprop';
48     my $value  = charprop($codepoint, $property);
49
50     use Unicode::UCD 'charprops_all';
51     my $all_values_hash_ref = charprops_all($codepoint);
52
53     use Unicode::UCD 'casefold';
54     my $casefold = casefold($codepoint);
55
56     use Unicode::UCD 'all_casefolds';
57     my $all_casefolds_ref = all_casefolds();
58
59     use Unicode::UCD 'casespec';
60     my $casespec = casespec($codepoint);
61
62     use Unicode::UCD 'charblock';
63     my $charblock  = charblock($codepoint);
64
65     use Unicode::UCD 'charscript';
66     my $charscript = charscript($codepoint);
67
68     use Unicode::UCD 'charblocks';
69     my $charblocks = charblocks();
70
71     use Unicode::UCD 'charscripts';
72     my $charscripts = charscripts();
73
74     use Unicode::UCD qw(charscript charinrange);
75     my $range = charscript($script);
76     print "looks like $script\n" if charinrange($range, $codepoint);
77
78     use Unicode::UCD qw(general_categories bidi_types);
79     my $categories = general_categories();
80     my $types = bidi_types();
81
82     use Unicode::UCD 'prop_aliases';
83     my @space_names = prop_aliases("space");
84
85     use Unicode::UCD 'prop_value_aliases';
86     my @gc_punct_names = prop_value_aliases("Gc", "Punct");
87
88     use Unicode::UCD 'prop_values';
89     my @all_EA_short_names = prop_values("East_Asian_Width");
90
91     use Unicode::UCD 'prop_invlist';
92     my @puncts = prop_invlist("gc=punctuation");
93
94     use Unicode::UCD 'prop_invmap';
95     my ($list_ref, $map_ref, $format, $missing)
96                                       = prop_invmap("General Category");
97
98     use Unicode::UCD 'search_invlist';
99     my $index = search_invlist(\@invlist, $code_point);
100
101     use Unicode::UCD 'compexcl';
102     my $compexcl = compexcl($codepoint);
103
104     use Unicode::UCD 'namedseq';
105     my $namedseq = namedseq($named_sequence_name);
106
107     my $unicode_version = Unicode::UCD::UnicodeVersion();
108
109     my $convert_to_numeric =
110               Unicode::UCD::num("\N{RUMI DIGIT ONE}\N{RUMI DIGIT TWO}");
111
112 =head1 DESCRIPTION
113
114 The Unicode::UCD module offers a series of functions that
115 provide a simple interface to the Unicode
116 Character Database.
117
118 =head2 code point argument
119
120 Some of the functions are called with a I<code point argument>, which is either
121 a decimal or a hexadecimal scalar designating a code point in the platform's
122 native character set (extended to Unicode), or a string containing C<U+>
123 followed by hexadecimals
124 designating a Unicode code point.  A leading 0 will force a hexadecimal
125 interpretation, as will a hexadecimal digit that isn't a decimal digit.
126
127 Examples:
128
129     223     # Decimal 223 in native character set
130     0223    # Hexadecimal 223, native (= 547 decimal)
131     0xDF    # Hexadecimal DF, native (= 223 decimal
132     'U+DF'  # Hexadecimal DF, in Unicode's character set
133                               (= LATIN SMALL LETTER SHARP S)
134
135 Note that the largest code point in Unicode is U+10FFFF.
136
137 =cut
138
139 my $BLOCKSFH;
140 my $VERSIONFH;
141 my $CASEFOLDFH;
142 my $CASESPECFH;
143 my $NAMEDSEQFH;
144 my $v_unicode_version;  # v-string.
145
146 sub openunicode {
147     my ($rfh, @path) = @_;
148     my $f;
149     unless (defined $$rfh) {
150         for my $d (@INC) {
151             use File::Spec;
152             $f = File::Spec->catfile($d, "unicore", @path);
153             last if open($$rfh, $f);
154             undef $f;
155         }
156         croak __PACKAGE__, ": failed to find ",
157               File::Spec->catfile(@path), " in @INC"
158             unless defined $f;
159     }
160     return $f;
161 }
162
163 sub _dclone ($) {   # Use Storable::dclone if available; otherwise emulate it.
164
165     use if defined &DynaLoader::boot_DynaLoader, Storable => qw(dclone);
166
167     return dclone(shift) if defined &dclone;
168
169     my $arg = shift;
170     my $type = ref $arg;
171     return $arg unless $type;   # No deep cloning needed for scalars
172
173     if ($type eq 'ARRAY') {
174         my @return;
175         foreach my $element (@$arg) {
176             push @return, &_dclone($element);
177         }
178         return \@return;
179     }
180     elsif ($type eq 'HASH') {
181         my %return;
182         foreach my $key (keys %$arg) {
183             $return{$key} = &_dclone($arg->{$key});
184         }
185         return \%return;
186     }
187     else {
188         croak "_dclone can't handle " . $type;
189     }
190 }
191
192 =head2 B<charinfo()>
193
194     use Unicode::UCD 'charinfo';
195
196     my $charinfo = charinfo(0x41);
197
198 This returns information about the input L</code point argument>
199 as a reference to a hash of fields as defined by the Unicode
200 standard.  If the L</code point argument> is not assigned in the standard
201 (i.e., has the general category C<Cn> meaning C<Unassigned>)
202 or is a non-character (meaning it is guaranteed to never be assigned in
203 the standard),
204 C<undef> is returned.
205
206 Fields that aren't applicable to the particular code point argument exist in the
207 returned hash, and are empty. 
208
209 For results that are less "raw" than this function returns, or to get the values for
210 any property, not just the few covered by this function, use the
211 L</charprop()> function.
212
213 The keys in the hash with the meanings of their values are:
214
215 =over
216
217 =item B<code>
218
219 the input native L</code point argument> expressed in hexadecimal, with
220 leading zeros
221 added if necessary to make it contain at least four hexdigits
222
223 =item B<name>
224
225 name of I<code>, all IN UPPER CASE.
226 Some control-type code points do not have names.
227 This field will be empty for C<Surrogate> and C<Private Use> code points,
228 and for the others without a name,
229 it will contain a description enclosed in angle brackets, like
230 C<E<lt>controlE<gt>>.
231
232
233 =item B<category>
234
235 The short name of the general category of I<code>.
236 This will match one of the keys in the hash returned by L</general_categories()>.
237
238 The L</prop_value_aliases()> function can be used to get all the synonyms
239 of the category name.
240
241 =item B<combining>
242
243 the combining class number for I<code> used in the Canonical Ordering Algorithm.
244 For Unicode 5.1, this is described in Section 3.11 C<Canonical Ordering Behavior>
245 available at
246 L<http://www.unicode.org/versions/Unicode5.1.0/>
247
248 The L</prop_value_aliases()> function can be used to get all the synonyms
249 of the combining class number.
250
251 =item B<bidi>
252
253 bidirectional type of I<code>.
254 This will match one of the keys in the hash returned by L</bidi_types()>.
255
256 The L</prop_value_aliases()> function can be used to get all the synonyms
257 of the bidi type name.
258
259 =item B<decomposition>
260
261 is empty if I<code> has no decomposition; or is one or more codes
262 (separated by spaces) that, taken in order, represent a decomposition for
263 I<code>.  Each has at least four hexdigits.
264 The codes may be preceded by a word enclosed in angle brackets, then a space,
265 like C<E<lt>compatE<gt> >, giving the type of decomposition
266
267 This decomposition may be an intermediate one whose components are also
268 decomposable.  Use L<Unicode::Normalize> to get the final decomposition in one
269 step.
270
271 =item B<decimal>
272
273 if I<code> represents a decimal digit this is its integer numeric value
274
275 =item B<digit>
276
277 if I<code> represents some other digit-like number, this is its integer
278 numeric value
279
280 =item B<numeric>
281
282 if I<code> represents a whole or rational number, this is its numeric value.
283 Rational values are expressed as a string like C<1/4>.
284
285 =item B<mirrored>
286
287 C<Y> or C<N> designating if I<code> is mirrored in bidirectional text
288
289 =item B<unicode10>
290
291 name of I<code> in the Unicode 1.0 standard if one
292 existed for this code point and is different from the current name
293
294 =item B<comment>
295
296 As of Unicode 6.0, this is always empty.
297
298 =item B<upper>
299
300 is, if non-empty, the uppercase mapping for I<code> expressed as at least four
301 hexdigits.  This indicates that the full uppercase mapping is a single
302 character, and is identical to the simple (single-character only) mapping.
303 When this field is empty, it means that the simple uppercase mapping is
304 I<code> itself; you'll need some other means, (like L</charprop()> or
305 L</casespec()> to get the full mapping.
306
307 =item B<lower>
308
309 is, if non-empty, the lowercase mapping for I<code> expressed as at least four
310 hexdigits.  This indicates that the full lowercase mapping is a single
311 character, and is identical to the simple (single-character only) mapping.
312 When this field is empty, it means that the simple lowercase mapping is
313 I<code> itself; you'll need some other means, (like L</charprop()> or
314 L</casespec()> to get the full mapping.
315
316 =item B<title>
317
318 is, if non-empty, the titlecase mapping for I<code> expressed as at least four
319 hexdigits.  This indicates that the full titlecase mapping is a single
320 character, and is identical to the simple (single-character only) mapping.
321 When this field is empty, it means that the simple titlecase mapping is
322 I<code> itself; you'll need some other means, (like L</charprop()> or
323 L</casespec()> to get the full mapping.
324
325 =item B<block>
326
327 the block I<code> belongs to (used in C<\p{Blk=...}>).
328 The L</prop_value_aliases()> function can be used to get all the synonyms
329 of the block name.
330
331 See L</Blocks versus Scripts>.
332
333 =item B<script>
334
335 the script I<code> belongs to.
336 The L</prop_value_aliases()> function can be used to get all the synonyms
337 of the script name.
338
339 See L</Blocks versus Scripts>.
340
341 =back
342
343 Note that you cannot do (de)composition and casing based solely on the
344 I<decomposition>, I<combining>, I<lower>, I<upper>, and I<title> fields; you
345 will need also the L</casespec()> function and the C<Composition_Exclusion>
346 property.  (Or you could just use the L<lc()|perlfunc/lc>,
347 L<uc()|perlfunc/uc>, and L<ucfirst()|perlfunc/ucfirst> functions, and the
348 L<Unicode::Normalize> module.)
349
350 =cut
351
352 # NB: This function is nearly duplicated in charnames.pm
353 sub _getcode {
354     my $arg = shift;
355
356     if ($arg =~ /^[1-9]\d*$/) {
357         return $arg;
358     }
359     elsif ($arg =~ /^(?:0[xX])?([[:xdigit:]]+)$/) {
360         return CORE::hex($1);
361     }
362     elsif ($arg =~ /^[Uu]\+([[:xdigit:]]+)$/) { # Is of form U+0000, means
363                                                 # wants the Unicode code
364                                                 # point, not the native one
365         my $decimal = CORE::hex($1);
366         return $decimal if IS_ASCII_PLATFORM;
367         return utf8::unicode_to_native($decimal);
368     }
369
370     return;
371 }
372
373 # Populated by _num.  Converts real number back to input rational
374 my %real_to_rational;
375
376 # To store the contents of files found on disk.
377 my @BIDIS;
378 my @CATEGORIES;
379 my @DECOMPOSITIONS;
380 my @NUMERIC_TYPES;
381 my %SIMPLE_LOWER;
382 my %SIMPLE_TITLE;
383 my %SIMPLE_UPPER;
384 my %UNICODE_1_NAMES;
385 my %ISO_COMMENT;
386
387 sub charinfo {
388
389     # This function has traditionally mimicked what is in UnicodeData.txt,
390     # warts and all.  This is a re-write that avoids UnicodeData.txt so that
391     # it can be removed to save disk space.  Instead, this assembles
392     # information gotten by other methods that get data from various other
393     # files.  It uses charnames to get the character name; and various
394     # mktables tables.
395
396     use feature 'unicode_strings';
397
398     # Will fail if called under minitest
399     use if defined &DynaLoader::boot_DynaLoader, "Unicode::Normalize" => qw(getCombinClass NFD);
400
401     my $arg  = shift;
402     my $code = _getcode($arg);
403     croak __PACKAGE__, "::charinfo: unknown code '$arg'" unless defined $code;
404
405     # Non-unicode implies undef.
406     return if $code > 0x10FFFF;
407
408     my %prop;
409     my $char = chr($code);
410
411     @CATEGORIES =_read_table("To/Gc.pl") unless @CATEGORIES;
412     $prop{'category'} = _search(\@CATEGORIES, 0, $#CATEGORIES, $code)
413                         // $utf8::SwashInfo{'ToGc'}{'missing'};
414     # Return undef if category value is 'Unassigned' or one of its synonyms 
415     return if grep { lc $_ eq 'unassigned' }
416                                     prop_value_aliases('Gc', $prop{'category'});
417
418     $prop{'code'} = sprintf "%04X", $code;
419     $prop{'name'} = ($char =~ /\p{Cntrl}/) ? '<control>'
420                                            : (charnames::viacode($code) // "");
421
422     $prop{'combining'} = getCombinClass($code);
423
424     @BIDIS =_read_table("To/Bc.pl") unless @BIDIS;
425     $prop{'bidi'} = _search(\@BIDIS, 0, $#BIDIS, $code)
426                     // $utf8::SwashInfo{'ToBc'}{'missing'};
427
428     # For most code points, we can just read in "unicore/Decomposition.pl", as
429     # its contents are exactly what should be output.  But that file doesn't
430     # contain the data for the Hangul syllable decompositions, which can be
431     # algorithmically computed, and NFD() does that, so we call NFD() for
432     # those.  We can't use NFD() for everything, as it does a complete
433     # recursive decomposition, and what this function has always done is to
434     # return what's in UnicodeData.txt which doesn't show that recursiveness.
435     # Fortunately, the NFD() of the Hanguls doesn't have any recursion
436     # issues.
437     # Having no decomposition implies an empty field; otherwise, all but
438     # "Canonical" imply a compatible decomposition, and the type is prefixed
439     # to that, as it is in UnicodeData.txt
440     UnicodeVersion() unless defined $v_unicode_version;
441     if ($v_unicode_version ge v2.0.0 && $char =~ /\p{Block=Hangul_Syllables}/) {
442         # The code points of the decomposition are output in standard Unicode
443         # hex format, separated by blanks.
444         $prop{'decomposition'} = join " ", map { sprintf("%04X", $_)}
445                                            unpack "U*", NFD($char);
446     }
447     else {
448         @DECOMPOSITIONS = _read_table("Decomposition.pl")
449                           unless @DECOMPOSITIONS;
450         $prop{'decomposition'} = _search(\@DECOMPOSITIONS, 0, $#DECOMPOSITIONS,
451                                                                 $code) // "";
452     }
453
454     # Can use num() to get the numeric values, if any.
455     if (! defined (my $value = num($char))) {
456         $prop{'decimal'} = $prop{'digit'} = $prop{'numeric'} = "";
457     }
458     else {
459         if ($char =~ /\d/) {
460             $prop{'decimal'} = $prop{'digit'} = $prop{'numeric'} = $value;
461         }
462         else {
463
464             # For non-decimal-digits, we have to read in the Numeric type
465             # to distinguish them.  It is not just a matter of integer vs.
466             # rational, as some whole number values are not considered digits,
467             # e.g., TAMIL NUMBER TEN.
468             $prop{'decimal'} = "";
469
470             @NUMERIC_TYPES =_read_table("To/Nt.pl") unless @NUMERIC_TYPES;
471             if ((_search(\@NUMERIC_TYPES, 0, $#NUMERIC_TYPES, $code) // "")
472                 eq 'Digit')
473             {
474                 $prop{'digit'} = $prop{'numeric'} = $value;
475             }
476             else {
477                 $prop{'digit'} = "";
478                 $prop{'numeric'} = $real_to_rational{$value} // $value;
479             }
480         }
481     }
482
483     $prop{'mirrored'} = ($char =~ /\p{Bidi_Mirrored}/) ? 'Y' : 'N';
484
485     %UNICODE_1_NAMES =_read_table("To/Na1.pl", "use_hash") unless %UNICODE_1_NAMES;
486     $prop{'unicode10'} = $UNICODE_1_NAMES{$code} // "";
487
488     UnicodeVersion() unless defined $v_unicode_version;
489     if ($v_unicode_version ge v6.0.0) {
490         $prop{'comment'} = "";
491     }
492     else {
493         %ISO_COMMENT = _read_table("To/Isc.pl", "use_hash") unless %ISO_COMMENT;
494         $prop{'comment'} = (defined $ISO_COMMENT{$code})
495                            ? $ISO_COMMENT{$code}
496                            : "";
497     }
498
499     %SIMPLE_UPPER = _read_table("To/Uc.pl", "use_hash") unless %SIMPLE_UPPER;
500     $prop{'upper'} = (defined $SIMPLE_UPPER{$code})
501                      ? sprintf("%04X", $SIMPLE_UPPER{$code})
502                      : "";
503
504     %SIMPLE_LOWER = _read_table("To/Lc.pl", "use_hash") unless %SIMPLE_LOWER;
505     $prop{'lower'} = (defined $SIMPLE_LOWER{$code})
506                      ? sprintf("%04X", $SIMPLE_LOWER{$code})
507                      : "";
508
509     %SIMPLE_TITLE = _read_table("To/Tc.pl", "use_hash") unless %SIMPLE_TITLE;
510     $prop{'title'} = (defined $SIMPLE_TITLE{$code})
511                      ? sprintf("%04X", $SIMPLE_TITLE{$code})
512                      : "";
513
514     $prop{block}  = charblock($code);
515     $prop{script} = charscript($code);
516     return \%prop;
517 }
518
519 sub _search { # Binary search in a [[lo,hi,prop],[...],...] table.
520     my ($table, $lo, $hi, $code) = @_;
521
522     return if $lo > $hi;
523
524     my $mid = int(($lo+$hi) / 2);
525
526     if ($table->[$mid]->[0] < $code) {
527         if ($table->[$mid]->[1] >= $code) {
528             return $table->[$mid]->[2];
529         } else {
530             _search($table, $mid + 1, $hi, $code);
531         }
532     } elsif ($table->[$mid]->[0] > $code) {
533         _search($table, $lo, $mid - 1, $code);
534     } else {
535         return $table->[$mid]->[2];
536     }
537 }
538
539 sub _read_table ($;$) {
540
541     # Returns the contents of the mktables generated table file located at $1
542     # in the form of either an array of arrays or a hash, depending on if the
543     # optional second parameter is true (for hash return) or not.  In the case
544     # of a hash return, each key is a code point, and its corresponding value
545     # is what the table gives as the code point's corresponding value.  In the
546     # case of an array return, each outer array denotes a range with [0] the
547     # start point of that range; [1] the end point; and [2] the value that
548     # every code point in the range has.  The hash return is useful for fast
549     # lookup when the table contains only single code point ranges.  The array
550     # return takes much less memory when there are large ranges.
551     #
552     # This function has the side effect of setting
553     # $utf8::SwashInfo{$property}{'format'} to be the mktables format of the
554     #                                       table; and
555     # $utf8::SwashInfo{$property}{'missing'} to be the value for all entries
556     #                                        not listed in the table.
557     # where $property is the Unicode property name, preceded by 'To' for map
558     # properties., e.g., 'ToSc'.
559     #
560     # Table entries look like one of:
561     # 0000      0040    Common  # [65]
562     # 00AA              Latin
563
564     my $table = shift;
565     my $return_hash = shift;
566     $return_hash = 0 unless defined $return_hash;
567     my @return;
568     my %return;
569     local $_;
570     my $list = do "unicore/$table";
571
572     # Look up if this property requires adjustments, which we do below if it
573     # does.
574     require "unicore/Heavy.pl";
575     my $property = $table =~ s/\.pl//r;
576     $property = $utf8::file_to_swash_name{$property};
577     my $to_adjust = defined $property
578                     && $utf8::SwashInfo{$property}{'format'} =~ / ^ a /x;
579
580     for (split /^/m, $list) {
581         my ($start, $end, $value) = / ^ (.+?) \t (.*?) \t (.+?)
582                                         \s* ( \# .* )?  # Optional comment
583                                         $ /x;
584         my $decimal_start = hex $start;
585         my $decimal_end = ($end eq "") ? $decimal_start : hex $end;
586         $value = hex $value if $to_adjust
587                                && $utf8::SwashInfo{$property}{'format'} eq 'ax';
588         if ($return_hash) {
589             foreach my $i ($decimal_start .. $decimal_end) {
590                 $return{$i} = ($to_adjust)
591                               ? $value + $i - $decimal_start
592                               : $value;
593             }
594         }
595         elsif (! $to_adjust
596                && @return
597                && $return[-1][1] == $decimal_start - 1
598                && $return[-1][2] eq $value)
599         {
600             # If this is merely extending the previous range, do just that.
601             $return[-1]->[1] = $decimal_end;
602         }
603         else {
604             push @return, [ $decimal_start, $decimal_end, $value ];
605         }
606     }
607     return ($return_hash) ? %return : @return;
608 }
609
610 sub charinrange {
611     my ($range, $arg) = @_;
612     my $code = _getcode($arg);
613     croak __PACKAGE__, "::charinrange: unknown code '$arg'"
614         unless defined $code;
615     _search($range, 0, $#$range, $code);
616 }
617
618 =head2 B<charprop()>
619
620     use Unicode::UCD 'charprop';
621
622     print charprop(0x41, "Gc"), "\n";
623     print charprop(0x61, "General_Category"), "\n";
624
625   prints
626     Lu
627     Ll
628
629 This returns the value of the Unicode property given by the second parameter
630 for the  L</code point argument> given by the first.
631
632 The passed-in property may be specified as any of the synonyms returned by
633 L</prop_aliases()>.
634
635 The return value is always a scalar, either a string or a number.  For
636 properties where there are synonyms for the values, the synonym returned by
637 this function is the longest, most descriptive form, the one returned by
638 L</prop_value_aliases()> when called in a scalar context.  Of course, you can
639 call L</prop_value_aliases()> on the result to get other synonyms.
640
641 The return values are more "cooked" than the L</charinfo()> ones.  For
642 example, the C<"uc"> property value is the actual string containing the full
643 uppercase mapping of the input code point.  You have to go to extra trouble
644 with C<charinfo> to get this value from its C<upper> hash element when the
645 full mapping differs from the simple one.
646
647 Special note should be made of the return values for a few properties:
648
649 =over
650
651 =item Block
652
653 The value returned is the new-style (see L</Old-style versus new-style block
654 names>).
655
656 =item Decomposition_Mapping
657
658 Like L</charinfo()>, the result may be an intermediate decomposition whose
659 components are also decomposable.  Use L<Unicode::Normalize> to get the final
660 decomposition in one step.
661
662 Unlike L</charinfo()>, this does not include the decomposition type.  Use the
663 C<Decomposition_Type> property to get that.
664
665 =item Name_Alias
666
667 If the input code point's name has more than one synonym, they are returned
668 joined into a single comma-separated string.
669
670 =item Numeric_Value
671
672 If the result is a fraction, it is converted into a floating point number to
673 the accuracy of your platform.
674
675 =item Script_Extensions
676
677 If the result is multiple script names, they are returned joined into a single
678 comma-separated string.
679
680 =back
681
682 When called with a property that is a Perl extension that isn't expressible in
683 a compound form, this function currently returns C<undef>, as the only two
684 possible values are I<true> or I<false> (1 or 0 I suppose).  This behavior may
685 change in the future, so don't write code that relies on it.  C<Present_In> is
686 a Perl extension that is expressible in a bipartite or compound form (for
687 example, C<\p{Present_In=4.0}>), so C<charprop> accepts it.  But C<Any> is a
688 Perl extension that isn't expressible that way, so C<charprop> returns
689 C<undef> for it.  Also C<charprop> returns C<undef> for all Perl extensions
690 that are internal-only.
691
692 =cut
693
694 sub charprop ($$) {
695     my ($input_cp, $prop) = @_;
696
697     my $cp = _getcode($input_cp);
698     croak __PACKAGE__, "::charprop: unknown code point '$input_cp'" unless defined $cp;
699
700     my ($list_ref, $map_ref, $format, $default)
701                                       = prop_invmap($prop);
702     return undef unless defined $list_ref;
703
704     my $i = search_invlist($list_ref, $cp);
705     croak __PACKAGE__, "::charprop: prop_invmap return is invalid for charprop('$input_cp', '$prop)" unless defined $i;
706
707     # $i is the index into both the inversion list and map of $cp.
708     my $map = $map_ref->[$i];
709
710     # Convert enumeration values to their most complete form.
711     if (! ref $map) {
712         my $long_form = prop_value_aliases($prop, $map);
713         $map = $long_form if defined $long_form;
714     }
715
716     if ($format =~ / ^ s /x) {  # Scalars
717         return join ",", @$map if ref $map; # Convert to scalar with comma
718                                             # separated array elements
719
720         # Resolve ambiguity as to whether an all digit value is a code point
721         # that should be converted to a character, or whether it is really
722         # just a number.  To do this, look at the default.  If it is a
723         # non-empty number, we can safely assume the result is also a number.
724         if ($map =~ / ^ \d+ $ /ax && $default !~ / ^ \d+ $ /ax) {
725             $map = chr $map;
726         }
727         elsif ($map =~ / ^ (?: Y | N ) $ /x) {
728
729             # prop_invmap() returns these values for properties that are Perl
730             # extensions.  But this is misleading.  For now, return undef for
731             # these, as currently documented.
732             undef $map unless
733                 exists $Unicode::UCD::prop_aliases{utf8::_loose_name(lc $prop)};
734         }
735         return $map;
736     }
737     elsif ($format eq 'ar') {   # numbers, including rationals
738         my $offset = $cp - $list_ref->[$i];
739         return $map if $map =~ /nan/i;
740         return $map + $offset if $offset != 0;  # If needs adjustment
741         return eval $map;   # Convert e.g., 1/2 to 0.5
742     }
743     elsif ($format =~ /^a/) {   # Some entries need adjusting
744
745         # Linearize sequences into a string.
746         return join "", map { chr $_ } @$map if ref $map; # XXX && $format =~ /^ a [dl] /x;
747
748         return "" if $map eq "" && $format =~ /^a.*e/;
749
750         # These are all character mappings.  Return the chr if no adjustment
751         # is needed
752         return chr $cp if $map eq "0";
753
754         # Convert special entry.
755         if ($map eq '<hangul syllable>' && $format eq 'ad') {
756             use Unicode::Normalize qw(NFD);
757             return NFD(chr $cp);
758         }
759
760         # The rest need adjustment from the first entry in the inversion list
761         # corresponding to this map.
762         my $offset = $cp - $list_ref->[$i];
763         return chr($map + $cp - $list_ref->[$i]);
764     }
765     elsif ($format eq 'n') {    # The name property
766
767         # There are two special cases, handled here.
768         if ($map =~ / ( .+ ) <code\ point> $ /x) {
769             $map = sprintf("$1%04X", $cp);
770         }
771         elsif ($map eq '<hangul syllable>') {
772             $map = charnames::viacode($cp);
773         }
774         return $map;
775     }
776     else {
777         croak __PACKAGE__, "::charprop: Internal error: unknown format '$format'.  Please perlbug this";
778     }
779 }
780
781 =head2 B<charprops_all()>
782
783     use Unicode::UCD 'charprops_all';
784
785     my $%properties_of_A_hash_ref = charprops_all("U+41");
786
787 This returns a reference to a hash whose keys are all the distinct Unicode (no
788 Perl extension) properties, and whose values are the respective values for
789 those properties for the input L</code point argument>.
790
791 Each key is the property name in its longest, most descriptive form.  The
792 values are what L</charprop()> would return.
793
794 This function is expensive in time and memory.
795
796 =cut
797
798 sub charprops_all($) {
799     my $input_cp = shift;
800
801     my $cp = _getcode($input_cp);
802     croak __PACKAGE__, "::charprops_all: unknown code point '$input_cp'" unless defined $cp;
803
804     my %return;
805
806     require "unicore/UCD.pl";
807
808     foreach my $prop (keys %Unicode::UCD::prop_aliases) {
809
810         # Don't return a Perl extension.  (This is the only one that
811         # %prop_aliases has in it.)
812         next if $prop eq 'perldecimaldigit';
813
814         # Use long name for $prop in the hash
815         $return{scalar prop_aliases($prop)} = charprop($cp, $prop);
816     }
817
818     return \%return;
819 }
820
821 =head2 B<charblock()>
822
823     use Unicode::UCD 'charblock';
824
825     my $charblock = charblock(0x41);
826     my $charblock = charblock(1234);
827     my $charblock = charblock(0x263a);
828     my $charblock = charblock("U+263a");
829
830     my $range     = charblock('Armenian');
831
832 With a L</code point argument> C<charblock()> returns the I<block> the code point
833 belongs to, e.g.  C<Basic Latin>.  The old-style block name is returned (see
834 L</Old-style versus new-style block names>).
835 The L</prop_value_aliases()> function can be used to get all the synonyms
836 of the block name.
837
838 If the code point is unassigned, this returns the block it would belong to if
839 it were assigned.  (If the Unicode version being used is so early as to not
840 have blocks, all code points are considered to be in C<No_Block>.)
841
842 See also L</Blocks versus Scripts>.
843
844 If supplied with an argument that can't be a code point, C<charblock()> tries to
845 do the opposite and interpret the argument as an old-style block name.  On an
846 ASCII platform, the return value is a I<range set> with one range: an
847 anonymous array with a single element that consists of another anonymous array
848 whose first element is the first code point in the block, and whose second
849 element is the final code point in the block.  On an EBCDIC
850 platform, the first two Unicode blocks are not contiguous.  Their range sets
851 are lists containing I<start-of-range>, I<end-of-range> code point pairs.  You
852 can test whether a code point is in a range set using the L</charinrange()>
853 function.  (To be precise, each I<range set> contains a third array element,
854 after the range boundary ones: the old_style block name.)
855
856 If the argument to C<charblock()> is not a known block, C<undef> is
857 returned.
858
859 =cut
860
861 my @BLOCKS;
862 my %BLOCKS;
863
864 sub _charblocks {
865
866     # Can't read from the mktables table because it loses the hyphens in the
867     # original.
868     unless (@BLOCKS) {
869         UnicodeVersion() unless defined $v_unicode_version;
870         if ($v_unicode_version lt v2.0.0) {
871             my $subrange = [ 0, 0x10FFFF, 'No_Block' ];
872             push @BLOCKS, $subrange;
873             push @{$BLOCKS{'No_Block'}}, $subrange;
874         }
875         elsif (openunicode(\$BLOCKSFH, "Blocks.txt")) {
876             local $_;
877             local $/ = "\n";
878             while (<$BLOCKSFH>) {
879                 if (/^([0-9A-F]+)\.\.([0-9A-F]+);\s+(.+)/) {
880                     my ($lo, $hi) = (hex($1), hex($2));
881                     my $subrange = [ $lo, $hi, $3 ];
882                     push @BLOCKS, $subrange;
883                     push @{$BLOCKS{$3}}, $subrange;
884                 }
885             }
886             close($BLOCKSFH);
887             if (! IS_ASCII_PLATFORM) {
888                 # The first two blocks, through 0xFF, are wrong on EBCDIC
889                 # platforms.
890
891                 my @new_blocks = _read_table("To/Blk.pl");
892
893                 # Get rid of the first two ranges in the Unicode version, and
894                 # replace them with the ones computed by mktables.
895                 shift @BLOCKS;
896                 shift @BLOCKS;
897                 delete $BLOCKS{'Basic Latin'};
898                 delete $BLOCKS{'Latin-1 Supplement'};
899
900                 # But there are multiple entries in the computed versions, and
901                 # we change their names to (which we know) to be the old-style
902                 # ones.
903                 for my $i (0.. @new_blocks - 1) {
904                     if ($new_blocks[$i][2] =~ s/Basic_Latin/Basic Latin/
905                         or $new_blocks[$i][2] =~
906                                     s/Latin_1_Supplement/Latin-1 Supplement/)
907                     {
908                         push @{$BLOCKS{$new_blocks[$i][2]}}, $new_blocks[$i];
909                     }
910                     else {
911                         splice @new_blocks, $i;
912                         last;
913                     }
914                 }
915                 unshift @BLOCKS, @new_blocks;
916             }
917         }
918     }
919 }
920
921 sub charblock {
922     my $arg = shift;
923
924     _charblocks() unless @BLOCKS;
925
926     my $code = _getcode($arg);
927
928     if (defined $code) {
929         my $result = _search(\@BLOCKS, 0, $#BLOCKS, $code);
930         return $result if defined $result;
931         return 'No_Block';
932     }
933     elsif (exists $BLOCKS{$arg}) {
934         return _dclone $BLOCKS{$arg};
935     }
936 }
937
938 =head2 B<charscript()>
939
940     use Unicode::UCD 'charscript';
941
942     my $charscript = charscript(0x41);
943     my $charscript = charscript(1234);
944     my $charscript = charscript("U+263a");
945
946     my $range      = charscript('Thai');
947
948 With a L</code point argument>, C<charscript()> returns the I<script> the
949 code point belongs to, e.g., C<Latin>, C<Greek>, C<Han>.
950 If the code point is unassigned or the Unicode version being used is so early
951 that it doesn't have scripts, this function returns C<"Unknown">.
952 The L</prop_value_aliases()> function can be used to get all the synonyms
953 of the script name.
954
955 If supplied with an argument that can't be a code point, charscript() tries
956 to do the opposite and interpret the argument as a script name. The
957 return value is a I<range set>: an anonymous array of arrays that contain
958 I<start-of-range>, I<end-of-range> code point pairs. You can test whether a
959 code point is in a range set using the L</charinrange()> function.
960 (To be precise, each I<range set> contains a third array element,
961 after the range boundary ones: the script name.)
962
963 If the C<charscript()> argument is not a known script, C<undef> is returned.
964
965 See also L</Blocks versus Scripts>.
966
967 =cut
968
969 my @SCRIPTS;
970 my %SCRIPTS;
971
972 sub _charscripts {
973     unless (@SCRIPTS) {
974         UnicodeVersion() unless defined $v_unicode_version;
975         if ($v_unicode_version lt v3.1.0) {
976             push @SCRIPTS, [ 0, 0x10FFFF, 'Unknown' ];
977         }
978         else {
979             @SCRIPTS =_read_table("To/Sc.pl");
980         }
981     }
982     foreach my $entry (@SCRIPTS) {
983         $entry->[2] =~ s/(_\w)/\L$1/g;  # Preserve old-style casing
984         push @{$SCRIPTS{$entry->[2]}}, $entry;
985     }
986 }
987
988 sub charscript {
989     my $arg = shift;
990
991     _charscripts() unless @SCRIPTS;
992
993     my $code = _getcode($arg);
994
995     if (defined $code) {
996         my $result = _search(\@SCRIPTS, 0, $#SCRIPTS, $code);
997         return $result if defined $result;
998         return $utf8::SwashInfo{'ToSc'}{'missing'};
999     } elsif (exists $SCRIPTS{$arg}) {
1000         return _dclone $SCRIPTS{$arg};
1001     }
1002
1003     return;
1004 }
1005
1006 =head2 B<charblocks()>
1007
1008     use Unicode::UCD 'charblocks';
1009
1010     my $charblocks = charblocks();
1011
1012 C<charblocks()> returns a reference to a hash with the known block names
1013 as the keys, and the code point ranges (see L</charblock()>) as the values.
1014
1015 The names are in the old-style (see L</Old-style versus new-style block
1016 names>).
1017
1018 L<prop_invmap("block")|/prop_invmap()> can be used to get this same data in a
1019 different type of data structure.
1020
1021 L<prop_values("Block")|/prop_values()> can be used to get all
1022 the known new-style block names as a list, without the code point ranges.
1023
1024 See also L</Blocks versus Scripts>.
1025
1026 =cut
1027
1028 sub charblocks {
1029     _charblocks() unless %BLOCKS;
1030     return _dclone \%BLOCKS;
1031 }
1032
1033 =head2 B<charscripts()>
1034
1035     use Unicode::UCD 'charscripts';
1036
1037     my $charscripts = charscripts();
1038
1039 C<charscripts()> returns a reference to a hash with the known script
1040 names as the keys, and the code point ranges (see L</charscript()>) as
1041 the values.
1042
1043 L<prop_invmap("script")|/prop_invmap()> can be used to get this same data in a
1044 different type of data structure.
1045
1046 L<C<prop_values("Script")>|/prop_values()> can be used to get all
1047 the known script names as a list, without the code point ranges.
1048
1049 See also L</Blocks versus Scripts>.
1050
1051 =cut
1052
1053 sub charscripts {
1054     _charscripts() unless %SCRIPTS;
1055     return _dclone \%SCRIPTS;
1056 }
1057
1058 =head2 B<charinrange()>
1059
1060 In addition to using the C<\p{Blk=...}> and C<\P{Blk=...}> constructs, you
1061 can also test whether a code point is in the I<range> as returned by
1062 L</charblock()> and L</charscript()> or as the values of the hash returned
1063 by L</charblocks()> and L</charscripts()> by using C<charinrange()>:
1064
1065     use Unicode::UCD qw(charscript charinrange);
1066
1067     $range = charscript('Hiragana');
1068     print "looks like hiragana\n" if charinrange($range, $codepoint);
1069
1070 =cut
1071
1072 my %GENERAL_CATEGORIES =
1073  (
1074     'L'  =>         'Letter',
1075     'LC' =>         'CasedLetter',
1076     'Lu' =>         'UppercaseLetter',
1077     'Ll' =>         'LowercaseLetter',
1078     'Lt' =>         'TitlecaseLetter',
1079     'Lm' =>         'ModifierLetter',
1080     'Lo' =>         'OtherLetter',
1081     'M'  =>         'Mark',
1082     'Mn' =>         'NonspacingMark',
1083     'Mc' =>         'SpacingMark',
1084     'Me' =>         'EnclosingMark',
1085     'N'  =>         'Number',
1086     'Nd' =>         'DecimalNumber',
1087     'Nl' =>         'LetterNumber',
1088     'No' =>         'OtherNumber',
1089     'P'  =>         'Punctuation',
1090     'Pc' =>         'ConnectorPunctuation',
1091     'Pd' =>         'DashPunctuation',
1092     'Ps' =>         'OpenPunctuation',
1093     'Pe' =>         'ClosePunctuation',
1094     'Pi' =>         'InitialPunctuation',
1095     'Pf' =>         'FinalPunctuation',
1096     'Po' =>         'OtherPunctuation',
1097     'S'  =>         'Symbol',
1098     'Sm' =>         'MathSymbol',
1099     'Sc' =>         'CurrencySymbol',
1100     'Sk' =>         'ModifierSymbol',
1101     'So' =>         'OtherSymbol',
1102     'Z'  =>         'Separator',
1103     'Zs' =>         'SpaceSeparator',
1104     'Zl' =>         'LineSeparator',
1105     'Zp' =>         'ParagraphSeparator',
1106     'C'  =>         'Other',
1107     'Cc' =>         'Control',
1108     'Cf' =>         'Format',
1109     'Cs' =>         'Surrogate',
1110     'Co' =>         'PrivateUse',
1111     'Cn' =>         'Unassigned',
1112  );
1113
1114 sub general_categories {
1115     return _dclone \%GENERAL_CATEGORIES;
1116 }
1117
1118 =head2 B<general_categories()>
1119
1120     use Unicode::UCD 'general_categories';
1121
1122     my $categories = general_categories();
1123
1124 This returns a reference to a hash which has short
1125 general category names (such as C<Lu>, C<Nd>, C<Zs>, C<S>) as keys and long
1126 names (such as C<UppercaseLetter>, C<DecimalNumber>, C<SpaceSeparator>,
1127 C<Symbol>) as values.  The hash is reversible in case you need to go
1128 from the long names to the short names.  The general category is the
1129 one returned from
1130 L</charinfo()> under the C<category> key.
1131
1132 The L</prop_values()> and L</prop_value_aliases()> functions can be used as an
1133 alternative to this function; the first returning a simple list of the short
1134 category names; and the second gets all the synonyms of a given category name.
1135
1136 =cut
1137
1138 my %BIDI_TYPES =
1139  (
1140    'L'   => 'Left-to-Right',
1141    'LRE' => 'Left-to-Right Embedding',
1142    'LRO' => 'Left-to-Right Override',
1143    'R'   => 'Right-to-Left',
1144    'AL'  => 'Right-to-Left Arabic',
1145    'RLE' => 'Right-to-Left Embedding',
1146    'RLO' => 'Right-to-Left Override',
1147    'PDF' => 'Pop Directional Format',
1148    'EN'  => 'European Number',
1149    'ES'  => 'European Number Separator',
1150    'ET'  => 'European Number Terminator',
1151    'AN'  => 'Arabic Number',
1152    'CS'  => 'Common Number Separator',
1153    'NSM' => 'Non-Spacing Mark',
1154    'BN'  => 'Boundary Neutral',
1155    'B'   => 'Paragraph Separator',
1156    'S'   => 'Segment Separator',
1157    'WS'  => 'Whitespace',
1158    'ON'  => 'Other Neutrals',
1159  ); 
1160
1161 =head2 B<bidi_types()>
1162
1163     use Unicode::UCD 'bidi_types';
1164
1165     my $categories = bidi_types();
1166
1167 This returns a reference to a hash which has the short
1168 bidi (bidirectional) type names (such as C<L>, C<R>) as keys and long
1169 names (such as C<Left-to-Right>, C<Right-to-Left>) as values.  The
1170 hash is reversible in case you need to go from the long names to the
1171 short names.  The bidi type is the one returned from
1172 L</charinfo()>
1173 under the C<bidi> key.  For the exact meaning of the various bidi classes
1174 the Unicode TR9 is recommended reading:
1175 L<http://www.unicode.org/reports/tr9/>
1176 (as of Unicode 5.0.0)
1177
1178 The L</prop_values()> and L</prop_value_aliases()> functions can be used as an
1179 alternative to this function; the first returning a simple list of the short
1180 bidi type names; and the second gets all the synonyms of a given bidi type
1181 name.
1182
1183 =cut
1184
1185 sub bidi_types {
1186     return _dclone \%BIDI_TYPES;
1187 }
1188
1189 =head2 B<compexcl()>
1190
1191     use Unicode::UCD 'compexcl';
1192
1193     my $compexcl = compexcl(0x09dc);
1194
1195 This routine returns C<undef> if the Unicode version being used is so early
1196 that it doesn't have this property.
1197
1198 C<compexcl()> is included for backwards
1199 compatibility, but as of Perl 5.12 and more modern Unicode versions, for
1200 most purposes it is probably more convenient to use one of the following
1201 instead:
1202
1203     my $compexcl = chr(0x09dc) =~ /\p{Comp_Ex};
1204     my $compexcl = chr(0x09dc) =~ /\p{Full_Composition_Exclusion};
1205
1206 or even
1207
1208     my $compexcl = chr(0x09dc) =~ /\p{CE};
1209     my $compexcl = chr(0x09dc) =~ /\p{Composition_Exclusion};
1210
1211 The first two forms return B<true> if the L</code point argument> should not
1212 be produced by composition normalization.  For the final two forms to return
1213 B<true>, it is additionally required that this fact not otherwise be
1214 determinable from the Unicode data base.
1215
1216 This routine behaves identically to the final two forms.  That is,
1217 it does not return B<true> if the code point has a decomposition
1218 consisting of another single code point, nor if its decomposition starts
1219 with a code point whose combining class is non-zero.  Code points that meet
1220 either of these conditions should also not be produced by composition
1221 normalization, which is probably why you should use the
1222 C<Full_Composition_Exclusion> property instead, as shown above.
1223
1224 The routine returns B<false> otherwise.
1225
1226 =cut
1227
1228 sub compexcl {
1229     my $arg  = shift;
1230     my $code = _getcode($arg);
1231     croak __PACKAGE__, "::compexcl: unknown code '$arg'"
1232         unless defined $code;
1233
1234     UnicodeVersion() unless defined $v_unicode_version;
1235     return if $v_unicode_version lt v3.0.0;
1236
1237     no warnings "non_unicode";     # So works on non-Unicode code points
1238     return chr($code) =~ /\p{Composition_Exclusion}/;
1239 }
1240
1241 =head2 B<casefold()>
1242
1243     use Unicode::UCD 'casefold';
1244
1245     my $casefold = casefold(0xDF);
1246     if (defined $casefold) {
1247         my @full_fold_hex = split / /, $casefold->{'full'};
1248         my $full_fold_string =
1249                     join "", map {chr(hex($_))} @full_fold_hex;
1250         my @turkic_fold_hex =
1251                         split / /, ($casefold->{'turkic'} ne "")
1252                                         ? $casefold->{'turkic'}
1253                                         : $casefold->{'full'};
1254         my $turkic_fold_string =
1255                         join "", map {chr(hex($_))} @turkic_fold_hex;
1256     }
1257     if (defined $casefold && $casefold->{'simple'} ne "") {
1258         my $simple_fold_hex = $casefold->{'simple'};
1259         my $simple_fold_string = chr(hex($simple_fold_hex));
1260     }
1261
1262 This returns the (almost) locale-independent case folding of the
1263 character specified by the L</code point argument>.  (Starting in Perl v5.16,
1264 the core function C<fc()> returns the C<full> mapping (described below)
1265 faster than this does, and for entire strings.)
1266
1267 If there is no case folding for the input code point, C<undef> is returned.
1268
1269 If there is a case folding for that code point, a reference to a hash
1270 with the following fields is returned:
1271
1272 =over
1273
1274 =item B<code>
1275
1276 the input native L</code point argument> expressed in hexadecimal, with
1277 leading zeros
1278 added if necessary to make it contain at least four hexdigits
1279
1280 =item B<full>
1281
1282 one or more codes (separated by spaces) that, taken in order, give the
1283 code points for the case folding for I<code>.
1284 Each has at least four hexdigits.
1285
1286 =item B<simple>
1287
1288 is empty, or is exactly one code with at least four hexdigits which can be used
1289 as an alternative case folding when the calling program cannot cope with the
1290 fold being a sequence of multiple code points.  If I<full> is just one code
1291 point, then I<simple> equals I<full>.  If there is no single code point folding
1292 defined for I<code>, then I<simple> is the empty string.  Otherwise, it is an
1293 inferior, but still better-than-nothing alternative folding to I<full>.
1294
1295 =item B<mapping>
1296
1297 is the same as I<simple> if I<simple> is not empty, and it is the same as I<full>
1298 otherwise.  It can be considered to be the simplest possible folding for
1299 I<code>.  It is defined primarily for backwards compatibility.
1300
1301 =item B<status>
1302
1303 is C<C> (for C<common>) if the best possible fold is a single code point
1304 (I<simple> equals I<full> equals I<mapping>).  It is C<S> if there are distinct
1305 folds, I<simple> and I<full> (I<mapping> equals I<simple>).  And it is C<F> if
1306 there is only a I<full> fold (I<mapping> equals I<full>; I<simple> is empty).
1307 Note that this
1308 describes the contents of I<mapping>.  It is defined primarily for backwards
1309 compatibility.
1310
1311 For Unicode versions between 3.1 and 3.1.1 inclusive, I<status> can also be
1312 C<I> which is the same as C<C> but is a special case for dotted uppercase I and
1313 dotless lowercase i:
1314
1315 =over
1316
1317 =item Z<>B<*> If you use this C<I> mapping
1318
1319 the result is case-insensitive,
1320 but dotless and dotted I's are not distinguished
1321
1322 =item Z<>B<*> If you exclude this C<I> mapping
1323
1324 the result is not fully case-insensitive, but
1325 dotless and dotted I's are distinguished
1326
1327 =back
1328
1329 =item B<turkic>
1330
1331 contains any special folding for Turkic languages.  For versions of Unicode
1332 starting with 3.2, this field is empty unless I<code> has a different folding
1333 in Turkic languages, in which case it is one or more codes (separated by
1334 spaces) that, taken in order, give the code points for the case folding for
1335 I<code> in those languages.
1336 Each code has at least four hexdigits.
1337 Note that this folding does not maintain canonical equivalence without
1338 additional processing.
1339
1340 For Unicode versions between 3.1 and 3.1.1 inclusive, this field is empty unless
1341 there is a
1342 special folding for Turkic languages, in which case I<status> is C<I>, and
1343 I<mapping>, I<full>, I<simple>, and I<turkic> are all equal.  
1344
1345 =back
1346
1347 Programs that want complete generality and the best folding results should use
1348 the folding contained in the I<full> field.  But note that the fold for some
1349 code points will be a sequence of multiple code points.
1350
1351 Programs that can't cope with the fold mapping being multiple code points can
1352 use the folding contained in the I<simple> field, with the loss of some
1353 generality.  In Unicode 5.1, about 7% of the defined foldings have no single
1354 code point folding.
1355
1356 The I<mapping> and I<status> fields are provided for backwards compatibility for
1357 existing programs.  They contain the same values as in previous versions of
1358 this function.
1359
1360 Locale is not completely independent.  The I<turkic> field contains results to
1361 use when the locale is a Turkic language.
1362
1363 For more information about case mappings see
1364 L<http://www.unicode.org/unicode/reports/tr21>
1365
1366 =cut
1367
1368 my %CASEFOLD;
1369
1370 sub _casefold {
1371     unless (%CASEFOLD) {   # Populate the hash
1372         my ($full_invlist_ref, $full_invmap_ref, undef, $default)
1373                                                 = prop_invmap('Case_Folding');
1374
1375         # Use the recipe given in the prop_invmap() pod to convert the
1376         # inversion map into the hash.
1377         for my $i (0 .. @$full_invlist_ref - 1 - 1) {
1378             next if $full_invmap_ref->[$i] == $default;
1379             my $adjust = -1;
1380             for my $j ($full_invlist_ref->[$i] .. $full_invlist_ref->[$i+1] -1) {
1381                 $adjust++;
1382                 if (! ref $full_invmap_ref->[$i]) {
1383
1384                     # This is a single character mapping
1385                     $CASEFOLD{$j}{'status'} = 'C';
1386                     $CASEFOLD{$j}{'simple'}
1387                         = $CASEFOLD{$j}{'full'}
1388                         = $CASEFOLD{$j}{'mapping'}
1389                         = sprintf("%04X", $full_invmap_ref->[$i] + $adjust);
1390                     $CASEFOLD{$j}{'code'} = sprintf("%04X", $j);
1391                     $CASEFOLD{$j}{'turkic'} = "";
1392                 }
1393                 else {  # prop_invmap ensures that $adjust is 0 for a ref
1394                     $CASEFOLD{$j}{'status'} = 'F';
1395                     $CASEFOLD{$j}{'full'}
1396                     = $CASEFOLD{$j}{'mapping'}
1397                     = join " ", map { sprintf "%04X", $_ }
1398                                                     @{$full_invmap_ref->[$i]};
1399                     $CASEFOLD{$j}{'simple'} = "";
1400                     $CASEFOLD{$j}{'code'} = sprintf("%04X", $j);
1401                     $CASEFOLD{$j}{'turkic'} = "";
1402                 }
1403             }
1404         }
1405
1406         # We have filled in the full mappings above, assuming there were no
1407         # simple ones for the ones with multi-character maps.  Now, we find
1408         # and fix the cases where that assumption was false.
1409         (my ($simple_invlist_ref, $simple_invmap_ref, undef), $default)
1410                                         = prop_invmap('Simple_Case_Folding');
1411         for my $i (0 .. @$simple_invlist_ref - 1 - 1) {
1412             next if $simple_invmap_ref->[$i] == $default;
1413             my $adjust = -1;
1414             for my $j ($simple_invlist_ref->[$i]
1415                        .. $simple_invlist_ref->[$i+1] -1)
1416             {
1417                 $adjust++;
1418                 next if $CASEFOLD{$j}{'status'} eq 'C';
1419                 $CASEFOLD{$j}{'status'} = 'S';
1420                 $CASEFOLD{$j}{'simple'}
1421                     = $CASEFOLD{$j}{'mapping'}
1422                     = sprintf("%04X", $simple_invmap_ref->[$i] + $adjust);
1423                 $CASEFOLD{$j}{'code'} = sprintf("%04X", $j);
1424                 $CASEFOLD{$j}{'turkic'} = "";
1425             }
1426         }
1427
1428         # We hard-code in the turkish rules
1429         UnicodeVersion() unless defined $v_unicode_version;
1430         if ($v_unicode_version ge v3.2.0) {
1431
1432             # These two code points should already have regular entries, so
1433             # just fill in the turkish fields
1434             $CASEFOLD{ord('I')}{'turkic'} = '0131';
1435             $CASEFOLD{0x130}{'turkic'} = sprintf "%04X", ord('i');
1436         }
1437         elsif ($v_unicode_version ge v3.1.0) {
1438
1439             # These two code points don't have entries otherwise.
1440             $CASEFOLD{0x130}{'code'} = '0130';
1441             $CASEFOLD{0x131}{'code'} = '0131';
1442             $CASEFOLD{0x130}{'status'} = $CASEFOLD{0x131}{'status'} = 'I';
1443             $CASEFOLD{0x130}{'turkic'}
1444                 = $CASEFOLD{0x130}{'mapping'}
1445                 = $CASEFOLD{0x130}{'full'}
1446                 = $CASEFOLD{0x130}{'simple'}
1447                 = $CASEFOLD{0x131}{'turkic'}
1448                 = $CASEFOLD{0x131}{'mapping'}
1449                 = $CASEFOLD{0x131}{'full'}
1450                 = $CASEFOLD{0x131}{'simple'}
1451                 = sprintf "%04X", ord('i');
1452         }
1453     }
1454 }
1455
1456 sub casefold {
1457     my $arg  = shift;
1458     my $code = _getcode($arg);
1459     croak __PACKAGE__, "::casefold: unknown code '$arg'"
1460         unless defined $code;
1461
1462     _casefold() unless %CASEFOLD;
1463
1464     return $CASEFOLD{$code};
1465 }
1466
1467 =head2 B<all_casefolds()>
1468
1469
1470     use Unicode::UCD 'all_casefolds';
1471
1472     my $all_folds_ref = all_casefolds();
1473     foreach my $char_with_casefold (sort { $a <=> $b }
1474                                     keys %$all_folds_ref)
1475     {
1476         printf "%04X:", $char_with_casefold;
1477         my $casefold = $all_folds_ref->{$char_with_casefold};
1478
1479         # Get folds for $char_with_casefold
1480
1481         my @full_fold_hex = split / /, $casefold->{'full'};
1482         my $full_fold_string =
1483                     join "", map {chr(hex($_))} @full_fold_hex;
1484         print " full=", join " ", @full_fold_hex;
1485         my @turkic_fold_hex =
1486                         split / /, ($casefold->{'turkic'} ne "")
1487                                         ? $casefold->{'turkic'}
1488                                         : $casefold->{'full'};
1489         my $turkic_fold_string =
1490                         join "", map {chr(hex($_))} @turkic_fold_hex;
1491         print "; turkic=", join " ", @turkic_fold_hex;
1492         if (defined $casefold && $casefold->{'simple'} ne "") {
1493             my $simple_fold_hex = $casefold->{'simple'};
1494             my $simple_fold_string = chr(hex($simple_fold_hex));
1495             print "; simple=$simple_fold_hex";
1496         }
1497         print "\n";
1498     }
1499
1500 This returns all the case foldings in the current version of Unicode in the
1501 form of a reference to a hash.  Each key to the hash is the decimal
1502 representation of a Unicode character that has a casefold to other than
1503 itself.  The casefold of a semi-colon is itself, so it isn't in the hash;
1504 likewise for a lowercase "a", but there is an entry for a capital "A".  The
1505 hash value for each key is another hash, identical to what is returned by
1506 L</casefold()> if called with that code point as its argument.  So the value
1507 C<< all_casefolds()->{ord("A")}' >> is equivalent to C<casefold(ord("A"))>;
1508
1509 =cut
1510
1511 sub all_casefolds () {
1512     _casefold() unless %CASEFOLD;
1513     return _dclone \%CASEFOLD;
1514 }
1515
1516 =head2 B<casespec()>
1517
1518     use Unicode::UCD 'casespec';
1519
1520     my $casespec = casespec(0xFB00);
1521
1522 This returns the potentially locale-dependent case mappings of the L</code point
1523 argument>.  The mappings may be longer than a single code point (which the basic
1524 Unicode case mappings as returned by L</charinfo()> never are).
1525
1526 If there are no case mappings for the L</code point argument>, or if all three
1527 possible mappings (I<lower>, I<title> and I<upper>) result in single code
1528 points and are locale independent and unconditional, C<undef> is returned
1529 (which means that the case mappings, if any, for the code point are those
1530 returned by L</charinfo()>).
1531
1532 Otherwise, a reference to a hash giving the mappings (or a reference to a hash
1533 of such hashes, explained below) is returned with the following keys and their
1534 meanings:
1535
1536 The keys in the bottom layer hash with the meanings of their values are:
1537
1538 =over
1539
1540 =item B<code>
1541
1542 the input native L</code point argument> expressed in hexadecimal, with
1543 leading zeros
1544 added if necessary to make it contain at least four hexdigits
1545
1546 =item B<lower>
1547
1548 one or more codes (separated by spaces) that, taken in order, give the
1549 code points for the lower case of I<code>.
1550 Each has at least four hexdigits.
1551
1552 =item B<title>
1553
1554 one or more codes (separated by spaces) that, taken in order, give the
1555 code points for the title case of I<code>.
1556 Each has at least four hexdigits.
1557
1558 =item B<upper>
1559
1560 one or more codes (separated by spaces) that, taken in order, give the
1561 code points for the upper case of I<code>.
1562 Each has at least four hexdigits.
1563
1564 =item B<condition>
1565
1566 the conditions for the mappings to be valid.
1567 If C<undef>, the mappings are always valid.
1568 When defined, this field is a list of conditions,
1569 all of which must be true for the mappings to be valid.
1570 The list consists of one or more
1571 I<locales> (see below)
1572 and/or I<contexts> (explained in the next paragraph),
1573 separated by spaces.
1574 (Other than as used to separate elements, spaces are to be ignored.)
1575 Case distinctions in the condition list are not significant.
1576 Conditions preceded by "NON_" represent the negation of the condition.
1577
1578 A I<context> is one of those defined in the Unicode standard.
1579 For Unicode 5.1, they are defined in Section 3.13 C<Default Case Operations>
1580 available at
1581 L<http://www.unicode.org/versions/Unicode5.1.0/>.
1582 These are for context-sensitive casing.
1583
1584 =back
1585
1586 The hash described above is returned for locale-independent casing, where
1587 at least one of the mappings has length longer than one.  If C<undef> is
1588 returned, the code point may have mappings, but if so, all are length one,
1589 and are returned by L</charinfo()>.
1590 Note that when this function does return a value, it will be for the complete
1591 set of mappings for a code point, even those whose length is one.
1592
1593 If there are additional casing rules that apply only in certain locales,
1594 an additional key for each will be defined in the returned hash.  Each such key
1595 will be its locale name, defined as a 2-letter ISO 3166 country code, possibly
1596 followed by a "_" and a 2-letter ISO language code (possibly followed by a "_"
1597 and a variant code).  You can find the lists of all possible locales, see
1598 L<Locale::Country> and L<Locale::Language>.
1599 (In Unicode 6.0, the only locales returned by this function
1600 are C<lt>, C<tr>, and C<az>.)
1601
1602 Each locale key is a reference to a hash that has the form above, and gives
1603 the casing rules for that particular locale, which take precedence over the
1604 locale-independent ones when in that locale.
1605
1606 If the only casing for a code point is locale-dependent, then the returned
1607 hash will not have any of the base keys, like C<code>, C<upper>, etc., but
1608 will contain only locale keys.
1609
1610 For more information about case mappings see
1611 L<http://www.unicode.org/unicode/reports/tr21/>
1612
1613 =cut
1614
1615 my %CASESPEC;
1616
1617 sub _casespec {
1618     unless (%CASESPEC) {
1619         UnicodeVersion() unless defined $v_unicode_version;
1620         if ($v_unicode_version lt v2.1.8) {
1621             %CASESPEC = {};
1622         }
1623         elsif (openunicode(\$CASESPECFH, "SpecialCasing.txt")) {
1624             local $_;
1625             local $/ = "\n";
1626             while (<$CASESPECFH>) {
1627                 if (/^([0-9A-F]+); ([0-9A-F]+(?: [0-9A-F]+)*)?; ([0-9A-F]+(?: [0-9A-F]+)*)?; ([0-9A-F]+(?: [0-9A-F]+)*)?; (\w+(?: \w+)*)?/) {
1628
1629                     my ($hexcode, $lower, $title, $upper, $condition) =
1630                         ($1, $2, $3, $4, $5);
1631                     if (! IS_ASCII_PLATFORM) { # Remap entry to native
1632                         foreach my $var_ref (\$hexcode,
1633                                              \$lower,
1634                                              \$title,
1635                                              \$upper)
1636                         {
1637                             next unless defined $$var_ref;
1638                             $$var_ref = join " ",
1639                                         map { sprintf("%04X",
1640                                               utf8::unicode_to_native(hex $_)) }
1641                                         split " ", $$var_ref;
1642                         }
1643                     }
1644
1645                     my $code = hex($hexcode);
1646
1647                     # In 2.1.8, there were duplicate entries; ignore all but
1648                     # the first one -- there were no conditions in the file
1649                     # anyway.
1650                     if (exists $CASESPEC{$code} && $v_unicode_version ne v2.1.8)
1651                     {
1652                         if (exists $CASESPEC{$code}->{code}) {
1653                             my ($oldlower,
1654                                 $oldtitle,
1655                                 $oldupper,
1656                                 $oldcondition) =
1657                                     @{$CASESPEC{$code}}{qw(lower
1658                                                            title
1659                                                            upper
1660                                                            condition)};
1661                             if (defined $oldcondition) {
1662                                 my ($oldlocale) =
1663                                 ($oldcondition =~ /^([a-z][a-z](?:_\S+)?)/);
1664                                 delete $CASESPEC{$code};
1665                                 $CASESPEC{$code}->{$oldlocale} =
1666                                 { code      => $hexcode,
1667                                   lower     => $oldlower,
1668                                   title     => $oldtitle,
1669                                   upper     => $oldupper,
1670                                   condition => $oldcondition };
1671                             }
1672                         }
1673                         my ($locale) =
1674                             ($condition =~ /^([a-z][a-z](?:_\S+)?)/);
1675                         $CASESPEC{$code}->{$locale} =
1676                         { code      => $hexcode,
1677                           lower     => $lower,
1678                           title     => $title,
1679                           upper     => $upper,
1680                           condition => $condition };
1681                     } else {
1682                         $CASESPEC{$code} =
1683                         { code      => $hexcode,
1684                           lower     => $lower,
1685                           title     => $title,
1686                           upper     => $upper,
1687                           condition => $condition };
1688                     }
1689                 }
1690             }
1691             close($CASESPECFH);
1692         }
1693     }
1694 }
1695
1696 sub casespec {
1697     my $arg  = shift;
1698     my $code = _getcode($arg);
1699     croak __PACKAGE__, "::casespec: unknown code '$arg'"
1700         unless defined $code;
1701
1702     _casespec() unless %CASESPEC;
1703
1704     return ref $CASESPEC{$code} ? _dclone $CASESPEC{$code} : $CASESPEC{$code};
1705 }
1706
1707 =head2 B<namedseq()>
1708
1709     use Unicode::UCD 'namedseq';
1710
1711     my $namedseq = namedseq("KATAKANA LETTER AINU P");
1712     my @namedseq = namedseq("KATAKANA LETTER AINU P");
1713     my %namedseq = namedseq();
1714
1715 If used with a single argument in a scalar context, returns the string
1716 consisting of the code points of the named sequence, or C<undef> if no
1717 named sequence by that name exists.  If used with a single argument in
1718 a list context, it returns the list of the ordinals of the code points.
1719
1720 If used with no
1721 arguments in a list context, it returns a hash with the names of all the
1722 named sequences as the keys and their sequences as strings as
1723 the values.  Otherwise, it returns C<undef> or an empty list depending
1724 on the context.
1725
1726 This function only operates on officially approved (not provisional) named
1727 sequences.
1728
1729 Note that as of Perl 5.14, C<\N{KATAKANA LETTER AINU P}> will insert the named
1730 sequence into double-quoted strings, and C<charnames::string_vianame("KATAKANA
1731 LETTER AINU P")> will return the same string this function does, but will also
1732 operate on character names that aren't named sequences, without you having to
1733 know which are which.  See L<charnames>.
1734
1735 =cut
1736
1737 my %NAMEDSEQ;
1738
1739 sub _namedseq {
1740     unless (%NAMEDSEQ) {
1741         if (openunicode(\$NAMEDSEQFH, "Name.pl")) {
1742             local $_;
1743             local $/ = "\n";
1744             while (<$NAMEDSEQFH>) {
1745                 if (/^ [0-9A-F]+ \  /x) {
1746                     chomp;
1747                     my ($sequence, $name) = split /\t/;
1748                     my @s = map { chr(hex($_)) } split(' ', $sequence);
1749                     $NAMEDSEQ{$name} = join("", @s);
1750                 }
1751             }
1752             close($NAMEDSEQFH);
1753         }
1754     }
1755 }
1756
1757 sub namedseq {
1758
1759     # Use charnames::string_vianame() which now returns this information,
1760     # unless the caller wants the hash returned, in which case we read it in,
1761     # and thereafter use it instead of calling charnames, as it is faster.
1762
1763     my $wantarray = wantarray();
1764     if (defined $wantarray) {
1765         if ($wantarray) {
1766             if (@_ == 0) {
1767                 _namedseq() unless %NAMEDSEQ;
1768                 return %NAMEDSEQ;
1769             } elsif (@_ == 1) {
1770                 my $s;
1771                 if (%NAMEDSEQ) {
1772                     $s = $NAMEDSEQ{ $_[0] };
1773                 }
1774                 else {
1775                     $s = charnames::string_vianame($_[0]);
1776                 }
1777                 return defined $s ? map { ord($_) } split('', $s) : ();
1778             }
1779         } elsif (@_ == 1) {
1780             return $NAMEDSEQ{ $_[0] } if %NAMEDSEQ;
1781             return charnames::string_vianame($_[0]);
1782         }
1783     }
1784     return;
1785 }
1786
1787 my %NUMERIC;
1788
1789 sub _numeric {
1790     my @numbers = _read_table("To/Nv.pl");
1791     foreach my $entry (@numbers) {
1792         my ($start, $end, $value) = @$entry;
1793
1794         # If value contains a slash, convert to decimal, add a reverse hash
1795         # used by charinfo.
1796         if ((my @rational = split /\//, $value) == 2) {
1797             my $real = $rational[0] / $rational[1];
1798             $real_to_rational{$real} = $value;
1799             $value = $real;
1800
1801             # Should only be single element, but just in case...
1802             for my $i ($start .. $end) {
1803                 $NUMERIC{$i} = $value;
1804             }
1805         }
1806         else {
1807             # The values require adjusting, as is in 'a' format
1808             for my $i ($start .. $end) {
1809                 $NUMERIC{$i} = $value + $i - $start;
1810             }
1811         }
1812     }
1813
1814     # Decided unsafe to use these that aren't officially part of the Unicode
1815     # standard.
1816     #use Math::Trig;
1817     #my $pi = acos(-1.0);
1818     #$NUMERIC{0x03C0} = $pi;
1819
1820     # Euler's constant, not to be confused with Euler's number
1821     #$NUMERIC{0x2107} = 0.57721566490153286060651209008240243104215933593992;
1822
1823     # Euler's number
1824     #$NUMERIC{0x212F} = 2.7182818284590452353602874713526624977572;
1825
1826     return;
1827 }
1828
1829 =pod
1830
1831 =head2 B<num()>
1832
1833     use Unicode::UCD 'num';
1834
1835     my $val = num("123");
1836     my $one_quarter = num("\N{VULGAR FRACTION 1/4}");
1837
1838 C<num()> returns the numeric value of the input Unicode string; or C<undef> if it
1839 doesn't think the entire string has a completely valid, safe numeric value.
1840
1841 If the string is just one character in length, the Unicode numeric value
1842 is returned if it has one, or C<undef> otherwise.  Note that this need
1843 not be a whole number.  C<num("\N{TIBETAN DIGIT HALF ZERO}")>, for
1844 example returns -0.5.
1845
1846 =cut
1847
1848 #A few characters to which Unicode doesn't officially
1849 #assign a numeric value are considered numeric by C<num>.
1850 #These are:
1851
1852 # EULER CONSTANT             0.5772...  (this is NOT Euler's number)
1853 # SCRIPT SMALL E             2.71828... (this IS Euler's number)
1854 # GREEK SMALL LETTER PI      3.14159...
1855
1856 =pod
1857
1858 If the string is more than one character, C<undef> is returned unless
1859 all its characters are decimal digits (that is, they would match C<\d+>),
1860 from the same script.  For example if you have an ASCII '0' and a Bengali
1861 '3', mixed together, they aren't considered a valid number, and C<undef>
1862 is returned.  A further restriction is that the digits all have to be of
1863 the same form.  A half-width digit mixed with a full-width one will
1864 return C<undef>.  The Arabic script has two sets of digits;  C<num> will
1865 return C<undef> unless all the digits in the string come from the same
1866 set.
1867
1868 C<num> errs on the side of safety, and there may be valid strings of
1869 decimal digits that it doesn't recognize.  Note that Unicode defines
1870 a number of "digit" characters that aren't "decimal digit" characters.
1871 "Decimal digits" have the property that they have a positional value, i.e.,
1872 there is a units position, a 10's position, a 100's, etc, AND they are
1873 arranged in Unicode in blocks of 10 contiguous code points.  The Chinese
1874 digits, for example, are not in such a contiguous block, and so Unicode
1875 doesn't view them as decimal digits, but merely digits, and so C<\d> will not
1876 match them.  A single-character string containing one of these digits will
1877 have its decimal value returned by C<num>, but any longer string containing
1878 only these digits will return C<undef>.
1879
1880 Strings of multiple sub- and superscripts are not recognized as numbers.  You
1881 can use either of the compatibility decompositions in Unicode::Normalize to
1882 change these into digits, and then call C<num> on the result.
1883
1884 =cut
1885
1886 # To handle sub, superscripts, this could if called in list context,
1887 # consider those, and return the <decomposition> type in the second
1888 # array element.
1889
1890 sub num {
1891     my $string = $_[0];
1892
1893     _numeric unless %NUMERIC;
1894
1895     my $length = length($string);
1896     return $NUMERIC{ord($string)} if $length == 1;
1897     return if $string =~ /\D/;
1898     my $first_ord = ord(substr($string, 0, 1));
1899     my $value = $NUMERIC{$first_ord};
1900
1901     # To be a valid decimal number, it should be in a block of 10 consecutive
1902     # characters, whose values are 0, 1, 2, ... 9.  Therefore this digit's
1903     # value is its offset in that block from the character that means zero.
1904     my $zero_ord = $first_ord - $value;
1905
1906     # Unicode 6.0 instituted the rule that only digits in a consecutive
1907     # block of 10 would be considered decimal digits.  If this is an earlier
1908     # release, we verify that this first character is a member of such a
1909     # block.  That is, that the block of characters surrounding this one
1910     # consists of all \d characters whose numeric values are the expected
1911     # ones.
1912     UnicodeVersion() unless defined $v_unicode_version;
1913     if ($v_unicode_version lt v6.0.0) {
1914         for my $i (0 .. 9) {
1915             my $ord = $zero_ord + $i;
1916             return unless chr($ord) =~ /\d/;
1917             my $numeric = $NUMERIC{$ord};
1918             return unless defined $numeric;
1919             return unless $numeric == $i;
1920         }
1921     }
1922
1923     for my $i (1 .. $length -1) {
1924
1925         # Here we know either by verifying, or by fact of the first character
1926         # being a \d in Unicode 6.0 or later, that any character between the
1927         # character that means 0, and 9 positions above it must be \d, and
1928         # must have its value correspond to its offset from the zero.  Any
1929         # characters outside these 10 do not form a legal number for this
1930         # function.
1931         my $ord = ord(substr($string, $i, 1));
1932         my $digit = $ord - $zero_ord;
1933         return unless $digit >= 0 && $digit <= 9;
1934         $value = $value * 10 + $digit;
1935     }
1936
1937     return $value;
1938 }
1939
1940 =pod
1941
1942 =head2 B<prop_aliases()>
1943
1944     use Unicode::UCD 'prop_aliases';
1945
1946     my ($short_name, $full_name, @other_names) = prop_aliases("space");
1947     my $same_full_name = prop_aliases("Space");     # Scalar context
1948     my ($same_short_name) = prop_aliases("Space");  # gets 0th element
1949     print "The full name is $full_name\n";
1950     print "The short name is $short_name\n";
1951     print "The other aliases are: ", join(", ", @other_names), "\n";
1952
1953     prints:
1954     The full name is White_Space
1955     The short name is WSpace
1956     The other aliases are: Space
1957
1958 Most Unicode properties have several synonymous names.  Typically, there is at
1959 least a short name, convenient to type, and a long name that more fully
1960 describes the property, and hence is more easily understood.
1961
1962 If you know one name for a Unicode property, you can use C<prop_aliases> to find
1963 either the long name (when called in scalar context), or a list of all of the
1964 names, somewhat ordered so that the short name is in the 0th element, the long
1965 name in the next element, and any other synonyms are in the remaining
1966 elements, in no particular order.
1967
1968 The long name is returned in a form nicely capitalized, suitable for printing.
1969
1970 The input parameter name is loosely matched, which means that white space,
1971 hyphens, and underscores are ignored (except for the trailing underscore in
1972 the old_form grandfathered-in C<"L_">, which is better written as C<"LC">, and
1973 both of which mean C<General_Category=Cased Letter>).
1974
1975 If the name is unknown, C<undef> is returned (or an empty list in list
1976 context).  Note that Perl typically recognizes property names in regular
1977 expressions with an optional C<"Is_>" (with or without the underscore)
1978 prefixed to them, such as C<\p{isgc=punct}>.  This function does not recognize
1979 those in the input, returning C<undef>.  Nor are they included in the output
1980 as possible synonyms.
1981
1982 C<prop_aliases> does know about the Perl extensions to Unicode properties,
1983 such as C<Any> and C<XPosixAlpha>, and the single form equivalents to Unicode
1984 properties such as C<XDigit>, C<Greek>, C<In_Greek>, and C<Is_Greek>.  The
1985 final example demonstrates that the C<"Is_"> prefix is recognized for these
1986 extensions; it is needed to resolve ambiguities.  For example,
1987 C<prop_aliases('lc')> returns the list C<(lc, Lowercase_Mapping)>, but
1988 C<prop_aliases('islc')> returns C<(Is_LC, Cased_Letter)>.  This is
1989 because C<islc> is a Perl extension which is short for
1990 C<General_Category=Cased Letter>.  The lists returned for the Perl extensions
1991 will not include the C<"Is_"> prefix (whether or not the input had it) unless
1992 needed to resolve ambiguities, as shown in the C<"islc"> example, where the
1993 returned list had one element containing C<"Is_">, and the other without.
1994
1995 It is also possible for the reverse to happen:  C<prop_aliases('isc')> returns
1996 the list C<(isc, ISO_Comment)>; whereas C<prop_aliases('c')> returns
1997 C<(C, Other)> (the latter being a Perl extension meaning
1998 C<General_Category=Other>.
1999 L<perluniprops/Properties accessible through Unicode::UCD> lists the available
2000 forms, including which ones are discouraged from use.
2001
2002 Those discouraged forms are accepted as input to C<prop_aliases>, but are not
2003 returned in the lists.  C<prop_aliases('isL&')> and C<prop_aliases('isL_')>,
2004 which are old synonyms for C<"Is_LC"> and should not be used in new code, are
2005 examples of this.  These both return C<(Is_LC, Cased_Letter)>.  Thus this
2006 function allows you to take a discouraged form, and find its acceptable
2007 alternatives.  The same goes with single-form Block property equivalences.
2008 Only the forms that begin with C<"In_"> are not discouraged; if you pass
2009 C<prop_aliases> a discouraged form, you will get back the equivalent ones that
2010 begin with C<"In_">.  It will otherwise look like a new-style block name (see.
2011 L</Old-style versus new-style block names>).
2012
2013 C<prop_aliases> does not know about any user-defined properties, and will
2014 return C<undef> if called with one of those.  Likewise for Perl internal
2015 properties, with the exception of "Perl_Decimal_Digit" which it does know
2016 about (and which is documented below in L</prop_invmap()>).
2017
2018 =cut
2019
2020 # It may be that there are use cases where the discouraged forms should be
2021 # returned.  If that comes up, an optional boolean second parameter to the
2022 # function could be created, for example.
2023
2024 # These are created by mktables for this routine and stored in unicore/UCD.pl
2025 # where their structures are described.
2026 our %string_property_loose_to_name;
2027 our %ambiguous_names;
2028 our %loose_perlprop_to_name;
2029 our %prop_aliases;
2030
2031 sub prop_aliases ($) {
2032     my $prop = $_[0];
2033     return unless defined $prop;
2034
2035     require "unicore/UCD.pl";
2036     require "unicore/Heavy.pl";
2037     require "utf8_heavy.pl";
2038
2039     # The property name may be loosely or strictly matched; we don't know yet.
2040     # But both types use lower-case.
2041     $prop = lc $prop;
2042
2043     # It is loosely matched if its lower case isn't known to be strict.
2044     my $list_ref;
2045     if (! exists $utf8::stricter_to_file_of{$prop}) {
2046         my $loose = utf8::_loose_name($prop);
2047
2048         # There is a hash that converts from any loose name to its standard
2049         # form, mapping all synonyms for a  name to one name that can be used
2050         # as a key into another hash.  The whole concept is for memory
2051         # savings, as the second hash doesn't have to have all the
2052         # combinations.  Actually, there are two hashes that do the
2053         # converstion.  One is used in utf8_heavy.pl (stored in Heavy.pl) for
2054         # looking up properties matchable in regexes.  This function needs to
2055         # access string properties, which aren't available in regexes, so a
2056         # second conversion hash is made for them (stored in UCD.pl).  Look in
2057         # the string one now, as the rest can have an optional 'is' prefix,
2058         # which these don't.
2059         if (exists $string_property_loose_to_name{$loose}) {
2060
2061             # Convert to its standard loose name.
2062             $prop = $string_property_loose_to_name{$loose};
2063         }
2064         else {
2065             my $retrying = 0;   # bool.  ? Has an initial 'is' been stripped
2066         RETRY:
2067             if (exists $utf8::loose_property_name_of{$loose}
2068                 && (! $retrying
2069                     || ! exists $ambiguous_names{$loose}))
2070             {
2071                 # Found an entry giving the standard form.  We don't get here
2072                 # (in the test above) when we've stripped off an
2073                 # 'is' and the result is an ambiguous name.  That is because
2074                 # these are official Unicode properties (though Perl can have
2075                 # an optional 'is' prefix meaning the official property), and
2076                 # all ambiguous cases involve a Perl single-form extension
2077                 # for the gc, script, or block properties, and the stripped
2078                 # 'is' means that they mean one of those, and not one of
2079                 # these
2080                 $prop = $utf8::loose_property_name_of{$loose};
2081             }
2082             elsif (exists $loose_perlprop_to_name{$loose}) {
2083
2084                 # This hash is specifically for this function to list Perl
2085                 # extensions that aren't in the earlier hashes.  If there is
2086                 # only one element, the short and long names are identical.
2087                 # Otherwise the form is already in the same form as
2088                 # %prop_aliases, which is handled at the end of the function.
2089                 $list_ref = $loose_perlprop_to_name{$loose};
2090                 if (@$list_ref == 1) {
2091                     my @list = ($list_ref->[0], $list_ref->[0]);
2092                     $list_ref = \@list;
2093                 }
2094             }
2095             elsif (! exists $utf8::loose_to_file_of{$loose}) {
2096
2097                 # loose_to_file_of is a complete list of loose names.  If not
2098                 # there, the input is unknown.
2099                 return;
2100             }
2101             elsif ($loose =~ / [:=] /x) {
2102
2103                 # Here we found the name but not its aliases, so it has to
2104                 # exist.  Exclude property-value combinations.  (This shows up
2105                 # for something like ccc=vr which matches loosely, but is a
2106                 # synonym for ccc=9 which matches only strictly.
2107                 return;
2108             }
2109             else {
2110
2111                 # Here it has to exist, and isn't a property-value
2112                 # combination.  This means it must be one of the Perl
2113                 # single-form extensions.  First see if it is for a
2114                 # property-value combination in one of the following
2115                 # properties.
2116                 my @list;
2117                 foreach my $property ("gc", "script") {
2118                     @list = prop_value_aliases($property, $loose);
2119                     last if @list;
2120                 }
2121                 if (@list) {
2122
2123                     # Here, it is one of those property-value combination
2124                     # single-form synonyms.  There are ambiguities with some
2125                     # of these.  Check against the list for these, and adjust
2126                     # if necessary.
2127                     for my $i (0 .. @list -1) {
2128                         if (exists $ambiguous_names
2129                                    {utf8::_loose_name(lc $list[$i])})
2130                         {
2131                             # The ambiguity is resolved by toggling whether or
2132                             # not it has an 'is' prefix
2133                             $list[$i] =~ s/^Is_// or $list[$i] =~ s/^/Is_/;
2134                         }
2135                     }
2136                     return @list;
2137                 }
2138
2139                 # Here, it wasn't one of the gc or script single-form
2140                 # extensions.  It could be a block property single-form
2141                 # extension.  An 'in' prefix definitely means that, and should
2142                 # be looked up without the prefix.  However, starting in
2143                 # Unicode 6.1, we have to special case 'indic...', as there
2144                 # is a property that begins with that name.   We shouldn't
2145                 # strip the 'in' from that.   I'm (khw) generalizing this to
2146                 # 'indic' instead of the single property, because I suspect
2147                 # that others of this class may come along in the future.
2148                 # However, this could backfire and a block created whose name
2149                 # begins with 'dic...', and we would want to strip the 'in'.
2150                 # At which point this would have to be tweaked.
2151                 my $began_with_in = $loose =~ s/^in(?!dic)//;
2152                 @list = prop_value_aliases("block", $loose);
2153                 if (@list) {
2154                     map { $_ =~ s/^/In_/ } @list;
2155                     return @list;
2156                 }
2157
2158                 # Here still haven't found it.  The last opportunity for it
2159                 # being valid is only if it began with 'is'.  We retry without
2160                 # the 'is', setting a flag to that effect so that we don't
2161                 # accept things that begin with 'isis...'
2162                 if (! $retrying && ! $began_with_in && $loose =~ s/^is//) {
2163                     $retrying = 1;
2164                     goto RETRY;
2165                 }
2166
2167                 # Here, didn't find it.  Since it was in %loose_to_file_of, we
2168                 # should have been able to find it.
2169                 carp __PACKAGE__, "::prop_aliases: Unexpectedly could not find '$prop'.  Send bug report to perlbug\@perl.org";
2170                 return;
2171             }
2172         }
2173     }
2174
2175     if (! $list_ref) {
2176         # Here, we have set $prop to a standard form name of the input.  Look
2177         # it up in the structure created by mktables for this purpose, which
2178         # contains both strict and loosely matched properties.  Avoid
2179         # autovivifying.
2180         $list_ref = $prop_aliases{$prop} if exists $prop_aliases{$prop};
2181         return unless $list_ref;
2182     }
2183
2184     # The full name is in element 1.
2185     return $list_ref->[1] unless wantarray;
2186
2187     return @{_dclone $list_ref};
2188 }
2189
2190 =pod
2191
2192 =head2 B<prop_values()>
2193
2194     use Unicode::UCD 'prop_values';
2195
2196     print "AHex values are: ", join(", ", prop_values("AHex")),
2197                                "\n";
2198   prints:
2199     AHex values are: N, Y
2200
2201 Some Unicode properties have a restricted set of legal values.  For example,
2202 all binary properties are restricted to just C<true> or C<false>; and there
2203 are only a few dozen possible General Categories.  Use C<prop_values>
2204 to find out if a given property is one such, and if so, to get a list of the
2205 values:
2206
2207     print join ", ", prop_values("NFC_Quick_Check");
2208   prints:
2209     M, N, Y
2210
2211 If the property doesn't have such a restricted set, C<undef> is returned.
2212
2213 There are usually several synonyms for each possible value.  Use
2214 L</prop_value_aliases()> to access those.
2215
2216 Case, white space, hyphens, and underscores are ignored in the input property
2217 name (except for the trailing underscore in the old-form grandfathered-in
2218 general category property value C<"L_">, which is better written as C<"LC">).
2219
2220 If the property name is unknown, C<undef> is returned.  Note that Perl typically
2221 recognizes property names in regular expressions with an optional C<"Is_>"
2222 (with or without the underscore) prefixed to them, such as C<\p{isgc=punct}>.
2223 This function does not recognize those in the property parameter, returning
2224 C<undef>.
2225
2226 For the block property, new-style block names are returned (see
2227 L</Old-style versus new-style block names>).
2228
2229 C<prop_values> does not know about any user-defined properties, and
2230 will return C<undef> if called with one of those.
2231
2232 =cut
2233
2234 # These are created by mktables for this module and stored in unicore/UCD.pl
2235 # where their structures are described.
2236 our %loose_to_standard_value;
2237 our %prop_value_aliases;
2238
2239 sub prop_values ($) {
2240     my $prop = shift;
2241     return undef unless defined $prop;
2242
2243     require "unicore/UCD.pl";
2244     require "utf8_heavy.pl";
2245
2246     # Find the property name synonym that's used as the key in other hashes,
2247     # which is element 0 in the returned list.
2248     ($prop) = prop_aliases($prop);
2249     return undef if ! $prop;
2250     $prop = utf8::_loose_name(lc $prop);
2251
2252     # Here is a legal property.
2253     return undef unless exists $prop_value_aliases{$prop};
2254     my @return;
2255     foreach my $value_key (sort { lc $a cmp lc $b }
2256                             keys %{$prop_value_aliases{$prop}})
2257     {
2258         push @return, $prop_value_aliases{$prop}{$value_key}[0];
2259     }
2260     return @return;
2261 }
2262
2263 =pod
2264
2265 =head2 B<prop_value_aliases()>
2266
2267     use Unicode::UCD 'prop_value_aliases';
2268
2269     my ($short_name, $full_name, @other_names)
2270                                    = prop_value_aliases("Gc", "Punct");
2271     my $same_full_name = prop_value_aliases("Gc", "P");   # Scalar cntxt
2272     my ($same_short_name) = prop_value_aliases("Gc", "P"); # gets 0th
2273                                                            # element
2274     print "The full name is $full_name\n";
2275     print "The short name is $short_name\n";
2276     print "The other aliases are: ", join(", ", @other_names), "\n";
2277
2278   prints:
2279     The full name is Punctuation
2280     The short name is P
2281     The other aliases are: Punct
2282
2283 Some Unicode properties have a restricted set of legal values.  For example,
2284 all binary properties are restricted to just C<true> or C<false>; and there
2285 are only a few dozen possible General Categories.
2286
2287 You can use L</prop_values()> to find out if a given property is one which has
2288 a restricted set of values, and if so, what those values are.  But usually
2289 each value actually has several synonyms.  For example, in Unicode binary
2290 properties, I<truth> can be represented by any of the strings "Y", "Yes", "T",
2291 or "True"; and the General Category "Punctuation" by that string, or "Punct",
2292 or simply "P".
2293
2294 Like property names, there is typically at least a short name for each such
2295 property-value, and a long name.  If you know any name of the property-value
2296 (which you can get by L</prop_values()>, you can use C<prop_value_aliases>()
2297 to get the long name (when called in scalar context), or a list of all the
2298 names, with the short name in the 0th element, the long name in the next
2299 element, and any other synonyms in the remaining elements, in no particular
2300 order, except that any all-numeric synonyms will be last.
2301
2302 The long name is returned in a form nicely capitalized, suitable for printing.
2303
2304 Case, white space, hyphens, and underscores are ignored in the input parameters
2305 (except for the trailing underscore in the old-form grandfathered-in general
2306 category property value C<"L_">, which is better written as C<"LC">).
2307
2308 If either name is unknown, C<undef> is returned.  Note that Perl typically
2309 recognizes property names in regular expressions with an optional C<"Is_>"
2310 (with or without the underscore) prefixed to them, such as C<\p{isgc=punct}>.
2311 This function does not recognize those in the property parameter, returning
2312 C<undef>.
2313
2314 If called with a property that doesn't have synonyms for its values, it
2315 returns the input value, possibly normalized with capitalization and
2316 underscores, but not necessarily checking that the input value is valid.
2317
2318 For the block property, new-style block names are returned (see
2319 L</Old-style versus new-style block names>).
2320
2321 To find the synonyms for single-forms, such as C<\p{Any}>, use
2322 L</prop_aliases()> instead.
2323
2324 C<prop_value_aliases> does not know about any user-defined properties, and
2325 will return C<undef> if called with one of those.
2326
2327 =cut
2328
2329 sub prop_value_aliases ($$) {
2330     my ($prop, $value) = @_;
2331     return unless defined $prop && defined $value;
2332
2333     require "unicore/UCD.pl";
2334     require "utf8_heavy.pl";
2335
2336     # Find the property name synonym that's used as the key in other hashes,
2337     # which is element 0 in the returned list.
2338     ($prop) = prop_aliases($prop);
2339     return if ! $prop;
2340     $prop = utf8::_loose_name(lc $prop);
2341
2342     # Here is a legal property, but the hash below (created by mktables for
2343     # this purpose) only knows about the properties that have a very finite
2344     # number of potential values, that is not ones whose value could be
2345     # anything, like most (if not all) string properties.  These don't have
2346     # synonyms anyway.  Simply return the input.  For example, there is no
2347     # synonym for ('Uppercase_Mapping', A').
2348     if (! exists $prop_value_aliases{$prop}) {
2349
2350         # Here, we have a legal property, but an unknown value.  Since the
2351         # property is legal, if it isn't in the prop_aliases hash, it must be
2352         # a Perl-extension All perl extensions are binary, hence are
2353         # enumerateds, which means that we know that the input unknown value
2354         # is illegal.
2355         return if ! exists $Unicode::UCD::prop_aliases{$prop};
2356
2357         # Otherwise, we assume it's valid, as documented.
2358         return $value;
2359     }
2360
2361     # The value name may be loosely or strictly matched; we don't know yet.
2362     # But both types use lower-case.
2363     $value = lc $value;
2364
2365     # If the name isn't found under loose matching, it certainly won't be
2366     # found under strict
2367     my $loose_value = utf8::_loose_name($value);
2368     return unless exists $loose_to_standard_value{"$prop=$loose_value"};
2369
2370     # Similarly if the combination under loose matching doesn't exist, it
2371     # won't exist under strict.
2372     my $standard_value = $loose_to_standard_value{"$prop=$loose_value"};
2373     return unless exists $prop_value_aliases{$prop}{$standard_value};
2374
2375     # Here we did find a combination under loose matching rules.  But it could
2376     # be that is a strict property match that shouldn't have matched.
2377     # %prop_value_aliases is set up so that the strict matches will appear as
2378     # if they were in loose form.  Thus, if the non-loose version is legal,
2379     # we're ok, can skip the further check.
2380     if (! exists $utf8::stricter_to_file_of{"$prop=$value"}
2381
2382         # We're also ok and skip the further check if value loosely matches.
2383         # mktables has verified that no strict name under loose rules maps to
2384         # an existing loose name.  This code relies on the very limited
2385         # circumstances that strict names can be here.  Strict name matching
2386         # happens under two conditions:
2387         # 1) when the name begins with an underscore.  But this function
2388         #    doesn't accept those, and %prop_value_aliases doesn't have
2389         #    them.
2390         # 2) When the values are numeric, in which case we need to look
2391         #    further, but their squeezed-out loose values will be in
2392         #    %stricter_to_file_of
2393         && exists $utf8::stricter_to_file_of{"$prop=$loose_value"})
2394     {
2395         # The only thing that's legal loosely under strict is that can have an
2396         # underscore between digit pairs XXX
2397         while ($value =~ s/(\d)_(\d)/$1$2/g) {}
2398         return unless exists $utf8::stricter_to_file_of{"$prop=$value"};
2399     }
2400
2401     # Here, we know that the combination exists.  Return it.
2402     my $list_ref = $prop_value_aliases{$prop}{$standard_value};
2403     if (@$list_ref > 1) {
2404         # The full name is in element 1.
2405         return $list_ref->[1] unless wantarray;
2406
2407         return @{_dclone $list_ref};
2408     }
2409
2410     return $list_ref->[0] unless wantarray;
2411
2412     # Only 1 element means that it repeats
2413     return ( $list_ref->[0], $list_ref->[0] );
2414 }
2415
2416 # All 1 bits is the largest possible UV.
2417 $Unicode::UCD::MAX_CP = ~0;
2418
2419 =pod
2420
2421 =head2 B<prop_invlist()>
2422
2423 C<prop_invlist> returns an inversion list (described below) that defines all the
2424 code points for the binary Unicode property (or "property=value" pair) given
2425 by the input parameter string:
2426
2427  use feature 'say';
2428  use Unicode::UCD 'prop_invlist';
2429  say join ", ", prop_invlist("Any");
2430
2431  prints:
2432  0, 1114112
2433
2434 If the input is unknown C<undef> is returned in scalar context; an empty-list
2435 in list context.  If the input is known, the number of elements in
2436 the list is returned if called in scalar context.
2437
2438 L<perluniprops|perluniprops/Properties accessible through \p{} and \P{}> gives
2439 the list of properties that this function accepts, as well as all the possible
2440 forms for them (including with the optional "Is_" prefixes).  (Except this
2441 function doesn't accept any Perl-internal properties, some of which are listed
2442 there.) This function uses the same loose or tighter matching rules for
2443 resolving the input property's name as is done for regular expressions.  These
2444 are also specified in L<perluniprops|perluniprops/Properties accessible
2445 through \p{} and \P{}>.  Examples of using the "property=value" form are:
2446
2447  say join ", ", prop_invlist("Script=Shavian");
2448
2449  prints:
2450  66640, 66688
2451
2452  say join ", ", prop_invlist("ASCII_Hex_Digit=No");
2453
2454  prints:
2455  0, 48, 58, 65, 71, 97, 103
2456
2457  say join ", ", prop_invlist("ASCII_Hex_Digit=Yes");
2458
2459  prints:
2460  48, 58, 65, 71, 97, 103
2461
2462 Inversion lists are a compact way of specifying Unicode property-value
2463 definitions.  The 0th item in the list is the lowest code point that has the
2464 property-value.  The next item (item [1]) is the lowest code point beyond that
2465 one that does NOT have the property-value.  And the next item beyond that
2466 ([2]) is the lowest code point beyond that one that does have the
2467 property-value, and so on.  Put another way, each element in the list gives
2468 the beginning of a range that has the property-value (for even numbered
2469 elements), or doesn't have the property-value (for odd numbered elements).
2470 The name for this data structure stems from the fact that each element in the
2471 list toggles (or inverts) whether the corresponding range is or isn't on the
2472 list.
2473
2474 In the final example above, the first ASCII Hex digit is code point 48, the
2475 character "0", and all code points from it through 57 (a "9") are ASCII hex
2476 digits.  Code points 58 through 64 aren't, but 65 (an "A") through 70 (an "F")
2477 are, as are 97 ("a") through 102 ("f").  103 starts a range of code points
2478 that aren't ASCII hex digits.  That range extends to infinity, which on your
2479 computer can be found in the variable C<$Unicode::UCD::MAX_CP>.  (This
2480 variable is as close to infinity as Perl can get on your platform, and may be
2481 too high for some operations to work; you may wish to use a smaller number for
2482 your purposes.)
2483
2484 Note that the inversion lists returned by this function can possibly include
2485 non-Unicode code points, that is anything above 0x10FFFF.  Unicode properties
2486 are not defined on such code points.  You might wish to change the output to
2487 not include these.  Simply add 0x110000 at the end of the non-empty returned
2488 list if it isn't already that value; and pop that value if it is; like:
2489
2490  my @list = prop_invlist("foo");
2491  if (@list) {
2492      if ($list[-1] == 0x110000) {
2493          pop @list;  # Defeat the turning on for above Unicode
2494      }
2495      else {
2496          push @list, 0x110000; # Turn off for above Unicode
2497      }
2498  }
2499
2500 It is a simple matter to expand out an inversion list to a full list of all
2501 code points that have the property-value:
2502
2503  my @invlist = prop_invlist($property_name);
2504  die "empty" unless @invlist;
2505  my @full_list;
2506  for (my $i = 0; $i < @invlist; $i += 2) {
2507     my $upper = ($i + 1) < @invlist
2508                 ? $invlist[$i+1] - 1      # In range
2509                 : $Unicode::UCD::MAX_CP;  # To infinity.  You may want
2510                                           # to stop much much earlier;
2511                                           # going this high may expose
2512                                           # perl deficiencies with very
2513                                           # large numbers.
2514     for my $j ($invlist[$i] .. $upper) {
2515         push @full_list, $j;
2516     }
2517  }
2518
2519 C<prop_invlist> does not know about any user-defined nor Perl internal-only
2520 properties, and will return C<undef> if called with one of those.
2521
2522 The L</search_invlist()> function is provided for finding a code point within
2523 an inversion list.
2524
2525 =cut
2526
2527 # User-defined properties could be handled with some changes to utf8_heavy.pl;
2528 # and implementing here of dealing with EXTRAS.  If done, consideration should
2529 # be given to the fact that the user subroutine could return different results
2530 # with each call; security issues need to be thought about.
2531
2532 # These are created by mktables for this routine and stored in unicore/UCD.pl
2533 # where their structures are described.
2534 our %loose_defaults;
2535 our $MAX_UNICODE_CODEPOINT;
2536
2537 sub prop_invlist ($;$) {
2538     my $prop = $_[0];
2539
2540     # Undocumented way to get at Perl internal properties; it may be changed
2541     # or removed without notice at any time.
2542     my $internal_ok = defined $_[1] && $_[1] eq '_perl_core_internal_ok';
2543
2544     return if ! defined $prop;
2545
2546     require "utf8_heavy.pl";
2547
2548     # Warnings for these are only for regexes, so not applicable to us
2549     no warnings 'deprecated';
2550
2551     # Get the swash definition of the property-value.
2552     my $swash = utf8::SWASHNEW(__PACKAGE__, $prop, undef, 1, 0);
2553
2554     # Fail if not found, or isn't a boolean property-value, or is a
2555     # user-defined property, or is internal-only.
2556     return if ! $swash
2557               || ref $swash eq ""
2558               || $swash->{'BITS'} != 1
2559               || $swash->{'USER_DEFINED'}
2560               || (! $internal_ok && $prop =~ /^\s*_/);
2561
2562     if ($swash->{'EXTRAS'}) {
2563         carp __PACKAGE__, "::prop_invlist: swash returned for $prop unexpectedly has EXTRAS magic";
2564         return;
2565     }
2566     if ($swash->{'SPECIALS'}) {
2567         carp __PACKAGE__, "::prop_invlist: swash returned for $prop unexpectedly has SPECIALS magic";
2568         return;
2569     }
2570
2571     my @invlist;
2572
2573     if ($swash->{'LIST'} =~ /^V/) {
2574
2575         # A 'V' as the first character marks the input as already an inversion
2576         # list, in which case, all we need to do is put the remaining lines
2577         # into our array.
2578         @invlist = split "\n", $swash->{'LIST'} =~ s/ \s* (?: \# .* )? $ //xmgr;
2579         shift @invlist;
2580     }
2581     else {
2582         # The input lines look like:
2583         # 0041\t005A   # [26]
2584         # 005F
2585
2586         # Split into lines, stripped of trailing comments
2587         foreach my $range (split "\n",
2588                               $swash->{'LIST'} =~ s/ \s* (?: \# .* )? $ //xmgr)
2589         {
2590             # And find the beginning and end of the range on the line
2591             my ($hex_begin, $hex_end) = split "\t", $range;
2592             my $begin = hex $hex_begin;
2593
2594             # If the new range merely extends the old, we remove the marker
2595             # created the last time through the loop for the old's end, which
2596             # causes the new one's end to be used instead.
2597             if (@invlist && $begin == $invlist[-1]) {
2598                 pop @invlist;
2599             }
2600             else {
2601                 # Add the beginning of the range
2602                 push @invlist, $begin;
2603             }
2604
2605             if (defined $hex_end) { # The next item starts with the code point 1
2606                                     # beyond the end of the range.
2607                 no warnings 'portable';
2608                 my $end = hex $hex_end;
2609                 last if $end == $Unicode::UCD::MAX_CP;
2610                 push @invlist, $end + 1;
2611             }
2612             else {  # No end of range, is a single code point.
2613                 push @invlist, $begin + 1;
2614             }
2615         }
2616     }
2617
2618     # Could need to be inverted: add or subtract a 0 at the beginning of the
2619     # list.
2620     if ($swash->{'INVERT_IT'}) {
2621         if (@invlist && $invlist[0] == 0) {
2622             shift @invlist;
2623         }
2624         else {
2625             unshift @invlist, 0;
2626         }
2627     }
2628
2629     return @invlist;
2630 }
2631
2632 =pod
2633
2634 =head2 B<prop_invmap()>
2635
2636  use Unicode::UCD 'prop_invmap';
2637  my ($list_ref, $map_ref, $format, $default)
2638                                       = prop_invmap("General Category");
2639
2640 C<prop_invmap> is used to get the complete mapping definition for a property,
2641 in the form of an inversion map.  An inversion map consists of two parallel
2642 arrays.  One is an ordered list of code points that mark range beginnings, and
2643 the other gives the value (or mapping) that all code points in the
2644 corresponding range have.
2645
2646 C<prop_invmap> is called with the name of the desired property.  The name is
2647 loosely matched, meaning that differences in case, white-space, hyphens, and
2648 underscores are not meaningful (except for the trailing underscore in the
2649 old-form grandfathered-in property C<"L_">, which is better written as C<"LC">,
2650 or even better, C<"Gc=LC">).
2651
2652 Many Unicode properties have more than one name (or alias).  C<prop_invmap>
2653 understands all of these, including Perl extensions to them.  Ambiguities are
2654 resolved as described above for L</prop_aliases()>.  The Perl internal
2655 property "Perl_Decimal_Digit, described below, is also accepted.  An empty
2656 list is returned if the property name is unknown.
2657 See L<perluniprops/Properties accessible through Unicode::UCD> for the
2658 properties acceptable as inputs to this function.
2659
2660 It is a fatal error to call this function except in list context.
2661
2662 In addition to the two arrays that form the inversion map, C<prop_invmap>
2663 returns two other values; one is a scalar that gives some details as to the
2664 format of the entries of the map array; the other is a default value, useful
2665 in maps whose format name begins with the letter C<"a">, as described
2666 L<below in its subsection|/a>; and for specialized purposes, such as
2667 converting to another data structure, described at the end of this main
2668 section.
2669
2670 This means that C<prop_invmap> returns a 4 element list.  For example,
2671
2672  my ($blocks_ranges_ref, $blocks_maps_ref, $format, $default)
2673                                                  = prop_invmap("Block");
2674
2675 In this call, the two arrays will be populated as shown below (for Unicode
2676 6.0):
2677
2678  Index  @blocks_ranges  @blocks_maps
2679    0        0x0000      Basic Latin
2680    1        0x0080      Latin-1 Supplement
2681    2        0x0100      Latin Extended-A
2682    3        0x0180      Latin Extended-B
2683    4        0x0250      IPA Extensions
2684    5        0x02B0      Spacing Modifier Letters
2685    6        0x0300      Combining Diacritical Marks
2686    7        0x0370      Greek and Coptic
2687    8        0x0400      Cyrillic
2688   ...
2689  233        0x2B820     No_Block
2690  234        0x2F800     CJK Compatibility Ideographs Supplement
2691  235        0x2FA20     No_Block
2692  236        0xE0000     Tags
2693  237        0xE0080     No_Block
2694  238        0xE0100     Variation Selectors Supplement
2695  239        0xE01F0     No_Block
2696  240        0xF0000     Supplementary Private Use Area-A
2697  241        0x100000    Supplementary Private Use Area-B
2698  242        0x110000    No_Block
2699
2700 The first line (with Index [0]) means that the value for code point 0 is "Basic
2701 Latin".  The entry "0x0080" in the @blocks_ranges column in the second line
2702 means that the value from the first line, "Basic Latin", extends to all code
2703 points in the range from 0 up to but not including 0x0080, that is, through
2704 127.  In other words, the code points from 0 to 127 are all in the "Basic
2705 Latin" block.  Similarly, all code points in the range from 0x0080 up to (but
2706 not including) 0x0100 are in the block named "Latin-1 Supplement", etc.
2707 (Notice that the return is the old-style block names; see L</Old-style versus
2708 new-style block names>).
2709
2710 The final line (with Index [242]) means that the value for all code points above
2711 the legal Unicode maximum code point have the value "No_Block", which is the
2712 term Unicode uses for a non-existing block.
2713
2714 The arrays completely specify the mappings for all possible code points.
2715 The final element in an inversion map returned by this function will always be
2716 for the range that consists of all the code points that aren't legal Unicode,
2717 but that are expressible on the platform.  (That is, it starts with code point
2718 0x110000, the first code point above the legal Unicode maximum, and extends to
2719 infinity.) The value for that range will be the same that any typical
2720 unassigned code point has for the specified property.  (Certain unassigned
2721 code points are not "typical"; for example the non-character code points, or
2722 those in blocks that are to be written right-to-left.  The above-Unicode
2723 range's value is not based on these atypical code points.)  It could be argued
2724 that, instead of treating these as unassigned Unicode code points, the value
2725 for this range should be C<undef>.  If you wish, you can change the returned
2726 arrays accordingly.
2727
2728 The maps for almost all properties are simple scalars that should be
2729 interpreted as-is.
2730 These values are those given in the Unicode-supplied data files, which may be
2731 inconsistent as to capitalization and as to which synonym for a property-value
2732 is given.  The results may be normalized by using the L</prop_value_aliases()>
2733 function.
2734
2735 There are exceptions to the simple scalar maps.  Some properties have some
2736 elements in their map list that are themselves lists of scalars; and some
2737 special strings are returned that are not to be interpreted as-is.  Element
2738 [2] (placed into C<$format> in the example above) of the returned four element
2739 list tells you if the map has any of these special elements or not, as follows:
2740
2741 =over
2742
2743 =item B<C<s>>
2744
2745 means all the elements of the map array are simple scalars, with no special
2746 elements.  Almost all properties are like this, like the C<block> example
2747 above.
2748
2749 =item B<C<sl>>
2750
2751 means that some of the map array elements have the form given by C<"s">, and
2752 the rest are lists of scalars.  For example, here is a portion of the output
2753 of calling C<prop_invmap>() with the "Script Extensions" property:
2754
2755  @scripts_ranges  @scripts_maps
2756       ...
2757       0x0953      Devanagari
2758       0x0964      [ Bengali, Devanagari, Gurumukhi, Oriya ]
2759       0x0966      Devanagari
2760       0x0970      Common
2761
2762 Here, the code points 0x964 and 0x965 are both used in Bengali,
2763 Devanagari, Gurmukhi, and Oriya, but no other scripts.
2764
2765 The Name_Alias property is also of this form.  But each scalar consists of two
2766 components:  1) the name, and 2) the type of alias this is.  They are
2767 separated by a colon and a space.  In Unicode 6.1, there are several alias types:
2768
2769 =over
2770
2771 =item C<correction>
2772
2773 indicates that the name is a corrected form for the
2774 original name (which remains valid) for the same code point.
2775
2776 =item C<control>
2777
2778 adds a new name for a control character.
2779
2780 =item C<alternate>
2781
2782 is an alternate name for a character
2783
2784 =item C<figment>
2785
2786 is a name for a character that has been documented but was never in any
2787 actual standard.
2788
2789 =item C<abbreviation>
2790
2791 is a common abbreviation for a character
2792
2793 =back
2794
2795 The lists are ordered (roughly) so the most preferred names come before less
2796 preferred ones.
2797
2798 For example,
2799
2800  @aliases_ranges        @alias_maps
2801     ...
2802     0x009E        [ 'PRIVACY MESSAGE: control', 'PM: abbreviation' ]
2803     0x009F        [ 'APPLICATION PROGRAM COMMAND: control',
2804                     'APC: abbreviation'
2805                   ]
2806     0x00A0        'NBSP: abbreviation'
2807     0x00A1        ""
2808     0x00AD        'SHY: abbreviation'
2809     0x00AE        ""
2810     0x01A2        'LATIN CAPITAL LETTER GHA: correction'
2811     0x01A3        'LATIN SMALL LETTER GHA: correction'
2812     0x01A4        ""
2813     ...
2814
2815 A map to the empty string means that there is no alias defined for the code
2816 point.
2817
2818 =item B<C<a>>
2819
2820 is like C<"s"> in that all the map array elements are scalars, but here they are
2821 restricted to all being integers, and some have to be adjusted (hence the name
2822 C<"a">) to get the correct result.  For example, in:
2823
2824  my ($uppers_ranges_ref, $uppers_maps_ref, $format, $default)
2825                           = prop_invmap("Simple_Uppercase_Mapping");
2826
2827 the returned arrays look like this:
2828
2829  @$uppers_ranges_ref    @$uppers_maps_ref   Note
2830        0                      0
2831       97                     65          'a' maps to 'A', b => B ...
2832      123                      0
2833      181                    924          MICRO SIGN => Greek Cap MU
2834      182                      0
2835      ...
2836
2837 and C<$default> is 0.
2838
2839 Let's start with the second line.  It says that the uppercase of code point 97
2840 is 65; or C<uc("a")> == "A".  But the line is for the entire range of code
2841 points 97 through 122.  To get the mapping for any code point in this range,
2842 you take the offset it has from the beginning code point of the range, and add
2843 that to the mapping for that first code point.  So, the mapping for 122 ("z")
2844 is derived by taking the offset of 122 from 97 (=25) and adding that to 65,
2845 yielding 90 ("z").  Likewise for everything in between.
2846
2847 Requiring this simple adjustment allows the returned arrays to be
2848 significantly smaller than otherwise, up to a factor of 10, speeding up
2849 searching through them.
2850
2851 Ranges that map to C<$default>, C<"0">, behave somewhat differently.  For
2852 these, each code point maps to itself.  So, in the first line in the example,
2853 S<C<ord(uc(chr(0)))>> is 0, S<C<ord(uc(chr(1)))>> is 1, ..
2854 S<C<ord(uc(chr(96)))>> is 96.
2855
2856 =item B<C<al>>
2857
2858 means that some of the map array elements have the form given by C<"a">, and
2859 the rest are ordered lists of code points.
2860 For example, in:
2861
2862  my ($uppers_ranges_ref, $uppers_maps_ref, $format, $default)
2863                                  = prop_invmap("Uppercase_Mapping");
2864
2865 the returned arrays look like this:
2866
2867  @$uppers_ranges_ref    @$uppers_maps_ref
2868        0                      0
2869       97                     65
2870      123                      0
2871      181                    924
2872      182                      0
2873      ...
2874     0x0149              [ 0x02BC 0x004E ]
2875     0x014A                    0
2876     0x014B                  330
2877      ...
2878
2879 This is the full Uppercase_Mapping property (as opposed to the
2880 Simple_Uppercase_Mapping given in the example for format C<"a">).  The only
2881 difference between the two in the ranges shown is that the code point at
2882 0x0149 (LATIN SMALL LETTER N PRECEDED BY APOSTROPHE) maps to a string of two
2883 characters, 0x02BC (MODIFIER LETTER APOSTROPHE) followed by 0x004E (LATIN
2884 CAPITAL LETTER N).
2885
2886 No adjustments are needed to entries that are references to arrays; each such
2887 entry will have exactly one element in its range, so the offset is always 0.
2888
2889 The fourth (index [3]) element (C<$default>) in the list returned for this
2890 format is 0.
2891
2892 =item B<C<ae>>
2893
2894 This is like C<"a">, but some elements are the empty string, and should not be
2895 adjusted.
2896 The one internal Perl property accessible by C<prop_invmap> is of this type:
2897 "Perl_Decimal_Digit" returns an inversion map which gives the numeric values
2898 that are represented by the Unicode decimal digit characters.  Characters that
2899 don't represent decimal digits map to the empty string, like so:
2900
2901  @digits    @values
2902  0x0000       ""
2903  0x0030        0
2904  0x003A:      ""
2905  0x0660:       0
2906  0x066A:      ""
2907  0x06F0:       0
2908  0x06FA:      ""
2909  0x07C0:       0
2910  0x07CA:      ""
2911  0x0966:       0
2912  ...
2913
2914 This means that the code points from 0 to 0x2F do not represent decimal digits;
2915 the code point 0x30 (DIGIT ZERO) represents 0;  code point 0x31, (DIGIT ONE),
2916 represents 0+1-0 = 1; ... code point 0x39, (DIGIT NINE), represents 0+9-0 = 9;
2917 ... code points 0x3A through 0x65F do not represent decimal digits; 0x660
2918 (ARABIC-INDIC DIGIT ZERO), represents 0; ... 0x07C1 (NKO DIGIT ONE),
2919 represents 0+1-0 = 1 ...
2920
2921 The fourth (index [3]) element (C<$default>) in the list returned for this
2922 format is the empty string.
2923
2924 =item B<C<ale>>
2925
2926 is a combination of the C<"al"> type and the C<"ae"> type.  Some of
2927 the map array elements have the forms given by C<"al">, and
2928 the rest are the empty string.  The property C<NFKC_Casefold> has this form.
2929 An example slice is:
2930
2931  @$ranges_ref  @$maps_ref         Note
2932     ...
2933    0x00AA       97                FEMININE ORDINAL INDICATOR => 'a'
2934    0x00AB        0
2935    0x00AD                         SOFT HYPHEN => ""
2936    0x00AE        0
2937    0x00AF     [ 0x0020, 0x0304 ]  MACRON => SPACE . COMBINING MACRON
2938    0x00B0        0
2939    ...
2940
2941 The fourth (index [3]) element (C<$default>) in the list returned for this
2942 format is 0.
2943
2944 =item B<C<ar>>
2945
2946 means that all the elements of the map array are either rational numbers or
2947 the string C<"NaN">, meaning "Not a Number".  A rational number is either an
2948 integer, or two integers separated by a solidus (C<"/">).  The second integer
2949 represents the denominator of the division implied by the solidus, and is
2950 actually always positive, so it is guaranteed not to be 0 and to not be
2951 signed.  When the element is a plain integer (without the
2952 solidus), it may need to be adjusted to get the correct value by adding the
2953 offset, just as other C<"a"> properties.  No adjustment is needed for
2954 fractions, as the range is guaranteed to have just a single element, and so
2955 the offset is always 0.
2956
2957 If you want to convert the returned map to entirely scalar numbers, you
2958 can use something like this:
2959
2960  my ($invlist_ref, $invmap_ref, $format) = prop_invmap($property);
2961  if ($format && $format eq "ar") {
2962      map { $_ = eval $_ if $_ ne 'NaN' } @$map_ref;
2963  }
2964
2965 Here's some entries from the output of the property "Nv", which has format
2966 C<"ar">.
2967
2968  @numerics_ranges  @numerics_maps       Note
2969         0x00           "NaN"
2970         0x30             0           DIGIT 0 .. DIGIT 9
2971         0x3A           "NaN"
2972         0xB2             2           SUPERSCRIPTs 2 and 3
2973         0xB4           "NaN"
2974         0xB9             1           SUPERSCRIPT 1
2975         0xBA           "NaN"
2976         0xBC            1/4          VULGAR FRACTION 1/4
2977         0xBD            1/2          VULGAR FRACTION 1/2
2978         0xBE            3/4          VULGAR FRACTION 3/4
2979         0xBF           "NaN"
2980         0x660            0           ARABIC-INDIC DIGIT ZERO .. NINE
2981         0x66A          "NaN"
2982
2983 The fourth (index [3]) element (C<$default>) in the list returned for this
2984 format is C<"NaN">.
2985
2986 =item B<C<n>>
2987
2988 means the Name property.  All the elements of the map array are simple
2989 scalars, but some of them contain special strings that require more work to
2990 get the actual name.
2991
2992 Entries such as:
2993
2994  CJK UNIFIED IDEOGRAPH-<code point>
2995
2996 mean that the name for the code point is "CJK UNIFIED IDEOGRAPH-"
2997 with the code point (expressed in hexadecimal) appended to it, like "CJK
2998 UNIFIED IDEOGRAPH-3403" (similarly for S<C<CJK COMPATIBILITY IDEOGRAPH-E<lt>code
2999 pointE<gt>>>).
3000
3001 Also, entries like
3002
3003  <hangul syllable>
3004
3005 means that the name is algorithmically calculated.  This is easily done by
3006 the function L<charnames/charnames::viacode(code)>.
3007
3008 Note that for control characters (C<Gc=cc>), Unicode's data files have the
3009 string "C<E<lt>controlE<gt>>", but the real name of each of these characters is the empty
3010 string.  This function returns that real name, the empty string.  (There are
3011 names for these characters, but they are considered aliases, not the Name
3012 property name, and are contained in the C<Name_Alias> property.)
3013
3014 =item B<C<ad>>
3015
3016 means the Decomposition_Mapping property.  This property is like C<"al">
3017 properties, except that one of the scalar elements is of the form:
3018
3019  <hangul syllable>
3020
3021 This signifies that this entry should be replaced by the decompositions for
3022 all the code points whose decomposition is algorithmically calculated.  (All
3023 of them are currently in one range and no others outside the range are likely
3024 to ever be added to Unicode; the C<"n"> format
3025 has this same entry.)  These can be generated via the function
3026 L<Unicode::Normalize::NFD()|Unicode::Normalize>.
3027
3028 Note that the mapping is the one that is specified in the Unicode data files,
3029 and to get the final decomposition, it may need to be applied recursively.
3030
3031 The fourth (index [3]) element (C<$default>) in the list returned for this
3032 format is 0.
3033
3034 =back
3035
3036 Note that a format begins with the letter "a" if and only the property it is
3037 for requires adjustments by adding the offsets in multi-element ranges.  For
3038 all these properties, an entry should be adjusted only if the map is a scalar
3039 which is an integer.  That is, it must match the regular expression:
3040
3041     / ^ -? \d+ $ /xa
3042
3043 Further, the first element in a range never needs adjustment, as the
3044 adjustment would be just adding 0.
3045
3046 A binary search such as that provided by L</search_invlist()>, can be used to
3047 quickly find a code point in the inversion list, and hence its corresponding
3048 mapping.
3049
3050 The final, fourth element (index [3], assigned to C<$default> in the "block"
3051 example) in the four element list returned by this function is used with the
3052 C<"a"> format types; it may also be useful for applications
3053 that wish to convert the returned inversion map data structure into some
3054 other, such as a hash.  It gives the mapping that most code points map to
3055 under the property.  If you establish the convention that any code point not
3056 explicitly listed in your data structure maps to this value, you can
3057 potentially make your data structure much smaller.  As you construct your data
3058 structure from the one returned by this function, simply ignore those ranges
3059 that map to this value.  For example, to
3060 convert to the data structure searchable by L</charinrange()>, you can follow
3061 this recipe for properties that don't require adjustments:
3062
3063  my ($list_ref, $map_ref, $format, $default) = prop_invmap($property);
3064  my @range_list;
3065
3066  # Look at each element in the list, but the -2 is needed because we
3067  # look at $i+1 in the loop, and the final element is guaranteed to map
3068  # to $default by prop_invmap(), so we would skip it anyway.
3069  for my $i (0 .. @$list_ref - 2) {
3070     next if $map_ref->[$i] eq $default;
3071     push @range_list, [ $list_ref->[$i],
3072                         $list_ref->[$i+1],
3073                         $map_ref->[$i]
3074                       ];
3075  }
3076
3077  print charinrange(\@range_list, $code_point), "\n";
3078
3079 With this, C<charinrange()> will return C<undef> if its input code point maps
3080 to C<$default>.  You can avoid this by omitting the C<next> statement, and adding
3081 a line after the loop to handle the final element of the inversion map.
3082
3083 Similarly, this recipe can be used for properties that do require adjustments:
3084
3085  for my $i (0 .. @$list_ref - 2) {
3086     next if $map_ref->[$i] eq $default;
3087
3088     # prop_invmap() guarantees that if the mapping is to an array, the
3089     # range has just one element, so no need to worry about adjustments.
3090     if (ref $map_ref->[$i]) {
3091         push @range_list,
3092                    [ $list_ref->[$i], $list_ref->[$i], $map_ref->[$i] ];
3093     }
3094     else {  # Otherwise each element is actually mapped to a separate
3095             # value, so the range has to be split into single code point
3096             # ranges.
3097
3098         my $adjustment = 0;
3099
3100         # For each code point that gets mapped to something...
3101         for my $j ($list_ref->[$i] .. $list_ref->[$i+1] -1 ) {
3102
3103             # ... add a range consisting of just it mapping to the
3104             # original plus the adjustment, which is incremented for the
3105             # next time through the loop, as the offset increases by 1
3106             # for each element in the range
3107             push @range_list,
3108                              [ $j, $j, $map_ref->[$i] + $adjustment++ ];
3109         }
3110     }
3111  }
3112
3113 Note that the inversion maps returned for the C<Case_Folding> and
3114 C<Simple_Case_Folding> properties do not include the Turkic-locale mappings.
3115 Use L</casefold()> for these.
3116
3117 C<prop_invmap> does not know about any user-defined properties, and will
3118 return C<undef> if called with one of those.
3119
3120 The returned values for the Perl extension properties, such as C<Any> and
3121 C<Greek> are somewhat misleading.  The values are either C<"Y"> or C<"N>".
3122 All Unicode properties are bipartite, so you can actually use the C<"Y"> or
3123 C<"N>" in a Perl regular rexpression for these, like C<qr/\p{ID_Start=Y/}> or
3124 C<qr/\p{Upper=N/}>.  But the Perl extensions aren't specified this way, only
3125 like C</qr/\p{Any}>, I<etc>.  You can't actually use the C<"Y"> and C<"N>" in
3126 them.
3127
3128 =cut
3129
3130 # User-defined properties could be handled with some changes to utf8_heavy.pl;
3131 # if done, consideration should be given to the fact that the user subroutine
3132 # could return different results with each call, which could lead to some
3133 # security issues.
3134
3135 # One could store things in memory so they don't have to be recalculated, but
3136 # it is unlikely this will be called often, and some properties would take up
3137 # significant memory.
3138
3139 # These are created by mktables for this routine and stored in unicore/UCD.pl
3140 # where their structures are described.
3141 our @algorithmic_named_code_points;
3142 our $HANGUL_BEGIN;
3143 our $HANGUL_COUNT;
3144
3145 sub prop_invmap ($;$) {
3146
3147     croak __PACKAGE__, "::prop_invmap: must be called in list context" unless wantarray;
3148
3149     my $prop = $_[0];
3150     return unless defined $prop;
3151
3152     # Undocumented way to get at Perl internal properties; it may be changed
3153     # or removed without notice at any time.  It currently also changes the
3154     # output to use the format specified in the file rather than the one we
3155     # normally compute and return
3156     my $internal_ok = defined $_[1] && $_[1] eq '_perl_core_internal_ok';
3157
3158     # Fail internal properties
3159     return if $prop =~ /^_/ && ! $internal_ok;
3160
3161     # The values returned by this function.
3162     my (@invlist, @invmap, $format, $missing);
3163
3164     # The swash has two components we look at, the base list, and a hash,
3165     # named 'SPECIALS', containing any additional members whose mappings don't
3166     # fit into the base list scheme of things.  These generally 'override'
3167     # any value in the base list for the same code point.
3168     my $overrides;
3169
3170     require "utf8_heavy.pl";
3171     require "unicore/UCD.pl";
3172
3173 RETRY:
3174
3175     # If there are multiple entries for a single code point
3176     my $has_multiples = 0;
3177
3178     # Try to get the map swash for the property.  They have 'To' prepended to
3179     # the property name, and 32 means we will accept 32 bit return values.
3180     # The 0 means we aren't calling this from tr///.
3181     my $swash = utf8::SWASHNEW(__PACKAGE__, "To$prop", undef, 32, 0);
3182
3183     # If didn't find it, could be because needs a proxy.  And if was the
3184     # 'Block' or 'Name' property, use a proxy even if did find it.  Finding it
3185     # in these cases would be the result of the installation changing mktables
3186     # to output the Block or Name tables.  The Block table gives block names
3187     # in the new-style, and this routine is supposed to return old-style block
3188     # names.  The Name table is valid, but we need to execute the special code
3189     # below to add in the algorithmic-defined name entries.
3190     # And NFKCCF needs conversion, so handle that here too.
3191     if (ref $swash eq ""
3192         || $swash->{'TYPE'} =~ / ^ To (?: Blk | Na | NFKCCF ) $ /x)
3193     {
3194
3195         # Get the short name of the input property, in standard form
3196         my ($second_try) = prop_aliases($prop);
3197         return unless $second_try;
3198         $second_try = utf8::_loose_name(lc $second_try);
3199
3200         if ($second_try eq "in") {
3201
3202             # This property is identical to age for inversion map purposes
3203             $prop = "age";
3204             goto RETRY;
3205         }
3206         elsif ($second_try =~ / ^ s ( cf | fc | [ltu] c ) $ /x) {
3207
3208             # These properties use just the LIST part of the full mapping,
3209             # which includes the simple maps that are otherwise overridden by
3210             # the SPECIALS.  So all we need do is to not look at the SPECIALS;
3211             # set $overrides to indicate that
3212             $overrides = -1;
3213
3214             # The full name is the simple name stripped of its initial 's'
3215             $prop = $1;
3216
3217             # .. except for this case
3218             $prop = 'cf' if $prop eq 'fc';
3219
3220             goto RETRY;
3221         }
3222         elsif ($second_try eq "blk") {
3223
3224             # We use the old block names.  Just create a fake swash from its
3225             # data.
3226             _charblocks();
3227             my %blocks;
3228             $blocks{'LIST'} = "";
3229             $blocks{'TYPE'} = "ToBlk";
3230             $utf8::SwashInfo{ToBlk}{'missing'} = "No_Block";
3231             $utf8::SwashInfo{ToBlk}{'format'} = "s";
3232
3233             foreach my $block (@BLOCKS) {
3234                 $blocks{'LIST'} .= sprintf "%x\t%x\t%s\n",
3235                                            $block->[0],
3236                                            $block->[1],
3237                                            $block->[2];
3238             }
3239             $swash = \%blocks;
3240         }
3241         elsif ($second_try eq "na") {
3242
3243             # Use the combo file that has all the Name-type properties in it,
3244             # extracting just the ones that are for the actual 'Name'
3245             # property.  And create a fake swash from it.
3246             my %names;
3247             $names{'LIST'} = "";
3248             my $original = do "unicore/Name.pl";
3249             my $algorithm_names = \@algorithmic_named_code_points;
3250
3251             # We need to remove the names from it that are aliases.  For that
3252             # we need to also read in that table.  Create a hash with the keys
3253             # being the code points, and the values being a list of the
3254             # aliases for the code point key.
3255             my ($aliases_code_points, $aliases_maps, undef, undef) =
3256                                                 &prop_invmap('Name_Alias');
3257             my %aliases;
3258             for (my $i = 0; $i < @$aliases_code_points; $i++) {
3259                 my $code_point = $aliases_code_points->[$i];
3260                 $aliases{$code_point} = $aliases_maps->[$i];
3261
3262                 # If not already a list, make it into one, so that later we
3263                 # can treat things uniformly
3264                 if (! ref $aliases{$code_point}) {
3265                     $aliases{$code_point} = [ $aliases{$code_point} ];
3266                 }
3267
3268                 # Remove the alias type from the entry, retaining just the
3269                 # name.
3270                 map { s/:.*// } @{$aliases{$code_point}};
3271             }
3272
3273             my $i = 0;
3274             foreach my $line (split "\n", $original) {
3275                 my ($hex_code_point, $name) = split "\t", $line;
3276
3277                 # Weeds out all comments, blank lines, and named sequences
3278                 next if $hex_code_point =~ /[^[:xdigit:]]/a;
3279
3280                 my $code_point = hex $hex_code_point;
3281
3282                 # The name of all controls is the default: the empty string.
3283                 # The set of controls is immutable
3284                 next if chr($code_point) =~ /[[:cntrl:]]/u;
3285
3286                 # If this is a name_alias, it isn't a name
3287                 next if grep { $_ eq $name } @{$aliases{$code_point}};
3288
3289                 # If we are beyond where one of the special lines needs to
3290                 # be inserted ...
3291                 while ($i < @$algorithm_names
3292                     && $code_point > $algorithm_names->[$i]->{'low'})
3293                 {
3294
3295                     # ... then insert it, ahead of what we were about to
3296                     # output
3297                     $names{'LIST'} .= sprintf "%x\t%x\t%s\n",
3298                                             $algorithm_names->[$i]->{'low'},
3299                                             $algorithm_names->[$i]->{'high'},
3300                                             $algorithm_names->[$i]->{'name'};
3301
3302                     # Done with this range.
3303                     $i++;
3304
3305                     # We loop until all special lines that precede the next
3306                     # regular one are output.
3307                 }
3308
3309                 # Here, is a normal name.
3310                 $names{'LIST'} .= sprintf "%x\t\t%s\n", $code_point, $name;
3311             } # End of loop through all the names
3312
3313             $names{'TYPE'} = "ToNa";
3314             $utf8::SwashInfo{ToNa}{'missing'} = "";
3315             $utf8::SwashInfo{ToNa}{'format'} = "n";
3316             $swash = \%names;
3317         }
3318         elsif ($second_try =~ / ^ ( d [mt] ) $ /x) {
3319
3320             # The file is a combination of dt and dm properties.  Create a
3321             # fake swash from the portion that we want.
3322             my $original = do "unicore/Decomposition.pl";
3323             my %decomps;
3324
3325             if ($second_try eq 'dt') {
3326                 $decomps{'TYPE'} = "ToDt";
3327                 $utf8::SwashInfo{'ToDt'}{'missing'} = "None";
3328                 $utf8::SwashInfo{'ToDt'}{'format'} = "s";
3329             }   # 'dm' is handled below, with 'nfkccf'
3330
3331             $decomps{'LIST'} = "";
3332
3333             # This property has one special range not in the file: for the
3334             # hangul syllables.  But not in Unicode version 1.
3335             UnicodeVersion() unless defined $v_unicode_version;
3336             my $done_hangul = ($v_unicode_version lt v2.0.0)
3337                               ? 1
3338                               : 0;    # Have we done the hangul range ?
3339             foreach my $line (split "\n", $original) {
3340                 my ($hex_lower, $hex_upper, $type_and_map) = split "\t", $line;
3341                 my $code_point = hex $hex_lower;
3342                 my $value;
3343                 my $redo = 0;
3344
3345                 # The type, enclosed in <...>, precedes the mapping separated
3346                 # by blanks
3347                 if ($type_and_map =~ / ^ < ( .* ) > \s+ (.*) $ /x) {
3348                     $value = ($second_try eq 'dt') ? $1 : $2
3349                 }
3350                 else {  # If there is no type specified, it's canonical
3351                     $value = ($second_try eq 'dt')
3352                              ? "Canonical" :
3353                              $type_and_map;
3354                 }
3355
3356                 # Insert the hangul range at the appropriate spot.
3357                 if (! $done_hangul && $code_point > $HANGUL_BEGIN) {
3358                     $done_hangul = 1;
3359                     $decomps{'LIST'} .=
3360                                 sprintf "%x\t%x\t%s\n",
3361                                         $HANGUL_BEGIN,
3362                                         $HANGUL_BEGIN + $HANGUL_COUNT - 1,
3363                                         ($second_try eq 'dt')
3364                                         ? "Canonical"
3365                                         : "<hangul syllable>";
3366                 }
3367
3368                 if ($value =~ / / && $hex_upper ne "" && $hex_upper ne $hex_lower) {
3369                     $line = sprintf("%04X\t%s\t%s", hex($hex_lower) + 1, $hex_upper, $value);
3370                     $hex_upper = "";
3371                     $redo = 1;
3372                 }
3373
3374                 # And append this to our constructed LIST.
3375                 $decomps{'LIST'} .= "$hex_lower\t$hex_upper\t$value\n";
3376
3377                 redo if $redo;
3378             }
3379             $swash = \%decomps;
3380         }
3381         elsif ($second_try ne 'nfkccf') { # Don't know this property. Fail.
3382             return;
3383         }
3384
3385         if ($second_try eq 'nfkccf' || $second_try eq 'dm') {
3386
3387             # The 'nfkccf' property is stored in the old format for backwards
3388             # compatibility for any applications that has read its file
3389             # directly before prop_invmap() existed.
3390             # And the code above has extracted the 'dm' property from its file
3391             # yielding the same format.  So here we convert them to adjusted
3392             # format for compatibility with the other properties similar to
3393             # them.
3394             my %revised_swash;
3395
3396             # We construct a new converted list.
3397             my $list = "";
3398
3399             my @ranges = split "\n", $swash->{'LIST'};
3400             for (my $i = 0; $i < @ranges; $i++) {
3401                 my ($hex_begin, $hex_end, $map) = split "\t", $ranges[$i];
3402
3403                 # The dm property has maps that are space separated sequences
3404                 # of code points, as well as the special entry "<hangul
3405                 # syllable>, which also contains a blank.
3406                 my @map = split " ", $map;
3407                 if (@map > 1) {
3408
3409                     # If it's just the special entry, append as-is.
3410                     if ($map eq '<hangul syllable>') {
3411                         $list .= "$ranges[$i]\n";
3412                     }
3413                     else {
3414
3415                         # These should all be single-element ranges.
3416                         croak __PACKAGE__, "::prop_invmap: Not expecting a mapping with multiple code points in a multi-element range, $ranges[$i]" if $hex_end ne "" && $hex_end ne $hex_begin;
3417
3418                         # Convert them to decimal, as that's what's expected.
3419                         $list .= "$hex_begin\t\t"
3420                             . join(" ", map { hex } @map)
3421                             . "\n";
3422                     }
3423                     next;
3424                 }
3425
3426                 # Here, the mapping doesn't have a blank, is for a single code
3427                 # point.
3428                 my $begin = hex $hex_begin;
3429                 my $end = (defined $hex_end && $hex_end ne "")
3430                         ? hex $hex_end
3431                         : $begin;
3432
3433                 # Again, the output is to be in decimal.
3434                 my $decimal_map = hex $map;
3435
3436                 # We know that multi-element ranges with the same mapping
3437                 # should not be adjusted, as after the adjustment
3438                 # multi-element ranges are for consecutive increasing code
3439                 # points.  Further, the final element in the list won't be
3440                 # adjusted, as there is nothing after it to include in the
3441                 # adjustment
3442                 if ($begin != $end || $i == @ranges -1) {
3443
3444                     # So just convert these to single-element ranges
3445                     foreach my $code_point ($begin .. $end) {
3446                         $list .= sprintf("%04X\t\t%d\n",
3447                                         $code_point, $decimal_map);
3448                     }
3449                 }
3450                 else {
3451
3452                     # Here, we have a candidate for adjusting.  What we do is
3453                     # look through the subsequent adjacent elements in the
3454                     # input.  If the map to the next one differs by 1 from the
3455                     # one before, then we combine into a larger range with the
3456                     # initial map.  Loop doing this until we find one that
3457                     # can't be combined.
3458
3459                     my $offset = 0;     # How far away are we from the initial
3460                                         # map
3461                     my $squished = 0;   # ? Did we squish at least two
3462                                         # elements together into one range
3463                     for ( ; $i < @ranges; $i++) {
3464                         my ($next_hex_begin, $next_hex_end, $next_map)
3465                                                 = split "\t", $ranges[$i+1];
3466
3467                         # In the case of 'dm', the map may be a sequence of
3468                         # multiple code points, which are never combined with
3469                         # another range
3470                         last if $next_map =~ / /;
3471
3472                         $offset++;
3473                         my $next_decimal_map = hex $next_map;
3474
3475                         # If the next map is not next in sequence, it
3476                         # shouldn't be combined.
3477                         last if $next_decimal_map != $decimal_map + $offset;
3478
3479                         my $next_begin = hex $next_hex_begin;
3480
3481                         # Likewise, if the next element isn't adjacent to the
3482                         # previous one, it shouldn't be combined.
3483                         last if $next_begin != $begin + $offset;
3484
3485                         my $next_end = (defined $next_hex_end
3486                                         && $next_hex_end ne "")
3487                                             ? hex $next_hex_end
3488                                             : $next_begin;
3489
3490                         # And finally, if the next element is a multi-element
3491                         # range, it shouldn't be combined.
3492                         last if $next_end != $next_begin;
3493
3494                         # Here, we will combine.  Loop to see if we should
3495                         # combine the next element too.
3496                         $squished = 1;
3497                     }
3498
3499                     if ($squished) {
3500
3501                         # Here, 'i' is the element number of the last element to
3502                         # be combined, and the range is single-element, or we
3503                         # wouldn't be combining.  Get it's code point.
3504                         my ($hex_end, undef, undef) = split "\t", $ranges[$i];
3505                         $list .= "$hex_begin\t$hex_end\t$decimal_map\n";
3506                     } else {
3507
3508                         # Here, no combining done.  Just append the initial
3509                         # (and current) values.
3510                         $list .= "$hex_begin\t\t$decimal_map\n";
3511                     }
3512                 }
3513             } # End of loop constructing the converted list
3514
3515             # Finish up the data structure for our converted swash
3516             my $type = ($second_try eq 'nfkccf') ? 'ToNFKCCF' : 'ToDm';
3517             $revised_swash{'LIST'} = $list;
3518             $revised_swash{'TYPE'} = $type;
3519             $revised_swash{'SPECIALS'} = $swash->{'SPECIALS'};
3520             $swash = \%revised_swash;
3521
3522             $utf8::SwashInfo{$type}{'missing'} = 0;
3523             $utf8::SwashInfo{$type}{'format'} = 'a';
3524         }
3525     }
3526
3527     if ($swash->{'EXTRAS'}) {
3528         carp __PACKAGE__, "::prop_invmap: swash returned for $prop unexpectedly has EXTRAS magic";
3529         return;
3530     }
3531
3532     # Here, have a valid swash return.  Examine it.
3533     my $returned_prop = $swash->{'TYPE'};
3534
3535     # All properties but binary ones should have 'missing' and 'format'
3536     # entries
3537     $missing = $utf8::SwashInfo{$returned_prop}{'missing'};
3538     $missing = 'N' unless defined $missing;
3539
3540     $format = $utf8::SwashInfo{$returned_prop}{'format'};
3541     $format = 'b' unless defined $format;
3542
3543     my $requires_adjustment = $format =~ /^a/;
3544
3545     if ($swash->{'LIST'} =~ /^V/) {
3546         @invlist = split "\n", $swash->{'LIST'} =~ s/ \s* (?: \# .* )? $ //xmgr;
3547         shift @invlist;
3548         foreach my $i (0 .. @invlist - 1) {
3549             $invmap[$i] = ($i % 2 == 0) ? 'Y' : 'N'
3550         }
3551
3552         # The map includes lines for all code points; add one for the range
3553         # from 0 to the first Y.
3554         if ($invlist[0] != 0) {
3555             unshift @invlist, 0;
3556             unshift @invmap, 'N';
3557         }
3558     }
3559     else {
3560         # The LIST input lines look like:
3561         # ...
3562         # 0374\t\tCommon
3563         # 0375\t0377\tGreek   # [3]
3564         # 037A\t037D\tGreek   # [4]
3565         # 037E\t\tCommon
3566         # 0384\t\tGreek
3567         # ...
3568         #
3569         # Convert them to like
3570         # 0374 => Common
3571         # 0375 => Greek
3572         # 0378 => $missing
3573         # 037A => Greek
3574         # 037E => Common
3575         # 037F => $missing
3576         # 0384 => Greek
3577         #
3578         # For binary properties, the final non-comment column is absent, and
3579         # assumed to be 'Y'.
3580
3581         foreach my $range (split "\n", $swash->{'LIST'}) {
3582             $range =~ s/ \s* (?: \# .* )? $ //xg; # rmv trailing space, comments
3583
3584             # Find the beginning and end of the range on the line
3585             my ($hex_begin, $hex_end, $map) = split "\t", $range;
3586             my $begin = hex $hex_begin;
3587             no warnings 'portable';
3588             my $end = (defined $hex_end && $hex_end ne "")
3589                     ? hex $hex_end
3590                     : $begin;
3591
3592             # Each time through the loop (after the first):
3593             # $invlist[-2] contains the beginning of the previous range processed
3594             # $invlist[-1] contains the end+1 of the previous range processed
3595             # $invmap[-2] contains the value of the previous range processed
3596             # $invmap[-1] contains the default value for missing ranges
3597             #                                                       ($missing)
3598             #
3599             # Thus, things are set up for the typical case of a new
3600             # non-adjacent range of non-missings to be added.  But, if the new
3601             # range is adjacent, it needs to replace the [-1] element; and if
3602             # the new range is a multiple value of the previous one, it needs
3603             # to be added to the [-2] map element.
3604
3605             # The first time through, everything will be empty.  If the
3606             # property doesn't have a range that begins at 0, add one that
3607             # maps to $missing
3608             if (! @invlist) {
3609                 if ($begin != 0) {
3610                     push @invlist, 0;
3611                     push @invmap, $missing;
3612                 }
3613             }
3614             elsif (@invlist > 1 && $invlist[-2] == $begin) {
3615
3616                 # Here we handle the case where the input has multiple entries
3617                 # for each code point.  mktables should have made sure that
3618                 # each such range contains only one code point.  At this
3619                 # point, $invlist[-1] is the $missing that was added at the
3620                 # end of the last loop iteration, and [-2] is the last real
3621                 # input code point, and that code point is the same as the one
3622                 # we are adding now, making the new one a multiple entry.  Add
3623                 # it to the existing entry, either by pushing it to the
3624                 # existing list of multiple entries, or converting the single
3625                 # current entry into a list with both on it.  This is all we
3626                 # need do for this iteration.
3627
3628                 if ($end != $begin) {
3629                     croak __PACKAGE__, ":prop_invmap: Multiple maps per code point in '$prop' require single-element ranges: begin=$begin, end=$end, map=$map";
3630                 }
3631                 if (! ref $invmap[-2]) {
3632                     $invmap[-2] = [ $invmap[-2], $map ];
3633                 }
3634                 else {
3635                     push @{$invmap[-2]}, $map;
3636                 }
3637                 $has_multiples = 1;
3638                 next;
3639             }
3640             elsif ($invlist[-1] == $begin) {
3641
3642                 # If the input isn't in the most compact form, so that there
3643                 # are two adjacent ranges that map to the same thing, they
3644                 # should be combined (EXCEPT where the arrays require
3645                 # adjustments, in which case everything is already set up
3646                 # correctly).  This happens in our constructed dt mapping, as
3647                 # Element [-2] is the map for the latest range so far
3648                 # processed.  Just set the beginning point of the map to
3649                 # $missing (in invlist[-1]) to 1 beyond where this range ends.
3650                 # For example, in
3651                 # 12\t13\tXYZ
3652                 # 14\t17\tXYZ
3653                 # we have set it up so that it looks like
3654                 # 12 => XYZ
3655                 # 14 => $missing
3656                 #
3657                 # We now see that it should be
3658                 # 12 => XYZ
3659                 # 18 => $missing
3660                 if (! $requires_adjustment && @invlist > 1 && ( (defined $map)
3661                                     ? $invmap[-2] eq $map
3662                                     : $invmap[-2] eq 'Y'))
3663                 {
3664                     $invlist[-1] = $end + 1;
3665                     next;
3666                 }
3667
3668                 # Here, the range started in the previous iteration that maps
3669                 # to $missing starts at the same code point as this range.
3670                 # That means there is no gap to fill that that range was
3671                 # intended for, so we just pop it off the parallel arrays.
3672                 pop @invlist;
3673                 pop @invmap;
3674             }
3675
3676             # Add the range beginning, and the range's map.
3677             push @invlist, $begin;
3678             if ($returned_prop eq 'ToDm') {
3679
3680                 # The decomposition maps are either a line like <hangul
3681                 # syllable> which are to be taken as is; or a sequence of code
3682                 # points in hex and separated by blanks.  Convert them to
3683                 # decimal, and if there is more than one, use an anonymous
3684                 # array as the map.
3685                 if ($map =~ /^ < /x) {
3686                     push @invmap, $map;
3687                 }
3688                 else {
3689                     my @map = split " ", $map;
3690                     if (@map == 1) {
3691                         push @invmap, $map[0];
3692                     }
3693                     else {
3694                         push @invmap, \@map;
3695                     }
3696                 }
3697             }
3698             else {
3699
3700                 # Otherwise, convert hex formatted list entries to decimal;
3701                 # add a 'Y' map for the missing value in binary properties, or
3702                 # otherwise, use the input map unchanged.
3703                 $map = ($format eq 'x' || $format eq 'ax')
3704                     ? hex $map
3705                     : $format eq 'b'
3706                     ? 'Y'
3707                     : $map;
3708                 push @invmap, $map;
3709             }
3710
3711             # We just started a range.  It ends with $end.  The gap between it
3712             # and the next element in the list must be filled with a range
3713             # that maps to the default value.  If there is no gap, the next
3714             # iteration will pop this, unless there is no next iteration, and
3715             # we have filled all of the Unicode code space, so check for that
3716             # and skip.
3717             if ($end < $Unicode::UCD::MAX_CP) {
3718                 push @invlist, $end + 1;
3719                 push @invmap, $missing;
3720             }
3721         }
3722     }
3723
3724     # If the property is empty, make all code points use the value for missing
3725     # ones.
3726     if (! @invlist) {
3727         push @invlist, 0;
3728         push @invmap, $missing;
3729     }
3730
3731     # The final element is always for just the above-Unicode code points.  If
3732     # not already there, add it.  It merely splits the current final range
3733     # that extends to infinity into two elements, each with the same map.
3734     # (This is to conform with the API that says the final element is for
3735     # $MAX_UNICODE_CODEPOINT + 1 .. INFINITY.)
3736     if ($invlist[-1] != $MAX_UNICODE_CODEPOINT + 1) {
3737         push @invmap, $invmap[-1];
3738         push @invlist, $MAX_UNICODE_CODEPOINT + 1;
3739     }
3740
3741     # The second component of the map are those values that require
3742     # non-standard specification, stored in SPECIALS.  These override any
3743     # duplicate code points in LIST.  If we are using a proxy, we may have
3744     # already set $overrides based on the proxy.
3745     $overrides = $swash->{'SPECIALS'} unless defined $overrides;
3746     if ($overrides) {
3747
3748         # A negative $overrides implies that the SPECIALS should be ignored,
3749         # and a simple 'a' list is the value.
3750         if ($overrides < 0) {
3751             $format = 'a';
3752         }
3753         else {
3754
3755             # Currently, all overrides are for properties that normally map to
3756             # single code points, but now some will map to lists of code
3757             # points (but there is an exception case handled below).
3758             $format = 'al';
3759
3760             # Look through the overrides.
3761             foreach my $cp_maybe_utf8 (keys %$overrides) {
3762                 my $cp;
3763                 my @map;
3764
3765                 # If the overrides came from SPECIALS, the code point keys are
3766                 # packed UTF-8.
3767                 if ($overrides == $swash->{'SPECIALS'}) {
3768                     $cp = $cp_maybe_utf8;
3769                     if (! utf8::decode($cp)) {
3770                         croak __PACKAGE__, "::prop_invmap: Malformed UTF-8: ",
3771                               map { sprintf("\\x{%02X}", unpack("C", $_)) }
3772                                                                 split "", $cp;
3773                     }
3774
3775                     $cp = unpack("W", $cp);
3776                     @map = unpack "W*", $swash->{'SPECIALS'}{$cp_maybe_utf8};
3777
3778                     # The empty string will show up unpacked as an empty
3779                     # array.
3780                     $format = 'ale' if @map == 0;
3781                 }
3782                 else {
3783
3784                     # But if we generated the overrides, we didn't bother to
3785                     # pack them, and we, so far, do this only for properties
3786                     # that are 'a' ones.
3787                     $cp = $cp_maybe_utf8;
3788                     @map = hex $overrides->{$cp};
3789                     $format = 'a';
3790                 }
3791
3792                 # Find the range that the override applies to.
3793                 my $i = search_invlist(\@invlist, $cp);
3794                 if ($cp < $invlist[$i] || $cp >= $invlist[$i + 1]) {
3795                     croak __PACKAGE__, "::prop_invmap: wrong_range, cp=$cp; i=$i, current=$invlist[$i]; next=$invlist[$i + 1]"
3796                 }
3797
3798                 # And what that range currently maps to
3799                 my $cur_map = $invmap[$i];
3800
3801                 # If there is a gap between the next range and the code point
3802                 # we are overriding, we have to add elements to both arrays to
3803                 # fill that gap, using the map that applies to it, which is
3804                 # $cur_map, since it is part of the current range.
3805                 if ($invlist[$i + 1] > $cp + 1) {
3806                     #use feature 'say';
3807                     #say "Before splice:";
3808                     #say 'i-2=[', $i-2, ']', sprintf("%04X maps to %s", $invlist[$i-2], $invmap[$i-2]) if $i >= 2;
3809                     #say 'i-1=[', $i-1, ']', sprintf("%04X maps to %s", $invlist[$i-1], $invmap[$i-1]) if $i >= 1;
3810                     #say 'i  =[', $i, ']', sprintf("%04X maps to %s", $invlist[$i], $invmap[$i]);
3811                     #say 'i+1=[', $i+1, ']', sprintf("%04X maps to %s", $invlist[$i+1], $invmap[$i+1]) if $i < @invlist + 1;
3812                     #say 'i+2=[', $i+2, ']', sprintf("%04X maps to %s", $invlist[$i+2], $invmap[$i+2]) if $i < @invlist + 2;
3813
3814                     splice @invlist, $i + 1, 0, $cp + 1;
3815                     splice @invmap, $i + 1, 0, $cur_map;
3816
3817                     #say "After splice:";
3818                     #say 'i-2=[', $i-2, ']', sprintf("%04X maps to %s", $invlist[$i-2], $invmap[$i-2]) if $i >= 2;
3819                     #say 'i-1=[', $i-1, ']', sprintf("%04X maps to %s", $invlist[$i-1], $invmap[$i-1]) if $i >= 1;
3820                     #say 'i  =[', $i, ']', sprintf("%04X maps to %s", $invlist[$i], $invmap[$i]);
3821                     #say 'i+1=[', $i+1, ']', sprintf("%04X maps to %s", $invlist[$i+1], $invmap[$i+1]) if $i < @invlist + 1;
3822                     #say 'i+2=[', $i+2, ']', sprintf("%04X maps to %s", $invlist[$i+2], $invmap[$i+2]) if $i < @invlist + 2;
3823                 }
3824
3825                 # If the remaining portion of the range is multiple code
3826                 # points (ending with the one we are replacing, guaranteed by
3827                 # the earlier splice).  We must split it into two
3828                 if ($invlist[$i] < $cp) {
3829                     $i++;   # Compensate for the new element
3830
3831                     #use feature 'say';
3832                     #say "Before splice:";
3833                     #say 'i-2=[', $i-2, ']', sprintf("%04X maps to %s", $invlist[$i-2], $invmap[$i-2]) if $i >= 2;
3834                     #say 'i-1=[', $i-1, ']', sprintf("%04X maps to %s", $invlist[$i-1], $invmap[$i-1]) if $i >= 1;
3835                     #say 'i  =[', $i, ']', sprintf("%04X maps to %s", $invlist[$i], $invmap[$i]);
3836                     #say 'i+1=[', $i+1, ']', sprintf("%04X maps to %s", $invlist[$i+1], $invmap[$i+1]) if $i < @invlist + 1;
3837                     #say 'i+2=[', $i+2, ']', sprintf("%04X maps to %s", $invlist[$i+2], $invmap[$i+2]) if $i < @invlist + 2;
3838
3839                     splice @invlist, $i, 0, $cp;
3840                     splice @invmap, $i, 0, 'dummy';
3841
3842                     #say "After splice:";
3843                     #say 'i-2=[', $i-2, ']', sprintf("%04X maps to %s", $invlist[$i-2], $invmap[$i-2]) if $i >= 2;
3844                     #say 'i-1=[', $i-1, ']', sprintf("%04X maps to %s", $invlist[$i-1], $invmap[$i-1]) if $i >= 1;
3845                     #say 'i  =[', $i, ']', sprintf("%04X maps to %s", $invlist[$i], $invmap[$i]);
3846                     #say 'i+1=[', $i+1, ']', sprintf("%04X maps to %s", $invlist[$i+1], $invmap[$i+1]) if $i < @invlist + 1;
3847                     #say 'i+2=[', $i+2, ']', sprintf("%04X maps to %s", $invlist[$i+2], $invmap[$i+2]) if $i < @invlist + 2;
3848                 }
3849
3850                 # Here, the range we are overriding contains a single code
3851                 # point.  The result could be the empty string, a single
3852                 # value, or a list.  If the last case, we use an anonymous
3853                 # array.
3854                 $invmap[$i] = (scalar @map == 0)
3855                                ? ""
3856                                : (scalar @map > 1)
3857                                   ? \@map
3858                                   : $map[0];
3859             }
3860         }
3861     }
3862     elsif ($format eq 'x') {
3863
3864         # All hex-valued properties are really to code points, and have been
3865         # converted to decimal.
3866         $format = 's';
3867     }
3868     elsif ($returned_prop eq 'ToDm') {
3869         $format = 'ad';
3870     }
3871     elsif ($format eq 'sw') { # blank-separated elements to form a list.
3872         map { $_ = [ split " ", $_  ] if $_ =~ / / } @invmap;
3873         $format = 'sl';
3874     }
3875     elsif ($returned_prop eq 'ToNameAlias') {
3876
3877         # This property currently doesn't have any lists, but theoretically
3878         # could
3879         $format = 'sl';
3880     }
3881     elsif ($returned_prop eq 'ToPerlDecimalDigit') {
3882         $format = 'ae';
3883     }
3884     elsif ($returned_prop eq 'ToNv') {
3885
3886         # The one property that has this format is stored as a delta, so needs
3887         # to indicate that need to add code point to it.
3888         $format = 'ar';
3889     }
3890     elsif ($format ne 'n' && $format ne 'a') {
3891
3892         # All others are simple scalars
3893         $format = 's';
3894     }
3895     if ($has_multiples &&  $format !~ /l/) {
3896         croak __PACKAGE__, "::prop_invmap: Wrong format '$format' for prop_invmap('$prop'); should indicate has lists";
3897     }
3898
3899     return (\@invlist, \@invmap, $format, $missing);
3900 }
3901
3902 sub search_invlist {
3903
3904 =pod
3905
3906 =head2 B<search_invlist()>
3907
3908  use Unicode::UCD qw(prop_invmap prop_invlist);
3909  use Unicode::UCD 'search_invlist';
3910
3911  my @invlist = prop_invlist($property_name);
3912  print $code_point, ((search_invlist(\@invlist, $code_point) // -1) % 2)
3913                      ? " isn't"
3914                      : " is",
3915      " in $property_name\n";
3916
3917  my ($blocks_ranges_ref, $blocks_map_ref) = prop_invmap("Block");
3918  my $index = search_invlist($blocks_ranges_ref, $code_point);
3919  print "$code_point is in block ", $blocks_map_ref->[$index], "\n";
3920
3921 C<search_invlist> is used to search an inversion list returned by
3922 C<prop_invlist> or C<prop_invmap> for a particular L</code point argument>.
3923 C<undef> is returned if the code point is not found in the inversion list
3924 (this happens only when it is not a legal L<code point argument>, or is less
3925 than the list's first element).  A warning is raised in the first instance.
3926
3927 Otherwise, it returns the index into the list of the range that contains the
3928 code point.; that is, find C<i> such that
3929
3930     list[i]<= code_point < list[i+1].
3931
3932 As explained in L</prop_invlist()>, whether a code point is in the list or not
3933 depends on if the index is even (in) or odd (not in).  And as explained in
3934 L</prop_invmap()>, the index is used with the returned parallel array to find
3935 the mapping.
3936
3937 =cut
3938
3939
3940     my $list_ref = shift;
3941     my $input_code_point = shift;
3942     my $code_point = _getcode($input_code_point);
3943
3944     if (! defined $code_point) {
3945         carp __PACKAGE__, "::search_invlist: unknown code '$input_code_point'";
3946         return;
3947     }
3948
3949     my $max_element = @$list_ref - 1;
3950
3951     # Return undef if list is empty or requested item is before the first element.
3952     return if $max_element < 0;
3953     return if $code_point < $list_ref->[0];
3954
3955     # Short cut something at the far-end of the table.  This also allows us to
3956     # refer to element [$i+1] without fear of being out-of-bounds in the loop
3957     # below.
3958     return $max_element if $code_point >= $list_ref->[$max_element];
3959
3960     use integer;        # want integer division
3961
3962     my $i = $max_element / 2;
3963
3964     my $lower = 0;
3965     my $upper = $max_element;
3966     while (1) {
3967
3968         if ($code_point >= $list_ref->[$i]) {
3969
3970             # Here we have met the lower constraint.  We can quit if we
3971             # also meet the upper one.
3972             last if $code_point < $list_ref->[$i+1];
3973
3974             $lower = $i;        # Still too low.
3975
3976         }
3977         else {
3978
3979             # Here, $code_point < $list_ref[$i], so look lower down.
3980             $upper = $i;
3981         }
3982
3983         # Split search domain in half to try again.
3984         my $temp = ($upper + $lower) / 2;
3985
3986         # No point in continuing unless $i changes for next time
3987         # in the loop.
3988         return $i if $temp == $i;
3989         $i = $temp;
3990     } # End of while loop
3991
3992     # Here we have found the offset
3993     return $i;
3994 }
3995
3996 =head2 Unicode::UCD::UnicodeVersion
3997
3998 This returns the version of the Unicode Character Database, in other words, the
3999 version of the Unicode standard the database implements.  The version is a
4000 string of numbers delimited by dots (C<'.'>).
4001
4002 =cut
4003
4004 my $UNICODEVERSION;
4005
4006 sub UnicodeVersion {
4007     unless (defined $UNICODEVERSION) {
4008         openunicode(\$VERSIONFH, "version");
4009         local $/ = "\n";
4010         chomp($UNICODEVERSION = <$VERSIONFH>);
4011         close($VERSIONFH);
4012         croak __PACKAGE__, "::VERSION: strange version '$UNICODEVERSION'"
4013             unless $UNICODEVERSION =~ /^\d+(?:\.\d+)+$/;
4014     }
4015     $v_unicode_version = pack "C*", split /\./, $UNICODEVERSION;
4016     return $UNICODEVERSION;
4017 }
4018
4019 =head2 B<Blocks versus Scripts>
4020
4021 The difference between a block and a script is that scripts are closer
4022 to the linguistic notion of a set of code points required to represent
4023 languages, while block is more of an artifact of the Unicode code point
4024 numbering and separation into blocks of consecutive code points (so far the
4025 size of a block is some multiple of 16, like 128 or 256).
4026
4027 For example the Latin B<script> is spread over several B<blocks>, such
4028 as C<Basic Latin>, C<Latin 1 Supplement>, C<Latin Extended-A>, and
4029 C<Latin Extended-B>.  On the other hand, the Latin script does not
4030 contain all the characters of the C<Basic Latin> block (also known as
4031 ASCII): it includes only the letters, and not, for example, the digits
4032 nor the punctuation.
4033
4034 For blocks see L<http://www.unicode.org/Public/UNIDATA/Blocks.txt>
4035
4036 For scripts see UTR #24: L<http://www.unicode.org/unicode/reports/tr24/>
4037
4038 =head2 B<Matching Scripts and Blocks>
4039
4040 Scripts are matched with the regular-expression construct
4041 C<\p{...}> (e.g. C<\p{Tibetan}> matches characters of the Tibetan script),
4042 while C<\p{Blk=...}> is used for blocks (e.g. C<\p{Blk=Tibetan}> matches
4043 any of the 256 code points in the Tibetan block).
4044
4045 =head2 Old-style versus new-style block names
4046
4047 Unicode publishes the names of blocks in two different styles, though the two
4048 are equivalent under Unicode's loose matching rules.
4049
4050 The original style uses blanks and hyphens in the block names (except for
4051 C<No_Block>), like so:
4052
4053  Miscellaneous Mathematical Symbols-B
4054
4055 The newer style replaces these with underscores, like this:
4056
4057  Miscellaneous_Mathematical_Symbols_B
4058
4059 This newer style is consistent with the values of other Unicode properties.
4060 To preserve backward compatibility, all the functions in Unicode::UCD that
4061 return block names (except as noted) return the old-style ones.
4062 L</prop_value_aliases()> returns the new-style and can be used to convert from
4063 old-style to new-style:
4064
4065  my $new_style = prop_values_aliases("block", $old_style);
4066
4067 Perl also has single-form extensions that refer to blocks, C<In_Cyrillic>,
4068 meaning C<Block=Cyrillic>.  These have always been written in the new style.
4069
4070 To convert from new-style to old-style, follow this recipe:
4071
4072  $old_style = charblock((prop_invlist("block=$new_style"))[0]);
4073
4074 (which finds the range of code points in the block using C<prop_invlist>,
4075 gets the lower end of the range (0th element) and then looks up the old name
4076 for its block using C<charblock>).
4077
4078 Note that starting in Unicode 6.1, many of the block names have shorter
4079 synonyms.  These are always given in the new style.
4080
4081 =head1 AUTHOR
4082
4083 Jarkko Hietaniemi.  Now maintained by perl5 porters.
4084
4085 =cut
4086
4087 1;