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