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