Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Unicode::UCD.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Unicode::UCD 3pm"
61 .TH Unicode::UCD 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Unicode::UCD \- Unicode character database
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& use Unicode::UCD \*(Aqcharinfo\*(Aq;
72 \& my $charinfo = charinfo($codepoint);
73 \&
74 \& use Unicode::UCD \*(Aqcharprop\*(Aq;
75 \& my $value = charprop($codepoint, $property);
76 \&
77 \& use Unicode::UCD \*(Aqcharprops_all\*(Aq;
78 \& my $all_values_hash_ref = charprops_all($codepoint);
79 \&
80 \& use Unicode::UCD \*(Aqcasefold\*(Aq;
81 \& my $casefold = casefold($codepoint);
82 \&
83 \& use Unicode::UCD \*(Aqall_casefolds\*(Aq;
84 \& my $all_casefolds_ref = all_casefolds();
85 \&
86 \& use Unicode::UCD \*(Aqcasespec\*(Aq;
87 \& my $casespec = casespec($codepoint);
88 \&
89 \& use Unicode::UCD \*(Aqcharblock\*(Aq;
90 \& my $charblock = charblock($codepoint);
91 \&
92 \& use Unicode::UCD \*(Aqcharscript\*(Aq;
93 \& my $charscript = charscript($codepoint);
94 \&
95 \& use Unicode::UCD \*(Aqcharblocks\*(Aq;
96 \& my $charblocks = charblocks();
97 \&
98 \& use Unicode::UCD \*(Aqcharscripts\*(Aq;
99 \& my $charscripts = charscripts();
100 \&
101 \& use Unicode::UCD qw(charscript charinrange);
102 \& my $range = charscript($script);
103 \& print "looks like $script\en" if charinrange($range, $codepoint);
104 \&
105 \& use Unicode::UCD qw(general_categories bidi_types);
106 \& my $categories = general_categories();
107 \& my $types = bidi_types();
108 \&
109 \& use Unicode::UCD \*(Aqprop_aliases\*(Aq;
110 \& my @space_names = prop_aliases("space");
111 \&
112 \& use Unicode::UCD \*(Aqprop_value_aliases\*(Aq;
113 \& my @gc_punct_names = prop_value_aliases("Gc", "Punct");
114 \&
115 \& use Unicode::UCD \*(Aqprop_values\*(Aq;
116 \& my @all_EA_short_names = prop_values("East_Asian_Width");
117 \&
118 \& use Unicode::UCD \*(Aqprop_invlist\*(Aq;
119 \& my @puncts = prop_invlist("gc=punctuation");
120 \&
121 \& use Unicode::UCD \*(Aqprop_invmap\*(Aq;
122 \& my ($list_ref, $map_ref, $format, $missing)
123 \& = prop_invmap("General Category");
124 \&
125 \& use Unicode::UCD \*(Aqsearch_invlist\*(Aq;
126 \& my $index = search_invlist(\e@invlist, $code_point);
127 \&
128 \& # The following function should be used only internally in
129 \& # implementations of the Unicode Normalization Algorithm, and there
130 \& # are better choices than it.
131 \& use Unicode::UCD \*(Aqcompexcl\*(Aq;
132 \& my $compexcl = compexcl($codepoint);
133 \&
134 \& use Unicode::UCD \*(Aqnamedseq\*(Aq;
135 \& my $namedseq = namedseq($named_sequence_name);
136 \&
137 \& my $unicode_version = Unicode::UCD::UnicodeVersion();
138 \&
139 \& my $convert_to_numeric =
140 \& Unicode::UCD::num("\eN{VAI DIGIT ONE}\eN{VAI DIGIT TWO}");
141 .Ve
142 .SH DESCRIPTION
143 .IX Header "DESCRIPTION"
144 The Unicode::UCD module offers a series of functions that
145 provide a simple interface to the Unicode
146 Character Database.
147 .SS "code point argument"
148 .IX Subsection "code point argument"
149 Some of the functions are called with a \fIcode point argument\fR, which is either
150 a decimal or a hexadecimal scalar designating a code point in the platform\*(Aqs
151 native character set (extended to Unicode), or a string containing \f(CW\*(C`U+\*(C'\fR
152 followed by hexadecimals
153 designating a Unicode code point. A leading 0 will force a hexadecimal
154 interpretation, as will a hexadecimal digit that isn\*(Aqt a decimal digit.
155 .PP
156 Examples:
157 .PP
158 .Vb 6
159 \& 223 # Decimal 223 in native character set
160 \& 0223 # Hexadecimal 223, native (= 547 decimal)
161 \& 0xDF # Hexadecimal DF, native (= 223 decimal)
162 \& \*(Aq0xDF\*(Aq # String form of hexadecimal (= 223 decimal)
163 \& \*(AqU+DF\*(Aq # Hexadecimal DF, in Unicode\*(Aqs character set
164 \& (= LATIN SMALL LETTER SHARP S)
165 .Ve
166 .PP
167 Note that the largest code point in Unicode is U+10FFFF.
168 .SS \fBcharinfo()\fP
169 .IX Subsection "charinfo()"
170 .Vb 1
171 \& use Unicode::UCD \*(Aqcharinfo\*(Aq;
172 \&
173 \& my $charinfo = charinfo(0x41);
174 .Ve
175 .PP
176 This returns information about the input "code point argument"
177 as a reference to a hash of fields as defined by the Unicode
178 standard. If the "code point argument" is not assigned in the standard
179 (i.e., has the general category \f(CW\*(C`Cn\*(C'\fR meaning \f(CW\*(C`Unassigned\*(C'\fR)
180 or is a non\-character (meaning it is guaranteed to never be assigned in
181 the standard),
182 \&\f(CW\*(C`undef\*(C'\fR is returned.
183 .PP
184 Fields that aren\*(Aqt applicable to the particular code point argument exist in the
185 returned hash, and are empty.
186 .PP
187 For results that are less "raw" than this function returns, or to get the values for
188 any property, not just the few covered by this function, use the
189 "\fBcharprop()\fR" function.
190 .PP
191 The keys in the hash with the meanings of their values are:
192 .IP \fBcode\fR 4
193 .IX Item "code"
194 the input native "code point argument" expressed in hexadecimal, with
195 leading zeros
196 added if necessary to make it contain at least four hexdigits
197 .IP \fBname\fR 4
198 .IX Item "name"
199 name of \fIcode\fR, all IN UPPER CASE.
200 Some control\-type code points do not have names.
201 This field will be empty for \f(CW\*(C`Surrogate\*(C'\fR and \f(CW\*(C`Private Use\*(C'\fR code points,
202 and for the others without a name,
203 it will contain a description enclosed in angle brackets, like
204 \&\f(CW\*(C`<control>\*(C'\fR.
205 .IP \fBcategory\fR 4
206 .IX Item "category"
207 The short name of the general category of \fIcode\fR.
208 This will match one of the keys in the hash returned by "\fBgeneral_categories()\fR".
209 .Sp
210 The "\fBprop_value_aliases()\fR" function can be used to get all the synonyms
211 of the category name.
212 .IP \fBcombining\fR 4
213 .IX Item "combining"
214 the combining class number for \fIcode\fR used in the Canonical Ordering Algorithm.
215 For Unicode 5.1, this is described in Section 3.11 \f(CW\*(C`Canonical Ordering Behavior\*(C'\fR
216 available at
217 <http://www.unicode.org/versions/Unicode5.1.0/>
218 .Sp
219 The "\fBprop_value_aliases()\fR" function can be used to get all the synonyms
220 of the combining class number.
221 .IP \fBbidi\fR 4
222 .IX Item "bidi"
223 bidirectional type of \fIcode\fR.
224 This will match one of the keys in the hash returned by "\fBbidi_types()\fR".
225 .Sp
226 The "\fBprop_value_aliases()\fR" function can be used to get all the synonyms
227 of the bidi type name.
228 .IP \fBdecomposition\fR 4
229 .IX Item "decomposition"
230 is empty if \fIcode\fR has no decomposition; or is one or more codes
231 (separated by spaces) that, taken in order, represent a decomposition for
232 \&\fIcode\fR. Each has at least four hexdigits.
233 The codes may be preceded by a word enclosed in angle brackets, then a space,
234 like \f(CW\*(C`<compat> \*(C'\fR, giving the type of decomposition
235 .Sp
236 This decomposition may be an intermediate one whose components are also
237 decomposable. Use Unicode::Normalize to get the final decomposition in one
238 step.
239 .IP \fBdecimal\fR 4
240 .IX Item "decimal"
241 if \fIcode\fR represents a decimal digit this is its integer numeric value
242 .IP \fBdigit\fR 4
243 .IX Item "digit"
244 if \fIcode\fR represents some other digit\-like number, this is its integer
245 numeric value
246 .IP \fBnumeric\fR 4
247 .IX Item "numeric"
248 if \fIcode\fR represents a whole or rational number, this is its numeric value.
249 Rational values are expressed as a string like \f(CW\*(C`1/4\*(C'\fR.
250 .IP \fBmirrored\fR 4
251 .IX Item "mirrored"
252 \&\f(CW\*(C`Y\*(C'\fR or \f(CW\*(C`N\*(C'\fR designating if \fIcode\fR is mirrored in bidirectional text
253 .IP \fBunicode10\fR 4
254 .IX Item "unicode10"
255 name of \fIcode\fR in the Unicode 1.0 standard if one
256 existed for this code point and is different from the current name
257 .IP \fBcomment\fR 4
258 .IX Item "comment"
259 As of Unicode 6.0, this is always empty.
260 .IP \fBupper\fR 4
261 .IX Item "upper"
262 is, if non\-empty, the uppercase mapping for \fIcode\fR expressed as at least four
263 hexdigits. This indicates that the full uppercase mapping is a single
264 character, and is identical to the simple (single\-character only) mapping.
265 When this field is empty, it means that the simple uppercase mapping is
266 \&\fIcode\fR itself; you\*(Aqll need some other means, (like "\fBcharprop()\fR" or
267 "\fBcasespec()\fR" to get the full mapping.
268 .IP \fBlower\fR 4
269 .IX Item "lower"
270 is, if non\-empty, the lowercase mapping for \fIcode\fR expressed as at least four
271 hexdigits. This indicates that the full lowercase mapping is a single
272 character, and is identical to the simple (single\-character only) mapping.
273 When this field is empty, it means that the simple lowercase mapping is
274 \&\fIcode\fR itself; you\*(Aqll need some other means, (like "\fBcharprop()\fR" or
275 "\fBcasespec()\fR" to get the full mapping.
276 .IP \fBtitle\fR 4
277 .IX Item "title"
278 is, if non\-empty, the titlecase mapping for \fIcode\fR expressed as at least four
279 hexdigits. This indicates that the full titlecase mapping is a single
280 character, and is identical to the simple (single\-character only) mapping.
281 When this field is empty, it means that the simple titlecase mapping is
282 \&\fIcode\fR itself; you\*(Aqll need some other means, (like "\fBcharprop()\fR" or
283 "\fBcasespec()\fR" to get the full mapping.
284 .IP \fBblock\fR 4
285 .IX Item "block"
286 the block \fIcode\fR belongs to (used in \f(CW\*(C`\ep{Blk=...}\*(C'\fR).
287 The "\fBprop_value_aliases()\fR" function can be used to get all the synonyms
288 of the block name.
289 .Sp
290 See "Blocks versus Scripts".
291 .IP \fBscript\fR 4
292 .IX Item "script"
293 the script \fIcode\fR belongs to.
294 The "\fBprop_value_aliases()\fR" function can be used to get all the synonyms
295 of the script name. Note that this is the older "Script" property value, and
296 not the improved "Script_Extensions" value.
297 .Sp
298 See "Blocks versus Scripts".
299 .PP
300 Note that you cannot do (de)composition and casing based solely on the
301 \&\fIdecomposition\fR, \fIcombining\fR, \fIlower\fR, \fIupper\fR, and \fItitle\fR fields; you
302 will need also the "\fBcasespec()\fR" function and the \f(CW\*(C`Composition_Exclusion\*(C'\fR
303 property. (Or you could just use the \fBlc()\fR,
304 \&\fBuc()\fR, and \fBucfirst()\fR functions, and the
305 Unicode::Normalize module.)
306 .SS \fBcharprop()\fP
307 .IX Subsection "charprop()"
308 .Vb 1
309 \& use Unicode::UCD \*(Aqcharprop\*(Aq;
310 \&
311 \& print charprop(0x41, "Gc"), "\en";
312 \& print charprop(0x61, "General_Category"), "\en";
313 \&
314 \& prints
315 \& Lu
316 \& Ll
317 .Ve
318 .PP
319 This returns the value of the Unicode property given by the second parameter
320 for the "code point argument" given by the first.
321 .PP
322 The passed\-in property may be specified as any of the synonyms returned by
323 "\fBprop_aliases()\fR".
324 .PP
325 The return value is always a scalar, either a string or a number. For
326 properties where there are synonyms for the values, the synonym returned by
327 this function is the longest, most descriptive form, the one returned by
328 "\fBprop_value_aliases()\fR" when called in a scalar context. Of course, you can
329 call "\fBprop_value_aliases()\fR" on the result to get other synonyms.
330 .PP
331 The return values are more "cooked" than the "\fBcharinfo()\fR" ones. For
332 example, the \f(CW"uc"\fR property value is the actual string containing the full
333 uppercase mapping of the input code point. You have to go to extra trouble
334 with \f(CW\*(C`charinfo\*(C'\fR to get this value from its \f(CW\*(C`upper\*(C'\fR hash element when the
335 full mapping differs from the simple one.
336 .PP
337 Special note should be made of the return values for a few properties:
338 .IP Block 4
339 .IX Item "Block"
340 The value returned is the new\-style (see "Old\-style versus new\-style block
341 names").
342 .IP Decomposition_Mapping 4
343 .IX Item "Decomposition_Mapping"
344 Like "\fBcharinfo()\fR", the result may be an intermediate decomposition whose
345 components are also decomposable. Use Unicode::Normalize to get the final
346 decomposition in one step.
347 .Sp
348 Unlike "\fBcharinfo()\fR", this does not include the decomposition type. Use the
349 \&\f(CW\*(C`Decomposition_Type\*(C'\fR property to get that.
350 .IP Name_Alias 4
351 .IX Item "Name_Alias"
352 If the input code point\*(Aqs name has more than one synonym, they are returned
353 joined into a single comma\-separated string.
354 .IP Numeric_Value 4
355 .IX Item "Numeric_Value"
356 If the result is a fraction, it is converted into a floating point number to
357 the accuracy of your platform.
358 .IP Script_Extensions 4
359 .IX Item "Script_Extensions"
360 If the result is multiple script names, they are returned joined into a single
361 comma\-separated string.
362 .PP
363 When called with a property that is a Perl extension that isn\*(Aqt expressible in
364 a compound form, this function currently returns \f(CW\*(C`undef\*(C'\fR, as the only two
365 possible values are \fItrue\fR or \fIfalse\fR (1 or 0 I suppose). This behavior may
366 change in the future, so don\*(Aqt write code that relies on it. \f(CW\*(C`Present_In\*(C'\fR is
367 a Perl extension that is expressible in a bipartite or compound form (for
368 example, \f(CW\*(C`\ep{Present_In=4.0}\*(C'\fR), so \f(CW\*(C`charprop\*(C'\fR accepts it. But \f(CW\*(C`Any\*(C'\fR is a
369 Perl extension that isn\*(Aqt expressible that way, so \f(CW\*(C`charprop\*(C'\fR returns
370 \&\f(CW\*(C`undef\*(C'\fR for it. Also \f(CW\*(C`charprop\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR for all Perl extensions
371 that are internal\-only.
372 .SS \fBcharprops_all()\fP
373 .IX Subsection "charprops_all()"
374 .Vb 1
375 \& use Unicode::UCD \*(Aqcharprops_all\*(Aq;
376 \&
377 \& my $%properties_of_A_hash_ref = charprops_all("U+41");
378 .Ve
379 .PP
380 This returns a reference to a hash whose keys are all the distinct Unicode (no
381 Perl extension) properties, and whose values are the respective values for
382 those properties for the input "code point argument".
383 .PP
384 Each key is the property name in its longest, most descriptive form. The
385 values are what "\fBcharprop()\fR" would return.
386 .PP
387 This function is expensive in time and memory.
388 .SS \fBcharblock()\fP
389 .IX Subsection "charblock()"
390 .Vb 1
391 \& use Unicode::UCD \*(Aqcharblock\*(Aq;
392 \&
393 \& my $charblock = charblock(0x41);
394 \& my $charblock = charblock(1234);
395 \& my $charblock = charblock(0x263a);
396 \& my $charblock = charblock("U+263a");
397 \&
398 \& my $range = charblock(\*(AqArmenian\*(Aq);
399 .Ve
400 .PP
401 With a "code point argument" \f(CWcharblock()\fR returns the \fIblock\fR the code point
402 belongs to, e.g. \f(CW\*(C`Basic Latin\*(C'\fR. The old\-style block name is returned (see
403 "Old\-style versus new\-style block names").
404 The "\fBprop_value_aliases()\fR" function can be used to get all the synonyms
405 of the block name.
406 .PP
407 If the code point is unassigned, this returns the block it would belong to if
408 it were assigned. (If the Unicode version being used is so early as to not
409 have blocks, all code points are considered to be in \f(CW\*(C`No_Block\*(C'\fR.)
410 .PP
411 See also "Blocks versus Scripts".
412 .PP
413 If supplied with an argument that can\*(Aqt be a code point, \f(CWcharblock()\fR tries to
414 do the opposite and interpret the argument as an old\-style block name. On an
415 ASCII platform, the return value is a \fIrange set\fR with one range: an
416 anonymous array with a single element that consists of another anonymous array
417 whose first element is the first code point in the block, and whose second
418 element is the final code point in the block. On an EBCDIC
419 platform, the first two Unicode blocks are not contiguous. Their range sets
420 are lists containing \fIstart\-of\-range\fR, \fIend\-of\-range\fR code point pairs. You
421 can test whether a code point is in a range set using the "\fBcharinrange()\fR"
422 function. (To be precise, each \fIrange set\fR contains a third array element,
423 after the range boundary ones: the old_style block name.)
424 .PP
425 If the argument to \f(CWcharblock()\fR is not a known block, \f(CW\*(C`undef\*(C'\fR is
426 returned.
427 .SS \fBcharscript()\fP
428 .IX Subsection "charscript()"
429 .Vb 1
430 \& use Unicode::UCD \*(Aqcharscript\*(Aq;
431 \&
432 \& my $charscript = charscript(0x41);
433 \& my $charscript = charscript(1234);
434 \& my $charscript = charscript("U+263a");
435 \&
436 \& my $range = charscript(\*(AqThai\*(Aq);
437 .Ve
438 .PP
439 With a "code point argument", \f(CWcharscript()\fR returns the \fIscript\fR the
440 code point belongs to, e.g., \f(CW\*(C`Latin\*(C'\fR, \f(CW\*(C`Greek\*(C'\fR, \f(CW\*(C`Han\*(C'\fR.
441 If the code point is unassigned or the Unicode version being used is so early
442 that it doesn\*(Aqt have scripts, this function returns \f(CW"Unknown"\fR.
443 The "\fBprop_value_aliases()\fR" function can be used to get all the synonyms
444 of the script name.
445 .PP
446 Note that the Script_Extensions property is an improved version of the Script
447 property, and you should probably be using that instead, with the
448 "\fBcharprop()\fR" function.
449 .PP
450 If supplied with an argument that can\*(Aqt be a code point, \fBcharscript()\fR tries
451 to do the opposite and interpret the argument as a script name. The
452 return value is a \fIrange set\fR: an anonymous array of arrays that contain
453 \&\fIstart\-of\-range\fR, \fIend\-of\-range\fR code point pairs. You can test whether a
454 code point is in a range set using the "\fBcharinrange()\fR" function.
455 (To be precise, each \fIrange set\fR contains a third array element,
456 after the range boundary ones: the script name.)
457 .PP
458 If the \f(CWcharscript()\fR argument is not a known script, \f(CW\*(C`undef\*(C'\fR is returned.
459 .PP
460 See also "Blocks versus Scripts".
461 .SS \fBcharblocks()\fP
462 .IX Subsection "charblocks()"
463 .Vb 1
464 \& use Unicode::UCD \*(Aqcharblocks\*(Aq;
465 \&
466 \& my $charblocks = charblocks();
467 .Ve
468 .PP
469 \&\f(CWcharblocks()\fR returns a reference to a hash with the known block names
470 as the keys, and the code point ranges (see "\fBcharblock()\fR") as the values.
471 .PP
472 The names are in the old\-style (see "Old\-style versus new\-style block
473 names").
474 .PP
475 prop_invmap("block") can be used to get this same data in a
476 different type of data structure.
477 .PP
478 prop_values("Block") can be used to get all
479 the known new\-style block names as a list, without the code point ranges.
480 .PP
481 See also "Blocks versus Scripts".
482 .SS \fBcharscripts()\fP
483 .IX Subsection "charscripts()"
484 .Vb 1
485 \& use Unicode::UCD \*(Aqcharscripts\*(Aq;
486 \&
487 \& my $charscripts = charscripts();
488 .Ve
489 .PP
490 \&\f(CWcharscripts()\fR returns a reference to a hash with the known script
491 names as the keys, and the code point ranges (see "\fBcharscript()\fR") as
492 the values.
493 .PP
494 prop_invmap("script") can be used to get this same data in a
495 different type of data structure. Since the Script_Extensions property is an
496 improved version of the Script property, you should instead use
497 prop_invmap("scx").
498 .PP
499 \&\f(CWprop_values("Script")\fR can be used to get all
500 the known script names as a list, without the code point ranges.
501 .PP
502 See also "Blocks versus Scripts".
503 .SS \fBcharinrange()\fP
504 .IX Subsection "charinrange()"
505 In addition to using the \f(CW\*(C`\ep{Blk=...}\*(C'\fR and \f(CW\*(C`\eP{Blk=...}\*(C'\fR constructs, you
506 can also test whether a code point is in the \fIrange\fR as returned by
507 "\fBcharblock()\fR" and "\fBcharscript()\fR" or as the values of the hash returned
508 by "\fBcharblocks()\fR" and "\fBcharscripts()\fR" by using \f(CWcharinrange()\fR:
509 .PP
510 .Vb 1
511 \& use Unicode::UCD qw(charscript charinrange);
512 \&
513 \& $range = charscript(\*(AqHiragana\*(Aq);
514 \& print "looks like hiragana\en" if charinrange($range, $codepoint);
515 .Ve
516 .SS \fBgeneral_categories()\fP
517 .IX Subsection "general_categories()"
518 .Vb 1
519 \& use Unicode::UCD \*(Aqgeneral_categories\*(Aq;
520 \&
521 \& my $categories = general_categories();
522 .Ve
523 .PP
524 This returns a reference to a hash which has short
525 general category names (such as \f(CW\*(C`Lu\*(C'\fR, \f(CW\*(C`Nd\*(C'\fR, \f(CW\*(C`Zs\*(C'\fR, \f(CW\*(C`S\*(C'\fR) as keys and long
526 names (such as \f(CW\*(C`UppercaseLetter\*(C'\fR, \f(CW\*(C`DecimalNumber\*(C'\fR, \f(CW\*(C`SpaceSeparator\*(C'\fR,
527 \&\f(CW\*(C`Symbol\*(C'\fR) as values. The hash is reversible in case you need to go
528 from the long names to the short names. The general category is the
529 one returned from
530 "\fBcharinfo()\fR" under the \f(CW\*(C`category\*(C'\fR key.
531 .PP
532 The "\fBprop_values()\fR" and "\fBprop_value_aliases()\fR" functions can be used as an
533 alternative to this function; the first returning a simple list of the short
534 category names; and the second gets all the synonyms of a given category name.
535 .SS \fBbidi_types()\fP
536 .IX Subsection "bidi_types()"
537 .Vb 1
538 \& use Unicode::UCD \*(Aqbidi_types\*(Aq;
539 \&
540 \& my $categories = bidi_types();
541 .Ve
542 .PP
543 This returns a reference to a hash which has the short
544 bidi (bidirectional) type names (such as \f(CW\*(C`L\*(C'\fR, \f(CW\*(C`R\*(C'\fR) as keys and long
545 names (such as \f(CW\*(C`Left\-to\-Right\*(C'\fR, \f(CW\*(C`Right\-to\-Left\*(C'\fR) as values. The
546 hash is reversible in case you need to go from the long names to the
547 short names. The bidi type is the one returned from
548 "\fBcharinfo()\fR"
549 under the \f(CW\*(C`bidi\*(C'\fR key. For the exact meaning of the various bidi classes
550 the Unicode TR9 is recommended reading:
551 <http://www.unicode.org/reports/tr9/>
552 (as of Unicode 5.0.0)
553 .PP
554 The "\fBprop_values()\fR" and "\fBprop_value_aliases()\fR" functions can be used as an
555 alternative to this function; the first returning a simple list of the short
556 bidi type names; and the second gets all the synonyms of a given bidi type
557 name.
558 .SS \fBcompexcl()\fP
559 .IX Subsection "compexcl()"
560 WARNING: Unicode discourages the use of this function or any of the
561 alternative mechanisms listed in this section (the documentation of
562 \&\f(CWcompexcl()\fR), except internally in implementations of the Unicode
563 Normalization Algorithm. You should be using Unicode::Normalize directly
564 instead of these. Using these will likely lead to half\-baked results.
565 .PP
566 .Vb 1
567 \& use Unicode::UCD \*(Aqcompexcl\*(Aq;
568 \&
569 \& my $compexcl = compexcl(0x09dc);
570 .Ve
571 .PP
572 This routine returns \f(CW\*(C`undef\*(C'\fR if the Unicode version being used is so early
573 that it doesn\*(Aqt have this property.
574 .PP
575 \&\f(CWcompexcl()\fR is included for backwards
576 compatibility, but as of Perl 5.12 and more modern Unicode versions, for
577 most purposes it is probably more convenient to use one of the following
578 instead:
579 .PP
580 .Vb 2
581 \& my $compexcl = chr(0x09dc) =~ /\ep{Comp_Ex};
582 \& my $compexcl = chr(0x09dc) =~ /\ep{Full_Composition_Exclusion};
583 .Ve
584 .PP
585 or even
586 .PP
587 .Vb 2
588 \& my $compexcl = chr(0x09dc) =~ /\ep{CE};
589 \& my $compexcl = chr(0x09dc) =~ /\ep{Composition_Exclusion};
590 .Ve
591 .PP
592 The first two forms return \fBtrue\fR if the "code point argument" should not
593 be produced by composition normalization. For the final two forms to return
594 \&\fBtrue\fR, it is additionally required that this fact not otherwise be
595 determinable from the Unicode data base.
596 .PP
597 This routine behaves identically to the final two forms. That is,
598 it does not return \fBtrue\fR if the code point has a decomposition
599 consisting of another single code point, nor if its decomposition starts
600 with a code point whose combining class is non\-zero. Code points that meet
601 either of these conditions should also not be produced by composition
602 normalization, which is probably why you should use the
603 \&\f(CW\*(C`Full_Composition_Exclusion\*(C'\fR property instead, as shown above.
604 .PP
605 The routine returns \fBfalse\fR otherwise.
606 .SS \fBcasefold()\fP
607 .IX Subsection "casefold()"
608 .Vb 1
609 \& use Unicode::UCD \*(Aqcasefold\*(Aq;
610 \&
611 \& my $casefold = casefold(0xDF);
612 \& if (defined $casefold) {
613 \& my @full_fold_hex = split / /, $casefold\->{\*(Aqfull\*(Aq};
614 \& my $full_fold_string =
615 \& join "", map {chr(hex($_))} @full_fold_hex;
616 \& my @turkic_fold_hex =
617 \& split / /, ($casefold\->{\*(Aqturkic\*(Aq} ne "")
618 \& ? $casefold\->{\*(Aqturkic\*(Aq}
619 \& : $casefold\->{\*(Aqfull\*(Aq};
620 \& my $turkic_fold_string =
621 \& join "", map {chr(hex($_))} @turkic_fold_hex;
622 \& }
623 \& if (defined $casefold && $casefold\->{\*(Aqsimple\*(Aq} ne "") {
624 \& my $simple_fold_hex = $casefold\->{\*(Aqsimple\*(Aq};
625 \& my $simple_fold_string = chr(hex($simple_fold_hex));
626 \& }
627 .Ve
628 .PP
629 This returns the (almost) locale\-independent case folding of the
630 character specified by the "code point argument". (Starting in Perl v5.16,
631 the core function \f(CWfc()\fR returns the \f(CW\*(C`full\*(C'\fR mapping (described below)
632 faster than this does, and for entire strings.)
633 .PP
634 If there is no case folding for the input code point, \f(CW\*(C`undef\*(C'\fR is returned.
635 .PP
636 If there is a case folding for that code point, a reference to a hash
637 with the following fields is returned:
638 .IP \fBcode\fR 4
639 .IX Item "code"
640 the input native "code point argument" expressed in hexadecimal, with
641 leading zeros
642 added if necessary to make it contain at least four hexdigits
643 .IP \fBfull\fR 4
644 .IX Item "full"
645 one or more codes (separated by spaces) that, taken in order, give the
646 code points for the case folding for \fIcode\fR.
647 Each has at least four hexdigits.
648 .IP \fBsimple\fR 4
649 .IX Item "simple"
650 is empty, or is exactly one code with at least four hexdigits which can be used
651 as an alternative case folding when the calling program cannot cope with the
652 fold being a sequence of multiple code points. If \fIfull\fR is just one code
653 point, then \fIsimple\fR equals \fIfull\fR. If there is no single code point folding
654 defined for \fIcode\fR, then \fIsimple\fR is the empty string. Otherwise, it is an
655 inferior, but still better\-than\-nothing alternative folding to \fIfull\fR.
656 .IP \fBmapping\fR 4
657 .IX Item "mapping"
658 is the same as \fIsimple\fR if \fIsimple\fR is not empty, and it is the same as \fIfull\fR
659 otherwise. It can be considered to be the simplest possible folding for
660 \&\fIcode\fR. It is defined primarily for backwards compatibility.
661 .IP \fBstatus\fR 4
662 .IX Item "status"
663 is \f(CW\*(C`C\*(C'\fR (for \f(CW\*(C`common\*(C'\fR) if the best possible fold is a single code point
664 (\fIsimple\fR equals \fIfull\fR equals \fImapping\fR). It is \f(CW\*(C`S\*(C'\fR if there are distinct
665 folds, \fIsimple\fR and \fIfull\fR (\fImapping\fR equals \fIsimple\fR). And it is \f(CW\*(C`F\*(C'\fR if
666 there is only a \fIfull\fR fold (\fImapping\fR equals \fIfull\fR; \fIsimple\fR is empty).
667 Note that this
668 describes the contents of \fImapping\fR. It is defined primarily for backwards
669 compatibility.
670 .Sp
671 For Unicode versions between 3.1 and 3.1.1 inclusive, \fIstatus\fR can also be
672 \&\f(CW\*(C`I\*(C'\fR which is the same as \f(CW\*(C`C\*(C'\fR but is a special case for dotted uppercase I and
673 dotless lowercase i:
674 .RS 4
675 .ie n .IP "\fB*\fR If you use this ""I"" mapping" 4
676 .el .IP "\fB*\fR If you use this \f(CWI\fR mapping" 4
677 .IX Item "* If you use this I mapping"
678 the result is case\-insensitive,
679 but dotless and dotted I\*(Aqs are not distinguished
680 .ie n .IP "\fB*\fR If you exclude this ""I"" mapping" 4
681 .el .IP "\fB*\fR If you exclude this \f(CWI\fR mapping" 4
682 .IX Item "* If you exclude this I mapping"
683 the result is not fully case\-insensitive, but
684 dotless and dotted I\*(Aqs are distinguished
685 .RE
686 .RS 4
687 .RE
688 .IP \fBturkic\fR 4
689 .IX Item "turkic"
690 contains any special folding for Turkic languages. For versions of Unicode
691 starting with 3.2, this field is empty unless \fIcode\fR has a different folding
692 in Turkic languages, in which case it is one or more codes (separated by
693 spaces) that, taken in order, give the code points for the case folding for
694 \&\fIcode\fR in those languages.
695 Each code has at least four hexdigits.
696 Note that this folding does not maintain canonical equivalence without
697 additional processing.
698 .Sp
699 For Unicode versions between 3.1 and 3.1.1 inclusive, this field is empty unless
700 there is a
701 special folding for Turkic languages, in which case \fIstatus\fR is \f(CW\*(C`I\*(C'\fR, and
702 \&\fImapping\fR, \fIfull\fR, \fIsimple\fR, and \fIturkic\fR are all equal.
703 .PP
704 Programs that want complete generality and the best folding results should use
705 the folding contained in the \fIfull\fR field. But note that the fold for some
706 code points will be a sequence of multiple code points.
707 .PP
708 Programs that can\*(Aqt cope with the fold mapping being multiple code points can
709 use the folding contained in the \fIsimple\fR field, with the loss of some
710 generality. In Unicode 5.1, about 7% of the defined foldings have no single
711 code point folding.
712 .PP
713 The \fImapping\fR and \fIstatus\fR fields are provided for backwards compatibility for
714 existing programs. They contain the same values as in previous versions of
715 this function.
716 .PP
717 Locale is not completely independent. The \fIturkic\fR field contains results to
718 use when the locale is a Turkic language.
719 .PP
720 For more information about case mappings see
721 <http://www.unicode.org/reports/tr21>
722 .SS \fBall_casefolds()\fP
723 .IX Subsection "all_casefolds()"
724 .Vb 1
725 \& use Unicode::UCD \*(Aqall_casefolds\*(Aq;
726 \&
727 \& my $all_folds_ref = all_casefolds();
728 \& foreach my $char_with_casefold (sort { $a <=> $b }
729 \& keys %$all_folds_ref)
730 \& {
731 \& printf "%04X:", $char_with_casefold;
732 \& my $casefold = $all_folds_ref\->{$char_with_casefold};
733 \&
734 \& # Get folds for $char_with_casefold
735 \&
736 \& my @full_fold_hex = split / /, $casefold\->{\*(Aqfull\*(Aq};
737 \& my $full_fold_string =
738 \& join "", map {chr(hex($_))} @full_fold_hex;
739 \& print " full=", join " ", @full_fold_hex;
740 \& my @turkic_fold_hex =
741 \& split / /, ($casefold\->{\*(Aqturkic\*(Aq} ne "")
742 \& ? $casefold\->{\*(Aqturkic\*(Aq}
743 \& : $casefold\->{\*(Aqfull\*(Aq};
744 \& my $turkic_fold_string =
745 \& join "", map {chr(hex($_))} @turkic_fold_hex;
746 \& print "; turkic=", join " ", @turkic_fold_hex;
747 \& if (defined $casefold && $casefold\->{\*(Aqsimple\*(Aq} ne "") {
748 \& my $simple_fold_hex = $casefold\->{\*(Aqsimple\*(Aq};
749 \& my $simple_fold_string = chr(hex($simple_fold_hex));
750 \& print "; simple=$simple_fold_hex";
751 \& }
752 \& print "\en";
753 \& }
754 .Ve
755 .PP
756 This returns all the case foldings in the current version of Unicode in the
757 form of a reference to a hash. Each key to the hash is the decimal
758 representation of a Unicode character that has a casefold to other than
759 itself. The casefold of a semi\-colon is itself, so it isn\*(Aqt in the hash;
760 likewise for a lowercase "a", but there is an entry for a capital "A". The
761 hash value for each key is another hash, identical to what is returned by
762 "\fBcasefold()\fR" if called with that code point as its argument. So the value
763 \&\f(CW\*(C`all_casefolds()\->{ord("A")}\*(Aq\*(C'\fR is equivalent to \f(CW\*(C`casefold(ord("A"))\*(C'\fR;
764 .SS \fBcasespec()\fP
765 .IX Subsection "casespec()"
766 .Vb 1
767 \& use Unicode::UCD \*(Aqcasespec\*(Aq;
768 \&
769 \& my $casespec = casespec(0xFB00);
770 .Ve
771 .PP
772 This returns the potentially locale\-dependent case mappings of the "code point
773 argument". The mappings may be longer than a single code point (which the basic
774 Unicode case mappings as returned by "\fBcharinfo()\fR" never are).
775 .PP
776 If there are no case mappings for the "code point argument", or if all three
777 possible mappings (\fIlower\fR, \fItitle\fR and \fIupper\fR) result in single code
778 points and are locale independent and unconditional, \f(CW\*(C`undef\*(C'\fR is returned
779 (which means that the case mappings, if any, for the code point are those
780 returned by "\fBcharinfo()\fR").
781 .PP
782 Otherwise, a reference to a hash giving the mappings (or a reference to a hash
783 of such hashes, explained below) is returned with the following keys and their
784 meanings:
785 .PP
786 The keys in the bottom layer hash with the meanings of their values are:
787 .IP \fBcode\fR 4
788 .IX Item "code"
789 the input native "code point argument" expressed in hexadecimal, with
790 leading zeros
791 added if necessary to make it contain at least four hexdigits
792 .IP \fBlower\fR 4
793 .IX Item "lower"
794 one or more codes (separated by spaces) that, taken in order, give the
795 code points for the lower case of \fIcode\fR.
796 Each has at least four hexdigits.
797 .IP \fBtitle\fR 4
798 .IX Item "title"
799 one or more codes (separated by spaces) that, taken in order, give the
800 code points for the title case of \fIcode\fR.
801 Each has at least four hexdigits.
802 .IP \fBupper\fR 4
803 .IX Item "upper"
804 one or more codes (separated by spaces) that, taken in order, give the
805 code points for the upper case of \fIcode\fR.
806 Each has at least four hexdigits.
807 .IP \fBcondition\fR 4
808 .IX Item "condition"
809 the conditions for the mappings to be valid.
810 If \f(CW\*(C`undef\*(C'\fR, the mappings are always valid.
811 When defined, this field is a list of conditions,
812 all of which must be true for the mappings to be valid.
813 The list consists of one or more
814 \&\fIlocales\fR (see below)
815 and/or \fIcontexts\fR (explained in the next paragraph),
816 separated by spaces.
817 (Other than as used to separate elements, spaces are to be ignored.)
818 Case distinctions in the condition list are not significant.
819 Conditions preceded by "NON_" represent the negation of the condition.
820 .Sp
821 A \fIcontext\fR is one of those defined in the Unicode standard.
822 For Unicode 5.1, they are defined in Section 3.13 \f(CW\*(C`Default Case Operations\*(C'\fR
823 available at
824 <http://www.unicode.org/versions/Unicode5.1.0/>.
825 These are for context\-sensitive casing.
826 .PP
827 The hash described above is returned for locale\-independent casing, where
828 at least one of the mappings has length longer than one. If \f(CW\*(C`undef\*(C'\fR is
829 returned, the code point may have mappings, but if so, all are length one,
830 and are returned by "\fBcharinfo()\fR".
831 Note that when this function does return a value, it will be for the complete
832 set of mappings for a code point, even those whose length is one.
833 .PP
834 If there are additional casing rules that apply only in certain locales,
835 an additional key for each will be defined in the returned hash. Each such key
836 will be its locale name, defined as a 2\-letter ISO 3166 country code, possibly
837 followed by a "_" and a 2\-letter ISO language code (possibly followed by a "_"
838 and a variant code). You can find the lists of all possible locales, see
839 Locale::Country and Locale::Language.
840 (In Unicode 6.0, the only locales returned by this function
841 are \f(CW\*(C`lt\*(C'\fR, \f(CW\*(C`tr\*(C'\fR, and \f(CW\*(C`az\*(C'\fR.)
842 .PP
843 Each locale key is a reference to a hash that has the form above, and gives
844 the casing rules for that particular locale, which take precedence over the
845 locale\-independent ones when in that locale.
846 .PP
847 If the only casing for a code point is locale\-dependent, then the returned
848 hash will not have any of the base keys, like \f(CW\*(C`code\*(C'\fR, \f(CW\*(C`upper\*(C'\fR, etc., but
849 will contain only locale keys.
850 .PP
851 For more information about case mappings see
852 <http://www.unicode.org/reports/tr21/>
853 .SS \fBnamedseq()\fP
854 .IX Subsection "namedseq()"
855 .Vb 1
856 \& use Unicode::UCD \*(Aqnamedseq\*(Aq;
857 \&
858 \& my $namedseq = namedseq("KATAKANA LETTER AINU P");
859 \& my @namedseq = namedseq("KATAKANA LETTER AINU P");
860 \& my %namedseq = namedseq();
861 .Ve
862 .PP
863 If used with a single argument in a scalar context, returns the string
864 consisting of the code points of the named sequence, or \f(CW\*(C`undef\*(C'\fR if no
865 named sequence by that name exists. If used with a single argument in
866 a list context, it returns the list of the ordinals of the code points.
867 .PP
868 If used with no
869 arguments in a list context, it returns a hash with the names of all the
870 named sequences as the keys and their sequences as strings as
871 the values. Otherwise, it returns \f(CW\*(C`undef\*(C'\fR or an empty list depending
872 on the context.
873 .PP
874 This function only operates on officially approved (not provisional) named
875 sequences.
876 .PP
877 Note that as of Perl 5.14, \f(CW\*(C`\eN{KATAKANA LETTER AINU P}\*(C'\fR will insert the named
878 sequence into double\-quoted strings, and \f(CW\*(C`charnames::string_vianame("KATAKANA
879 LETTER AINU P")\*(C'\fR will return the same string this function does, but will also
880 operate on character names that aren\*(Aqt named sequences, without you having to
881 know which are which. See charnames.
882 .SS \fBnum()\fP
883 .IX Subsection "num()"
884 .Vb 1
885 \& use Unicode::UCD \*(Aqnum\*(Aq;
886 \&
887 \& my $val = num("123");
888 \& my $one_quarter = num("\eN{VULGAR FRACTION ONE QUARTER}");
889 \& my $val = num("12a", \e$valid_length); # $valid_length contains 2
890 .Ve
891 .PP
892 \&\f(CWnum()\fR returns the numeric value of the input Unicode string; or \f(CW\*(C`undef\*(C'\fR if it
893 doesn\*(Aqt think the entire string has a completely valid, safe numeric value.
894 If called with an optional second parameter, a reference to a scalar, \f(CWnum()\fR
895 will set the scalar to the length of any valid initial substring; or to 0 if none.
896 .PP
897 If the string is just one character in length, the Unicode numeric value
898 is returned if it has one, or \f(CW\*(C`undef\*(C'\fR otherwise. If the optional scalar ref
899 is passed, it would be set to 1 if the return is valid; or 0 if the return is
900 \&\f(CW\*(C`undef\*(C'\fR. Note that the numeric value returned need not be a whole number.
901 \&\f(CW\*(C`num("\eN{TIBETAN DIGIT HALF ZERO}")\*(C'\fR, for example returns \-0.5.
902 .PP
903 If the string is more than one character, \f(CW\*(C`undef\*(C'\fR is returned unless
904 all its characters are decimal digits (that is, they would match \f(CW\*(C`\ed+\*(C'\fR),
905 from the same script. For example if you have an ASCII \*(Aq0\*(Aq and a Bengali
906 \&\*(Aq3\*(Aq, mixed together, they aren\*(Aqt considered a valid number, and \f(CW\*(C`undef\*(C'\fR
907 is returned. A further restriction is that the digits all have to be of
908 the same form. A half\-width digit mixed with a full\-width one will
909 return \f(CW\*(C`undef\*(C'\fR. The Arabic script has two sets of digits; \f(CW\*(C`num\*(C'\fR will
910 return \f(CW\*(C`undef\*(C'\fR unless all the digits in the string come from the same
911 set. In all cases, the optional scalar ref parameter is set to how
912 long any valid initial substring of digits is; hence it will be set to the
913 entire string length if the main return value is not \f(CW\*(C`undef\*(C'\fR.
914 .PP
915 \&\f(CW\*(C`num\*(C'\fR errs on the side of safety, and there may be valid strings of
916 decimal digits that it doesn\*(Aqt recognize. Note that Unicode defines
917 a number of "digit" characters that aren\*(Aqt "decimal digit" characters.
918 "Decimal digits" have the property that they have a positional value, i.e.,
919 there is a units position, a 10\*(Aqs position, a 100\*(Aqs, etc, AND they are
920 arranged in Unicode in blocks of 10 contiguous code points. The Chinese
921 digits, for example, are not in such a contiguous block, and so Unicode
922 doesn\*(Aqt view them as decimal digits, but merely digits, and so \f(CW\*(C`\ed\*(C'\fR will not
923 match them. A single\-character string containing one of these digits will
924 have its decimal value returned by \f(CW\*(C`num\*(C'\fR, but any longer string containing
925 only these digits will return \f(CW\*(C`undef\*(C'\fR.
926 .PP
927 To illustrate further, the Rumi numeric symbols were used in centuries past in
928 and around North Africa and the Iberian peninsula. In order to be able to
929 digitize the many historical documents that use them, Unicode has encoded the
930 set. There is no character representing zero. There are characters for one
931 through nine, ten, twenty, and so forth. \f(CW\*(C`num\*(C'\fR correctly returns the values
932 of these in isolation.
933 .PP
934 .Vb 4
935 \& my $rumi_one = num("\eN{RUMI DIGIT ONE}");
936 \& my $rumi_two = num("\eN{RUMI DIGIT TWO}");
937 \& my $rumi_twenty = num("\eN{RUMI NUMBER TWENTY}");
938 \& say "$rumi_one $rumi_two $rumi_twenty"; # 1 2 20
939 .Ve
940 .PP
941 Because these do not follow modern decimal positional notation, stringing more
942 than one of these together doesn\*(Aqt mean what you likely would think it means.
943 So, \f(CW\*(C`num\*(C'\fR correctly returns \f(CW\*(C`undef\*(C'\fR if you try. If you request the length
944 of the valid initial substring in this case, that length would be one.
945 .PP
946 .Vb 3
947 \& my $len;
948 \& my $value = num("\eN{RUMI DIGIT ONE}\eN{RUMI DIGIT TWO}", \e$len);
949 \& say $len, " ", (defined $value) ? $value : "undef"; # 1 undef
950 .Ve
951 .PP
952 How to represent numbers like twelve gets complicated, and Unicode doesn\*(Aqt
953 give any guidance, so \f(CW\*(C`num\*(C'\fR can\*(Aqt either.
954 .PP
955 Strings of multiple sub\- and superscripts are not recognized as numbers. You
956 can use either of the compatibility decompositions in Unicode::Normalize to
957 change these into digits, and then call \f(CW\*(C`num\*(C'\fR on the result.
958 .SS \fBprop_aliases()\fP
959 .IX Subsection "prop_aliases()"
960 .Vb 1
961 \& use Unicode::UCD \*(Aqprop_aliases\*(Aq;
962 \&
963 \& my ($short_name, $full_name, @other_names) = prop_aliases("space");
964 \& my $same_full_name = prop_aliases("Space"); # Scalar context
965 \& my ($same_short_name) = prop_aliases("Space"); # gets 0th element
966 \& print "The full name is $full_name\en";
967 \& print "The short name is $short_name\en";
968 \& print "The other aliases are: ", join(", ", @other_names), "\en";
969 \&
970 \& prints:
971 \& The full name is White_Space
972 \& The short name is WSpace
973 \& The other aliases are: Space
974 .Ve
975 .PP
976 Most Unicode properties have several synonymous names. Typically, there is at
977 least a short name, convenient to type, and a long name that more fully
978 describes the property, and hence is more easily understood.
979 .PP
980 If you know one name for a Unicode property, you can use \f(CW\*(C`prop_aliases\*(C'\fR to find
981 either the long name (when called in scalar context), or a list of all of the
982 names, somewhat ordered so that the short name is in the 0th element, the long
983 name in the next element, and any other synonyms are in the remaining
984 elements, in no particular order.
985 .PP
986 The long name is returned in a form nicely capitalized, suitable for printing.
987 .PP
988 The input parameter name is loosely matched, which means that white space,
989 hyphens, and underscores are ignored (except for the trailing underscore in
990 the old_form grandfathered\-in \f(CW"L_"\fR, which is better written as \f(CW"LC"\fR, and
991 both of which mean \f(CW\*(C`General_Category=Cased Letter\*(C'\fR).
992 .PP
993 If the name is unknown, \f(CW\*(C`undef\*(C'\fR is returned (or an empty list in list
994 context). Note that Perl typically recognizes property names in regular
995 expressions with an optional \f(CW\*(C`"Is_\*(C'\fR" (with or without the underscore)
996 prefixed to them, such as \f(CW\*(C`\ep{isgc=punct}\*(C'\fR. This function does not recognize
997 those in the input, returning \f(CW\*(C`undef\*(C'\fR. Nor are they included in the output
998 as possible synonyms.
999 .PP
1000 \&\f(CW\*(C`prop_aliases\*(C'\fR does know about the Perl extensions to Unicode properties,
1001 such as \f(CW\*(C`Any\*(C'\fR and \f(CW\*(C`XPosixAlpha\*(C'\fR, and the single form equivalents to Unicode
1002 properties such as \f(CW\*(C`XDigit\*(C'\fR, \f(CW\*(C`Greek\*(C'\fR, \f(CW\*(C`In_Greek\*(C'\fR, and \f(CW\*(C`Is_Greek\*(C'\fR. The
1003 final example demonstrates that the \f(CW"Is_"\fR prefix is recognized for these
1004 extensions; it is needed to resolve ambiguities. For example,
1005 \&\f(CWprop_aliases(\*(Aqlc\*(Aq)\fR returns the list \f(CW\*(C`(lc, Lowercase_Mapping)\*(C'\fR, but
1006 \&\f(CWprop_aliases(\*(Aqislc\*(Aq)\fR returns \f(CW\*(C`(Is_LC, Cased_Letter)\*(C'\fR. This is
1007 because \f(CW\*(C`islc\*(C'\fR is a Perl extension which is short for
1008 \&\f(CW\*(C`General_Category=Cased Letter\*(C'\fR. The lists returned for the Perl extensions
1009 will not include the \f(CW"Is_"\fR prefix (whether or not the input had it) unless
1010 needed to resolve ambiguities, as shown in the \f(CW"islc"\fR example, where the
1011 returned list had one element containing \f(CW"Is_"\fR, and the other without.
1012 .PP
1013 It is also possible for the reverse to happen: \f(CWprop_aliases(\*(Aqisc\*(Aq)\fR returns
1014 the list \f(CW\*(C`(isc, ISO_Comment)\*(C'\fR; whereas \f(CWprop_aliases(\*(Aqc\*(Aq)\fR returns
1015 \&\f(CW\*(C`(C, Other)\*(C'\fR (the latter being a Perl extension meaning
1016 \&\f(CW\*(C`General_Category=Other\*(C'\fR.
1017 "Properties accessible through Unicode::UCD" in perluniprops lists the available
1018 forms, including which ones are discouraged from use.
1019 .PP
1020 Those discouraged forms are accepted as input to \f(CW\*(C`prop_aliases\*(C'\fR, but are not
1021 returned in the lists. \f(CWprop_aliases(\*(AqisL&\*(Aq)\fR and \f(CWprop_aliases(\*(AqisL_\*(Aq)\fR,
1022 which are old synonyms for \f(CW"Is_LC"\fR and should not be used in new code, are
1023 examples of this. These both return \f(CW\*(C`(Is_LC, Cased_Letter)\*(C'\fR. Thus this
1024 function allows you to take a discouraged form, and find its acceptable
1025 alternatives. The same goes with single\-form Block property equivalences.
1026 Only the forms that begin with \f(CW"In_"\fR are not discouraged; if you pass
1027 \&\f(CW\*(C`prop_aliases\*(C'\fR a discouraged form, you will get back the equivalent ones that
1028 begin with \f(CW"In_"\fR. It will otherwise look like a new\-style block name (see.
1029 "Old\-style versus new\-style block names").
1030 .PP
1031 \&\f(CW\*(C`prop_aliases\*(C'\fR does not know about any user\-defined properties, and will
1032 return \f(CW\*(C`undef\*(C'\fR if called with one of those. Likewise for Perl internal
1033 properties, with the exception of "Perl_Decimal_Digit" which it does know
1034 about (and which is documented below in "\fBprop_invmap()\fR").
1035 .SS \fBprop_values()\fP
1036 .IX Subsection "prop_values()"
1037 .Vb 1
1038 \& use Unicode::UCD \*(Aqprop_values\*(Aq;
1039 \&
1040 \& print "AHex values are: ", join(", ", prop_values("AHex")),
1041 \& "\en";
1042 \& prints:
1043 \& AHex values are: N, Y
1044 .Ve
1045 .PP
1046 Some Unicode properties have a restricted set of legal values. For example,
1047 all binary properties are restricted to just \f(CW\*(C`true\*(C'\fR or \f(CW\*(C`false\*(C'\fR; and there
1048 are only a few dozen possible General Categories. Use \f(CW\*(C`prop_values\*(C'\fR
1049 to find out if a given property is one such, and if so, to get a list of the
1050 values:
1051 .PP
1052 .Vb 3
1053 \& print join ", ", prop_values("NFC_Quick_Check");
1054 \& prints:
1055 \& M, N, Y
1056 .Ve
1057 .PP
1058 If the property doesn\*(Aqt have such a restricted set, \f(CW\*(C`undef\*(C'\fR is returned.
1059 .PP
1060 There are usually several synonyms for each possible value. Use
1061 "\fBprop_value_aliases()\fR" to access those.
1062 .PP
1063 Case, white space, hyphens, and underscores are ignored in the input property
1064 name (except for the trailing underscore in the old\-form grandfathered\-in
1065 general category property value \f(CW"L_"\fR, which is better written as \f(CW"LC"\fR).
1066 .PP
1067 If the property name is unknown, \f(CW\*(C`undef\*(C'\fR is returned. Note that Perl typically
1068 recognizes property names in regular expressions with an optional \f(CW\*(C`"Is_\*(C'\fR"
1069 (with or without the underscore) prefixed to them, such as \f(CW\*(C`\ep{isgc=punct}\*(C'\fR.
1070 This function does not recognize those in the property parameter, returning
1071 \&\f(CW\*(C`undef\*(C'\fR.
1072 .PP
1073 For the block property, new\-style block names are returned (see
1074 "Old\-style versus new\-style block names").
1075 .PP
1076 \&\f(CW\*(C`prop_values\*(C'\fR does not know about any user\-defined properties, and
1077 will return \f(CW\*(C`undef\*(C'\fR if called with one of those.
1078 .SS \fBprop_value_aliases()\fP
1079 .IX Subsection "prop_value_aliases()"
1080 .Vb 1
1081 \& use Unicode::UCD \*(Aqprop_value_aliases\*(Aq;
1082 \&
1083 \& my ($short_name, $full_name, @other_names)
1084 \& = prop_value_aliases("Gc", "Punct");
1085 \& my $same_full_name = prop_value_aliases("Gc", "P"); # Scalar cntxt
1086 \& my ($same_short_name) = prop_value_aliases("Gc", "P"); # gets 0th
1087 \& # element
1088 \& print "The full name is $full_name\en";
1089 \& print "The short name is $short_name\en";
1090 \& print "The other aliases are: ", join(", ", @other_names), "\en";
1091 \&
1092 \& prints:
1093 \& The full name is Punctuation
1094 \& The short name is P
1095 \& The other aliases are: Punct
1096 .Ve
1097 .PP
1098 Some Unicode properties have a restricted set of legal values. For example,
1099 all binary properties are restricted to just \f(CW\*(C`true\*(C'\fR or \f(CW\*(C`false\*(C'\fR; and there
1100 are only a few dozen possible General Categories.
1101 .PP
1102 You can use "\fBprop_values()\fR" to find out if a given property is one which has
1103 a restricted set of values, and if so, what those values are. But usually
1104 each value actually has several synonyms. For example, in Unicode binary
1105 properties, \fItruth\fR can be represented by any of the strings "Y", "Yes", "T",
1106 or "True"; and the General Category "Punctuation" by that string, or "Punct",
1107 or simply "P".
1108 .PP
1109 Like property names, there is typically at least a short name for each such
1110 property\-value, and a long name. If you know any name of the property\-value
1111 (which you can get by "\fBprop_values()\fR", you can use \f(CW\*(C`prop_value_aliases\*(C'\fR()
1112 to get the long name (when called in scalar context), or a list of all the
1113 names, with the short name in the 0th element, the long name in the next
1114 element, and any other synonyms in the remaining elements, in no particular
1115 order, except that any all\-numeric synonyms will be last.
1116 .PP
1117 The long name is returned in a form nicely capitalized, suitable for printing.
1118 .PP
1119 Case, white space, hyphens, and underscores are ignored in the input parameters
1120 (except for the trailing underscore in the old\-form grandfathered\-in general
1121 category property value \f(CW"L_"\fR, which is better written as \f(CW"LC"\fR).
1122 .PP
1123 If either name is unknown, \f(CW\*(C`undef\*(C'\fR is returned. Note that Perl typically
1124 recognizes property names in regular expressions with an optional \f(CW\*(C`"Is_\*(C'\fR"
1125 (with or without the underscore) prefixed to them, such as \f(CW\*(C`\ep{isgc=punct}\*(C'\fR.
1126 This function does not recognize those in the property parameter, returning
1127 \&\f(CW\*(C`undef\*(C'\fR.
1128 .PP
1129 If called with a property that doesn\*(Aqt have synonyms for its values, it
1130 returns the input value, possibly normalized with capitalization and
1131 underscores, but not necessarily checking that the input value is valid.
1132 .PP
1133 For the block property, new\-style block names are returned (see
1134 "Old\-style versus new\-style block names").
1135 .PP
1136 To find the synonyms for single\-forms, such as \f(CW\*(C`\ep{Any}\*(C'\fR, use
1137 "\fBprop_aliases()\fR" instead.
1138 .PP
1139 \&\f(CW\*(C`prop_value_aliases\*(C'\fR does not know about any user\-defined properties, and
1140 will return \f(CW\*(C`undef\*(C'\fR if called with one of those.
1141 .SS \fBprop_invlist()\fP
1142 .IX Subsection "prop_invlist()"
1143 \&\f(CW\*(C`prop_invlist\*(C'\fR returns an inversion list (described below) that defines all the
1144 code points for the binary Unicode property (or "property=value" pair) given
1145 by the input parameter string:
1146 .PP
1147 .Vb 3
1148 \& use feature \*(Aqsay\*(Aq;
1149 \& use Unicode::UCD \*(Aqprop_invlist\*(Aq;
1150 \& say join ", ", prop_invlist("Any");
1151 \&
1152 \& prints:
1153 \& 0, 1114112
1154 .Ve
1155 .PP
1156 If the input is unknown \f(CW\*(C`undef\*(C'\fR is returned in scalar context; an empty\-list
1157 in list context. If the input is known, the number of elements in
1158 the list is returned if called in scalar context.
1159 .PP
1160 perluniprops gives
1161 the list of properties that this function accepts, as well as all the possible
1162 forms for them (including with the optional "Is_" prefixes). (Except this
1163 function doesn\*(Aqt accept any Perl\-internal properties, some of which are listed
1164 there.) This function uses the same loose or tighter matching rules for
1165 resolving the input property\*(Aqs name as is done for regular expressions. These
1166 are also specified in perluniprops. Examples of using the "property=value" form are:
1167 .PP
1168 .Vb 1
1169 \& say join ", ", prop_invlist("Script_Extensions=Shavian");
1170 \&
1171 \& prints:
1172 \& 66640, 66688
1173 \&
1174 \& say join ", ", prop_invlist("ASCII_Hex_Digit=No");
1175 \&
1176 \& prints:
1177 \& 0, 48, 58, 65, 71, 97, 103
1178 \&
1179 \& say join ", ", prop_invlist("ASCII_Hex_Digit=Yes");
1180 \&
1181 \& prints:
1182 \& 48, 58, 65, 71, 97, 103
1183 .Ve
1184 .PP
1185 Inversion lists are a compact way of specifying Unicode property\-value
1186 definitions. The 0th item in the list is the lowest code point that has the
1187 property\-value. The next item (item [1]) is the lowest code point beyond that
1188 one that does NOT have the property\-value. And the next item beyond that
1189 ([2]) is the lowest code point beyond that one that does have the
1190 property\-value, and so on. Put another way, each element in the list gives
1191 the beginning of a range that has the property\-value (for even numbered
1192 elements), or doesn\*(Aqt have the property\-value (for odd numbered elements).
1193 The name for this data structure stems from the fact that each element in the
1194 list toggles (or inverts) whether the corresponding range is or isn\*(Aqt on the
1195 list.
1196 .PP
1197 In the final example above, the first ASCII Hex digit is code point 48, the
1198 character "0", and all code points from it through 57 (a "9") are ASCII hex
1199 digits. Code points 58 through 64 aren\*(Aqt, but 65 (an "A") through 70 (an "F")
1200 are, as are 97 ("a") through 102 ("f"). 103 starts a range of code points
1201 that aren\*(Aqt ASCII hex digits. That range extends to infinity, which on your
1202 computer can be found in the variable \f(CW$Unicode::UCD::MAX_CP\fR. (This
1203 variable is as close to infinity as Perl can get on your platform, and may be
1204 too high for some operations to work; you may wish to use a smaller number for
1205 your purposes.)
1206 .PP
1207 Note that the inversion lists returned by this function can possibly include
1208 non\-Unicode code points, that is anything above 0x10FFFF. Unicode properties
1209 are not defined on such code points. You might wish to change the output to
1210 not include these. Simply add 0x110000 at the end of the non\-empty returned
1211 list if it isn\*(Aqt already that value; and pop that value if it is; like:
1212 .PP
1213 .Vb 9
1214 \& my @list = prop_invlist("foo");
1215 \& if (@list) {
1216 \& if ($list[\-1] == 0x110000) {
1217 \& pop @list; # Defeat the turning on for above Unicode
1218 \& }
1219 \& else {
1220 \& push @list, 0x110000; # Turn off for above Unicode
1221 \& }
1222 \& }
1223 .Ve
1224 .PP
1225 It is a simple matter to expand out an inversion list to a full list of all
1226 code points that have the property\-value:
1227 .PP
1228 .Vb 11
1229 \& my @invlist = prop_invlist($property_name);
1230 \& die "empty" unless @invlist;
1231 \& my @full_list;
1232 \& for (my $i = 0; $i < @invlist; $i += 2) {
1233 \& my $upper = ($i + 1) < @invlist
1234 \& ? $invlist[$i+1] \- 1 # In range
1235 \& : $Unicode::UCD::MAX_CP; # To infinity.
1236 \& for my $j ($invlist[$i] .. $upper) {
1237 \& push @full_list, $j;
1238 \& }
1239 \& }
1240 .Ve
1241 .PP
1242 \&\f(CW\*(C`prop_invlist\*(C'\fR does not know about any user\-defined nor Perl internal\-only
1243 properties, and will return \f(CW\*(C`undef\*(C'\fR if called with one of those.
1244 .PP
1245 The "\fBsearch_invlist()\fR" function is provided for finding a code point within
1246 an inversion list.
1247 .SS \fBprop_invmap()\fP
1248 .IX Subsection "prop_invmap()"
1249 .Vb 3
1250 \& use Unicode::UCD \*(Aqprop_invmap\*(Aq;
1251 \& my ($list_ref, $map_ref, $format, $default)
1252 \& = prop_invmap("General Category");
1253 .Ve
1254 .PP
1255 \&\f(CW\*(C`prop_invmap\*(C'\fR is used to get the complete mapping definition for a property,
1256 in the form of an inversion map. An inversion map consists of two parallel
1257 arrays. One is an ordered list of code points that mark range beginnings, and
1258 the other gives the value (or mapping) that all code points in the
1259 corresponding range have.
1260 .PP
1261 \&\f(CW\*(C`prop_invmap\*(C'\fR is called with the name of the desired property. The name is
1262 loosely matched, meaning that differences in case, white\-space, hyphens, and
1263 underscores are not meaningful (except for the trailing underscore in the
1264 old\-form grandfathered\-in property \f(CW"L_"\fR, which is better written as \f(CW"LC"\fR,
1265 or even better, \f(CW"Gc=LC"\fR).
1266 .PP
1267 Many Unicode properties have more than one name (or alias). \f(CW\*(C`prop_invmap\*(C'\fR
1268 understands all of these, including Perl extensions to them. Ambiguities are
1269 resolved as described above for "\fBprop_aliases()\fR" (except if a property has
1270 both a complete mapping, and a binary \f(CW\*(C`Y\*(C'\fR/\f(CW\*(C`N\*(C'\fR mapping, then specifying the
1271 property name prefixed by \f(CW"is"\fR causes the binary one to be returned). The
1272 Perl internal property "Perl_Decimal_Digit, described below, is also accepted.
1273 An empty list is returned if the property name is unknown.
1274 See "Properties accessible through Unicode::UCD" in perluniprops for the
1275 properties acceptable as inputs to this function.
1276 .PP
1277 It is a fatal error to call this function except in list context.
1278 .PP
1279 In addition to the two arrays that form the inversion map, \f(CW\*(C`prop_invmap\*(C'\fR
1280 returns two other values; one is a scalar that gives some details as to the
1281 format of the entries of the map array; the other is a default value, useful
1282 in maps whose format name begins with the letter \f(CW"a"\fR, as described
1283 below in its subsection; and for specialized purposes, such as
1284 converting to another data structure, described at the end of this main
1285 section.
1286 .PP
1287 This means that \f(CW\*(C`prop_invmap\*(C'\fR returns a 4 element list. For example,
1288 .PP
1289 .Vb 2
1290 \& my ($blocks_ranges_ref, $blocks_maps_ref, $format, $default)
1291 \& = prop_invmap("Block");
1292 .Ve
1293 .PP
1294 In this call, the two arrays will be populated as shown below (for Unicode
1295 6.0):
1296 .PP
1297 .Vb 10
1298 \& Index @blocks_ranges @blocks_maps
1299 \& 0 0x0000 Basic Latin
1300 \& 1 0x0080 Latin\-1 Supplement
1301 \& 2 0x0100 Latin Extended\-A
1302 \& 3 0x0180 Latin Extended\-B
1303 \& 4 0x0250 IPA Extensions
1304 \& 5 0x02B0 Spacing Modifier Letters
1305 \& 6 0x0300 Combining Diacritical Marks
1306 \& 7 0x0370 Greek and Coptic
1307 \& 8 0x0400 Cyrillic
1308 \& ...
1309 \& 233 0x2B820 No_Block
1310 \& 234 0x2F800 CJK Compatibility Ideographs Supplement
1311 \& 235 0x2FA20 No_Block
1312 \& 236 0xE0000 Tags
1313 \& 237 0xE0080 No_Block
1314 \& 238 0xE0100 Variation Selectors Supplement
1315 \& 239 0xE01F0 No_Block
1316 \& 240 0xF0000 Supplementary Private Use Area\-A
1317 \& 241 0x100000 Supplementary Private Use Area\-B
1318 \& 242 0x110000 No_Block
1319 .Ve
1320 .PP
1321 The first line (with Index [0]) means that the value for code point 0 is "Basic
1322 Latin". The entry "0x0080" in the \f(CW@blocks_ranges\fR column in the second line
1323 means that the value from the first line, "Basic Latin", extends to all code
1324 points in the range from 0 up to but not including 0x0080, that is, through
1325 127. In other words, the code points from 0 to 127 are all in the "Basic
1326 Latin" block. Similarly, all code points in the range from 0x0080 up to (but
1327 not including) 0x0100 are in the block named "Latin\-1 Supplement", etc.
1328 (Notice that the return is the old\-style block names; see "Old\-style versus
1329 new\-style block names").
1330 .PP
1331 The final line (with Index [242]) means that the value for all code points above
1332 the legal Unicode maximum code point have the value "No_Block", which is the
1333 term Unicode uses for a non\-existing block.
1334 .PP
1335 The arrays completely specify the mappings for all possible code points.
1336 The final element in an inversion map returned by this function will always be
1337 for the range that consists of all the code points that aren\*(Aqt legal Unicode,
1338 but that are expressible on the platform. (That is, it starts with code point
1339 0x110000, the first code point above the legal Unicode maximum, and extends to
1340 infinity.) The value for that range will be the same that any typical
1341 unassigned code point has for the specified property. (Certain unassigned
1342 code points are not "typical"; for example the non\-character code points, or
1343 those in blocks that are to be written right\-to\-left. The above\-Unicode
1344 range\*(Aqs value is not based on these atypical code points.) It could be argued
1345 that, instead of treating these as unassigned Unicode code points, the value
1346 for this range should be \f(CW\*(C`undef\*(C'\fR. If you wish, you can change the returned
1347 arrays accordingly.
1348 .PP
1349 The maps for almost all properties are simple scalars that should be
1350 interpreted as\-is.
1351 These values are those given in the Unicode\-supplied data files, which may be
1352 inconsistent as to capitalization and as to which synonym for a property\-value
1353 is given. The results may be normalized by using the "\fBprop_value_aliases()\fR"
1354 function.
1355 .PP
1356 There are exceptions to the simple scalar maps. Some properties have some
1357 elements in their map list that are themselves lists of scalars; and some
1358 special strings are returned that are not to be interpreted as\-is. Element
1359 [2] (placed into \f(CW$format\fR in the example above) of the returned four element
1360 list tells you if the map has any of these special elements or not, as follows:
1361 .ie n .IP "\fR\fB""s""\fR\fB\fR" 4
1362 .el .IP \fR\f(CBs\fR\fB\fR 4
1363 .IX Item "s"
1364 means all the elements of the map array are simple scalars, with no special
1365 elements. Almost all properties are like this, like the \f(CW\*(C`block\*(C'\fR example
1366 above.
1367 .ie n .IP "\fR\fB""sl""\fR\fB\fR" 4
1368 .el .IP \fR\f(CBsl\fR\fB\fR 4
1369 .IX Item "sl"
1370 means that some of the map array elements have the form given by \f(CW"s"\fR, and
1371 the rest are lists of scalars. For example, here is a portion of the output
1372 of calling \f(CW\*(C`prop_invmap\*(C'\fR() with the "Script Extensions" property:
1373 .Sp
1374 .Vb 6
1375 \& @scripts_ranges @scripts_maps
1376 \& ...
1377 \& 0x0953 Devanagari
1378 \& 0x0964 [ Bengali, Devanagari, Gurumukhi, Oriya ]
1379 \& 0x0966 Devanagari
1380 \& 0x0970 Common
1381 .Ve
1382 .Sp
1383 Here, the code points 0x964 and 0x965 are both used in Bengali,
1384 Devanagari, Gurmukhi, and Oriya, but no other scripts.
1385 .Sp
1386 The Name_Alias property is also of this form. But each scalar consists of two
1387 components: 1) the name, and 2) the type of alias this is. They are
1388 separated by a colon and a space. In Unicode 6.1, there are several alias types:
1389 .RS 4
1390 .ie n .IP """correction""" 4
1391 .el .IP \f(CWcorrection\fR 4
1392 .IX Item "correction"
1393 indicates that the name is a corrected form for the
1394 original name (which remains valid) for the same code point.
1395 .ie n .IP """control""" 4
1396 .el .IP \f(CWcontrol\fR 4
1397 .IX Item "control"
1398 adds a new name for a control character.
1399 .ie n .IP """alternate""" 4
1400 .el .IP \f(CWalternate\fR 4
1401 .IX Item "alternate"
1402 is an alternate name for a character
1403 .ie n .IP """figment""" 4
1404 .el .IP \f(CWfigment\fR 4
1405 .IX Item "figment"
1406 is a name for a character that has been documented but was never in any
1407 actual standard.
1408 .ie n .IP """abbreviation""" 4
1409 .el .IP \f(CWabbreviation\fR 4
1410 .IX Item "abbreviation"
1411 is a common abbreviation for a character
1412 .RE
1413 .RS 4
1414 .Sp
1415 The lists are ordered (roughly) so the most preferred names come before less
1416 preferred ones.
1417 .Sp
1418 For example,
1419 .Sp
1420 .Vb 10
1421 \& @aliases_ranges @alias_maps
1422 \& ...
1423 \& 0x009E [ \*(AqPRIVACY MESSAGE: control\*(Aq, \*(AqPM: abbreviation\*(Aq ]
1424 \& 0x009F [ \*(AqAPPLICATION PROGRAM COMMAND: control\*(Aq,
1425 \& \*(AqAPC: abbreviation\*(Aq
1426 \& ]
1427 \& 0x00A0 \*(AqNBSP: abbreviation\*(Aq
1428 \& 0x00A1 ""
1429 \& 0x00AD \*(AqSHY: abbreviation\*(Aq
1430 \& 0x00AE ""
1431 \& 0x01A2 \*(AqLATIN CAPITAL LETTER GHA: correction\*(Aq
1432 \& 0x01A3 \*(AqLATIN SMALL LETTER GHA: correction\*(Aq
1433 \& 0x01A4 ""
1434 \& ...
1435 .Ve
1436 .Sp
1437 A map to the empty string means that there is no alias defined for the code
1438 point.
1439 .RE
1440 .ie n .IP "\fR\fB""a""\fR\fB\fR" 4
1441 .el .IP \fR\f(CBa\fR\fB\fR 4
1442 .IX Item "a"
1443 is like \f(CW"s"\fR in that all the map array elements are scalars, but here they are
1444 restricted to all being integers, and some have to be adjusted (hence the name
1445 \&\f(CW"a"\fR) to get the correct result. For example, in:
1446 .Sp
1447 .Vb 2
1448 \& my ($uppers_ranges_ref, $uppers_maps_ref, $format, $default)
1449 \& = prop_invmap("Simple_Uppercase_Mapping");
1450 .Ve
1451 .Sp
1452 the returned arrays look like this:
1453 .Sp
1454 .Vb 7
1455 \& @$uppers_ranges_ref @$uppers_maps_ref Note
1456 \& 0 0
1457 \& 97 65 \*(Aqa\*(Aq maps to \*(AqA\*(Aq, b => B ...
1458 \& 123 0
1459 \& 181 924 MICRO SIGN => Greek Cap MU
1460 \& 182 0
1461 \& ...
1462 .Ve
1463 .Sp
1464 and \f(CW$default\fR is 0.
1465 .Sp
1466 Let\*(Aqs start with the second line. It says that the uppercase of code point 97
1467 is 65; or \f(CWuc("a")\fR == "A". But the line is for the entire range of code
1468 points 97 through 122. To get the mapping for any code point in this range,
1469 you take the offset it has from the beginning code point of the range, and add
1470 that to the mapping for that first code point. So, the mapping for 122 ("z")
1471 is derived by taking the offset of 122 from 97 (=25) and adding that to 65,
1472 yielding 90 ("Z"). Likewise for everything in between.
1473 .Sp
1474 Requiring this simple adjustment allows the returned arrays to be
1475 significantly smaller than otherwise, up to a factor of 10, speeding up
1476 searching through them.
1477 .Sp
1478 Ranges that map to \f(CW$default\fR, \f(CW"0"\fR, behave somewhat differently. For
1479 these, each code point maps to itself. So, in the first line in the example,
1480 \&\f(CW\*(C`ord(uc(chr(0)))\*(C'\fR is 0, \f(CW\*(C`ord(uc(chr(1)))\*(C'\fR is 1, ..
1481 \&\f(CW\*(C`ord(uc(chr(96)))\*(C'\fR is 96.
1482 .ie n .IP "\fR\fB""al""\fR\fB\fR" 4
1483 .el .IP \fR\f(CBal\fR\fB\fR 4
1484 .IX Item "al"
1485 means that some of the map array elements have the form given by \f(CW"a"\fR, and
1486 the rest are ordered lists of code points.
1487 For example, in:
1488 .Sp
1489 .Vb 2
1490 \& my ($uppers_ranges_ref, $uppers_maps_ref, $format, $default)
1491 \& = prop_invmap("Uppercase_Mapping");
1492 .Ve
1493 .Sp
1494 the returned arrays look like this:
1495 .Sp
1496 .Vb 11
1497 \& @$uppers_ranges_ref @$uppers_maps_ref
1498 \& 0 0
1499 \& 97 65
1500 \& 123 0
1501 \& 181 924
1502 \& 182 0
1503 \& ...
1504 \& 0x0149 [ 0x02BC 0x004E ]
1505 \& 0x014A 0
1506 \& 0x014B 330
1507 \& ...
1508 .Ve
1509 .Sp
1510 This is the full Uppercase_Mapping property (as opposed to the
1511 Simple_Uppercase_Mapping given in the example for format \f(CW"a"\fR). The only
1512 difference between the two in the ranges shown is that the code point at
1513 0x0149 (LATIN SMALL LETTER N PRECEDED BY APOSTROPHE) maps to a string of two
1514 characters, 0x02BC (MODIFIER LETTER APOSTROPHE) followed by 0x004E (LATIN
1515 CAPITAL LETTER N).
1516 .Sp
1517 No adjustments are needed to entries that are references to arrays; each such
1518 entry will have exactly one element in its range, so the offset is always 0.
1519 .Sp
1520 The fourth (index [3]) element (\f(CW$default\fR) in the list returned for this
1521 format is 0.
1522 .ie n .IP "\fR\fB""ae""\fR\fB\fR" 4
1523 .el .IP \fR\f(CBae\fR\fB\fR 4
1524 .IX Item "ae"
1525 This is like \f(CW"a"\fR, but some elements are the empty string, and should not be
1526 adjusted.
1527 The one internal Perl property accessible by \f(CW\*(C`prop_invmap\*(C'\fR is of this type:
1528 "Perl_Decimal_Digit" returns an inversion map which gives the numeric values
1529 that are represented by the Unicode decimal digit characters. Characters that
1530 don\*(Aqt represent decimal digits map to the empty string, like so:
1531 .Sp
1532 .Vb 12
1533 \& @digits @values
1534 \& 0x0000 ""
1535 \& 0x0030 0
1536 \& 0x003A: ""
1537 \& 0x0660: 0
1538 \& 0x066A: ""
1539 \& 0x06F0: 0
1540 \& 0x06FA: ""
1541 \& 0x07C0: 0
1542 \& 0x07CA: ""
1543 \& 0x0966: 0
1544 \& ...
1545 .Ve
1546 .Sp
1547 This means that the code points from 0 to 0x2F do not represent decimal digits;
1548 the code point 0x30 (DIGIT ZERO) represents 0; code point 0x31, (DIGIT ONE),
1549 represents 0+1\-0 = 1; ... code point 0x39, (DIGIT NINE), represents 0+9\-0 = 9;
1550 \&... code points 0x3A through 0x65F do not represent decimal digits; 0x660
1551 (ARABIC\-INDIC DIGIT ZERO), represents 0; ... 0x07C1 (NKO DIGIT ONE),
1552 represents 0+1\-0 = 1 ...
1553 .Sp
1554 The fourth (index [3]) element (\f(CW$default\fR) in the list returned for this
1555 format is the empty string.
1556 .ie n .IP "\fR\fB""ale""\fR\fB\fR" 4
1557 .el .IP \fR\f(CBale\fR\fB\fR 4
1558 .IX Item "ale"
1559 is a combination of the \f(CW"al"\fR type and the \f(CW"ae"\fR type. Some of
1560 the map array elements have the forms given by \f(CW"al"\fR, and
1561 the rest are the empty string. The properties \f(CW\*(C`NFKC_Casefold\*(C'\fR and
1562 \&\f(CW\*(C`NFKC_Simple_Casefold\*(C'\fR have this form. An example slice is:
1563 .Sp
1564 .Vb 9
1565 \& @$ranges_ref @$maps_ref Note
1566 \& ...
1567 \& 0x00AA 97 FEMININE ORDINAL INDICATOR => \*(Aqa\*(Aq
1568 \& 0x00AB 0
1569 \& 0x00AD SOFT HYPHEN => ""
1570 \& 0x00AE 0
1571 \& 0x00AF [ 0x0020, 0x0304 ] MACRON => SPACE . COMBINING MACRON
1572 \& 0x00B0 0
1573 \& ...
1574 .Ve
1575 .Sp
1576 The fourth (index [3]) element (\f(CW$default\fR) in the list returned for this
1577 format is 0.
1578 .ie n .IP "\fR\fB""ar""\fR\fB\fR" 4
1579 .el .IP \fR\f(CBar\fR\fB\fR 4
1580 .IX Item "ar"
1581 means that all the elements of the map array are either rational numbers or
1582 the string \f(CW"NaN"\fR, meaning "Not a Number". A rational number is either an
1583 integer, or two integers separated by a solidus (\f(CW"/"\fR). The second integer
1584 represents the denominator of the division implied by the solidus, and is
1585 actually always positive, so it is guaranteed not to be 0 and to not be
1586 signed. When the element is a plain integer (without the
1587 solidus), it may need to be adjusted to get the correct value by adding the
1588 offset, just as other \f(CW"a"\fR properties. No adjustment is needed for
1589 fractions, as the range is guaranteed to have just a single element, and so
1590 the offset is always 0.
1591 .Sp
1592 If you want to convert the returned map to entirely scalar numbers, you
1593 can use something like this:
1594 .Sp
1595 .Vb 4
1596 \& my ($invlist_ref, $invmap_ref, $format) = prop_invmap($property);
1597 \& if ($format && $format eq "ar") {
1598 \& map { $_ = eval $_ if $_ ne \*(AqNaN\*(Aq } @$map_ref;
1599 \& }
1600 .Ve
1601 .Sp
1602 Here\*(Aqs some entries from the output of the property "Nv", which has format
1603 \&\f(CW"ar"\fR.
1604 .Sp
1605 .Vb 10
1606 \& @numerics_ranges @numerics_maps Note
1607 \& 0x00 "NaN"
1608 \& 0x30 0 DIGIT 0 .. DIGIT 9
1609 \& 0x3A "NaN"
1610 \& 0xB2 2 SUPERSCRIPTs 2 and 3
1611 \& 0xB4 "NaN"
1612 \& 0xB9 1 SUPERSCRIPT 1
1613 \& 0xBA "NaN"
1614 \& 0xBC 1/4 VULGAR FRACTION 1/4
1615 \& 0xBD 1/2 VULGAR FRACTION 1/2
1616 \& 0xBE 3/4 VULGAR FRACTION 3/4
1617 \& 0xBF "NaN"
1618 \& 0x660 0 ARABIC\-INDIC DIGIT ZERO .. NINE
1619 \& 0x66A "NaN"
1620 .Ve
1621 .Sp
1622 The fourth (index [3]) element (\f(CW$default\fR) in the list returned for this
1623 format is \f(CW"NaN"\fR.
1624 .ie n .IP "\fR\fB""n""\fR\fB\fR" 4
1625 .el .IP \fR\f(CBn\fR\fB\fR 4
1626 .IX Item "n"
1627 means the Name property. All the elements of the map array are simple
1628 scalars, but some of them contain special strings that require more work to
1629 get the actual name.
1630 .Sp
1631 Entries such as:
1632 .Sp
1633 .Vb 1
1634 \& CJK UNIFIED IDEOGRAPH\-<code point>
1635 .Ve
1636 .Sp
1637 mean that the name for the code point is "CJK UNIFIED IDEOGRAPH\-"
1638 with the code point (expressed in hexadecimal) appended to it, like "CJK
1639 UNIFIED IDEOGRAPH\-3403" (similarly for \f(CW\*(C`CJK\ COMPATIBILITY\ IDEOGRAPH\-<code\ point>\*(C'\fR).
1640 .Sp
1641 Also, entries like
1642 .Sp
1643 .Vb 1
1644 \& <hangul syllable>
1645 .Ve
1646 .Sp
1647 means that the name is algorithmically calculated. This is easily done by
1648 the function "charnames::viacode(code)" in charnames.
1649 .Sp
1650 Note that for control characters (\f(CW\*(C`Gc=cc\*(C'\fR), Unicode\*(Aqs data files have the
1651 string "\f(CW\*(C`<control>\*(C'\fR", but the real name of each of these characters is the empty
1652 string. This function returns that real name, the empty string. (There are
1653 names for these characters, but they are considered aliases, not the Name
1654 property name, and are contained in the \f(CW\*(C`Name_Alias\*(C'\fR property.)
1655 .ie n .IP "\fR\fB""ad""\fR\fB\fR" 4
1656 .el .IP \fR\f(CBad\fR\fB\fR 4
1657 .IX Item "ad"
1658 means the Decomposition_Mapping property. This property is like \f(CW"al"\fR
1659 properties, except that one of the scalar elements is of the form:
1660 .Sp
1661 .Vb 1
1662 \& <hangul syllable>
1663 .Ve
1664 .Sp
1665 This signifies that this entry should be replaced by the decompositions for
1666 all the code points whose decomposition is algorithmically calculated. (All
1667 of them are currently in one range and no others outside the range are likely
1668 to ever be added to Unicode; the \f(CW"n"\fR format
1669 has this same entry.) These can be generated via the function
1670 \&\fBUnicode::Normalize::NFD()\fR.
1671 .Sp
1672 Note that the mapping is the one that is specified in the Unicode data files,
1673 and to get the final decomposition, it may need to be applied recursively.
1674 Unicode in fact discourages use of this property except internally in
1675 implementations of the Unicode Normalization Algorithm.
1676 .Sp
1677 The fourth (index [3]) element (\f(CW$default\fR) in the list returned for this
1678 format is 0.
1679 .PP
1680 Note that a format begins with the letter "a" if and only the property it is
1681 for requires adjustments by adding the offsets in multi\-element ranges. For
1682 all these properties, an entry should be adjusted only if the map is a scalar
1683 which is an integer. That is, it must match the regular expression:
1684 .PP
1685 .Vb 1
1686 \& / ^ \-? \ed+ $ /xa
1687 .Ve
1688 .PP
1689 Further, the first element in a range never needs adjustment, as the
1690 adjustment would be just adding 0.
1691 .PP
1692 A binary search such as that provided by "\fBsearch_invlist()\fR", can be used to
1693 quickly find a code point in the inversion list, and hence its corresponding
1694 mapping.
1695 .PP
1696 The final, fourth element (index [3], assigned to \f(CW$default\fR in the "block"
1697 example) in the four element list returned by this function is used with the
1698 \&\f(CW"a"\fR format types; it may also be useful for applications
1699 that wish to convert the returned inversion map data structure into some
1700 other, such as a hash. It gives the mapping that most code points map to
1701 under the property. If you establish the convention that any code point not
1702 explicitly listed in your data structure maps to this value, you can
1703 potentially make your data structure much smaller. As you construct your data
1704 structure from the one returned by this function, simply ignore those ranges
1705 that map to this value. For example, to
1706 convert to the data structure searchable by "\fBcharinrange()\fR", you can follow
1707 this recipe for properties that don\*(Aqt require adjustments:
1708 .PP
1709 .Vb 2
1710 \& my ($list_ref, $map_ref, $format, $default) = prop_invmap($property);
1711 \& my @range_list;
1712 \&
1713 \& # Look at each element in the list, but the \-2 is needed because we
1714 \& # look at $i+1 in the loop, and the final element is guaranteed to map
1715 \& # to $default by prop_invmap(), so we would skip it anyway.
1716 \& for my $i (0 .. @$list_ref \- 2) {
1717 \& next if $map_ref\->[$i] eq $default;
1718 \& push @range_list, [ $list_ref\->[$i],
1719 \& $list_ref\->[$i+1],
1720 \& $map_ref\->[$i]
1721 \& ];
1722 \& }
1723 \&
1724 \& print charinrange(\e@range_list, $code_point), "\en";
1725 .Ve
1726 .PP
1727 With this, \f(CWcharinrange()\fR will return \f(CW\*(C`undef\*(C'\fR if its input code point maps
1728 to \f(CW$default\fR. You can avoid this by omitting the \f(CW\*(C`next\*(C'\fR statement, and adding
1729 a line after the loop to handle the final element of the inversion map.
1730 .PP
1731 Similarly, this recipe can be used for properties that do require adjustments:
1732 .PP
1733 .Vb 2
1734 \& for my $i (0 .. @$list_ref \- 2) {
1735 \& next if $map_ref\->[$i] eq $default;
1736 \&
1737 \& # prop_invmap() guarantees that if the mapping is to an array, the
1738 \& # range has just one element, so no need to worry about adjustments.
1739 \& if (ref $map_ref\->[$i]) {
1740 \& push @range_list,
1741 \& [ $list_ref\->[$i], $list_ref\->[$i], $map_ref\->[$i] ];
1742 \& }
1743 \& else { # Otherwise each element is actually mapped to a separate
1744 \& # value, so the range has to be split into single code point
1745 \& # ranges.
1746 \&
1747 \& my $adjustment = 0;
1748 \&
1749 \& # For each code point that gets mapped to something...
1750 \& for my $j ($list_ref\->[$i] .. $list_ref\->[$i+1] \-1 ) {
1751 \&
1752 \& # ... add a range consisting of just it mapping to the
1753 \& # original plus the adjustment, which is incremented for the
1754 \& # next time through the loop, as the offset increases by 1
1755 \& # for each element in the range
1756 \& push @range_list,
1757 \& [ $j, $j, $map_ref\->[$i] + $adjustment++ ];
1758 \& }
1759 \& }
1760 \& }
1761 .Ve
1762 .PP
1763 Note that the inversion maps returned for the \f(CW\*(C`Case_Folding\*(C'\fR and
1764 \&\f(CW\*(C`Simple_Case_Folding\*(C'\fR properties do not include the Turkic\-locale mappings.
1765 Use "\fBcasefold()\fR" for these.
1766 .PP
1767 \&\f(CW\*(C`prop_invmap\*(C'\fR does not know about any user\-defined properties, and will
1768 return \f(CW\*(C`undef\*(C'\fR if called with one of those.
1769 .PP
1770 The returned values for the Perl extension properties, such as \f(CW\*(C`Any\*(C'\fR and
1771 \&\f(CW\*(C`Greek\*(C'\fR are somewhat misleading. The values are either \f(CW"Y"\fR or \f(CW\*(C`"N\*(C'\fR".
1772 All Unicode properties are bipartite, so you can actually use the \f(CW"Y"\fR or
1773 \&\f(CW\*(C`"N\*(C'\fR" in a Perl regular expression for these, like \f(CW\*(C`qr/\ep{ID_Start=Y/}\*(C'\fR or
1774 \&\f(CW\*(C`qr/\ep{Upper=N/}\*(C'\fR. But the Perl extensions aren\*(Aqt specified this way, only
1775 like \f(CW\*(C`/qr/\ep{Any}\*(C'\fR, \fIetc\fR. You can\*(Aqt actually use the \f(CW"Y"\fR and \f(CW\*(C`"N\*(C'\fR" in
1776 them.
1777 .PP
1778 \fIGetting every available name\fR
1779 .IX Subsection "Getting every available name"
1780 .PP
1781 Instead of reading the Unicode Database directly from files, as you were able
1782 to do for a long time, you are encouraged to use the supplied functions. So,
1783 instead of reading \f(CW\*(C`Name.pl\*(C'\fR directly, which changed formats in 5.32, and may
1784 do so again without notice in the future or even disappear, you ought to use
1785 "\fBprop_invmap()\fR" like this:
1786 .PP
1787 .Vb 10
1788 \& my (%name, %cp, %cps, $n);
1789 \& # All codepoints
1790 \& foreach my $cat (qw( Name Name_Alias )) {
1791 \& my ($codepoints, $names, $format, $default) = prop_invmap($cat);
1792 \& # $format => "n", $default => ""
1793 \& foreach my $i (0 .. @$codepoints \- 2) {
1794 \& my ($cp, $n) = ($codepoints\->[$i], $names\->[$i]);
1795 \& # If $n is a ref, the same codepoint has multiple names
1796 \& foreach my $name (ref $n ? @$n : $n) {
1797 \& $name{$cp} //= $name;
1798 \& $cp{$name} //= $cp;
1799 \& }
1800 \& }
1801 \& }
1802 \& # Named sequences
1803 \& { my %ns = namedseq();
1804 \& foreach my $name (sort { $ns{$a} cmp $ns{$b} } keys %ns) {
1805 \& $cp{$name} //= [ map { ord } split "" => $ns{$name} ];
1806 \& }
1807 \& }
1808 .Ve
1809 .SS \fBsearch_invlist()\fP
1810 .IX Subsection "search_invlist()"
1811 .Vb 2
1812 \& use Unicode::UCD qw(prop_invmap prop_invlist);
1813 \& use Unicode::UCD \*(Aqsearch_invlist\*(Aq;
1814 \&
1815 \& my @invlist = prop_invlist($property_name);
1816 \& print $code_point, ((search_invlist(\e@invlist, $code_point) // \-1) % 2)
1817 \& ? " isn\*(Aqt"
1818 \& : " is",
1819 \& " in $property_name\en";
1820 \&
1821 \& my ($blocks_ranges_ref, $blocks_map_ref) = prop_invmap("Block");
1822 \& my $index = search_invlist($blocks_ranges_ref, $code_point);
1823 \& print "$code_point is in block ", $blocks_map_ref\->[$index], "\en";
1824 .Ve
1825 .PP
1826 \&\f(CW\*(C`search_invlist\*(C'\fR is used to search an inversion list returned by
1827 \&\f(CW\*(C`prop_invlist\*(C'\fR or \f(CW\*(C`prop_invmap\*(C'\fR for a particular "code point argument".
1828 \&\f(CW\*(C`undef\*(C'\fR is returned if the code point is not found in the inversion list
1829 (this happens only when it is not a legal "code point argument", or is less
1830 than the list\*(Aqs first element). A warning is raised in the first instance.
1831 .PP
1832 Otherwise, it returns the index into the list of the range that contains the
1833 code point.; that is, find \f(CW\*(C`i\*(C'\fR such that
1834 .PP
1835 .Vb 1
1836 \& list[i]<= code_point < list[i+1].
1837 .Ve
1838 .PP
1839 As explained in "\fBprop_invlist()\fR", whether a code point is in the list or not
1840 depends on if the index is even (in) or odd (not in). And as explained in
1841 "\fBprop_invmap()\fR", the index is used with the returned parallel array to find
1842 the mapping.
1843 .SS Unicode::UCD::UnicodeVersion
1844 .IX Subsection "Unicode::UCD::UnicodeVersion"
1845 This returns the version of the Unicode Character Database, in other words, the
1846 version of the Unicode standard the database implements. The version is a
1847 string of numbers delimited by dots (\f(CW\*(Aq.\*(Aq\fR).
1848 .SS "\fBBlocks versus Scripts\fP"
1849 .IX Subsection "Blocks versus Scripts"
1850 The difference between a block and a script is that scripts are closer
1851 to the linguistic notion of a set of code points required to represent
1852 languages, while block is more of an artifact of the Unicode code point
1853 numbering and separation into blocks of consecutive code points (so far the
1854 size of a block is some multiple of 16, like 128 or 256).
1855 .PP
1856 For example the Latin \fBscript\fR is spread over several \fBblocks\fR, such
1857 as \f(CW\*(C`Basic Latin\*(C'\fR, \f(CW\*(C`Latin 1 Supplement\*(C'\fR, \f(CW\*(C`Latin Extended\-A\*(C'\fR, and
1858 \&\f(CW\*(C`Latin Extended\-B\*(C'\fR. On the other hand, the Latin script does not
1859 contain all the characters of the \f(CW\*(C`Basic Latin\*(C'\fR block (also known as
1860 ASCII): it includes only the letters, and not, for example, the digits
1861 nor the punctuation.
1862 .PP
1863 For blocks see <http://www.unicode.org/Public/UNIDATA/Blocks.txt>
1864 .PP
1865 For scripts see UTR #24: <http://www.unicode.org/reports/tr24/>
1866 .SS "\fBMatching Scripts and Blocks\fP"
1867 .IX Subsection "Matching Scripts and Blocks"
1868 Scripts are matched with the regular\-expression construct
1869 \&\f(CW\*(C`\ep{...}\*(C'\fR (e.g. \f(CW\*(C`\ep{Tibetan}\*(C'\fR matches characters of the Tibetan script),
1870 while \f(CW\*(C`\ep{Blk=...}\*(C'\fR is used for blocks (e.g. \f(CW\*(C`\ep{Blk=Tibetan}\*(C'\fR matches
1871 any of the 256 code points in the Tibetan block).
1872 .SS "Old\-style versus new\-style block names"
1873 .IX Subsection "Old-style versus new-style block names"
1874 Unicode publishes the names of blocks in two different styles, though the two
1875 are equivalent under Unicode\*(Aqs loose matching rules.
1876 .PP
1877 The original style uses blanks and hyphens in the block names (except for
1878 \&\f(CW\*(C`No_Block\*(C'\fR), like so:
1879 .PP
1880 .Vb 1
1881 \& Miscellaneous Mathematical Symbols\-B
1882 .Ve
1883 .PP
1884 The newer style replaces these with underscores, like this:
1885 .PP
1886 .Vb 1
1887 \& Miscellaneous_Mathematical_Symbols_B
1888 .Ve
1889 .PP
1890 This newer style is consistent with the values of other Unicode properties.
1891 To preserve backward compatibility, all the functions in Unicode::UCD that
1892 return block names (except as noted) return the old\-style ones.
1893 "\fBprop_value_aliases()\fR" returns the new\-style and can be used to convert from
1894 old\-style to new\-style:
1895 .PP
1896 .Vb 1
1897 \& my $new_style = prop_values_aliases("block", $old_style);
1898 .Ve
1899 .PP
1900 Perl also has single\-form extensions that refer to blocks, \f(CW\*(C`In_Cyrillic\*(C'\fR,
1901 meaning \f(CW\*(C`Block=Cyrillic\*(C'\fR. These have always been written in the new style.
1902 .PP
1903 To convert from new\-style to old\-style, follow this recipe:
1904 .PP
1905 .Vb 1
1906 \& $old_style = charblock((prop_invlist("block=$new_style"))[0]);
1907 .Ve
1908 .PP
1909 (which finds the range of code points in the block using \f(CW\*(C`prop_invlist\*(C'\fR,
1910 gets the lower end of the range (0th element) and then looks up the old name
1911 for its block using \f(CW\*(C`charblock\*(C'\fR).
1912 .PP
1913 Note that starting in Unicode 6.1, many of the block names have shorter
1914 synonyms. These are always given in the new style.
1915 .SS "Use with older Unicode versions"
1916 .IX Subsection "Use with older Unicode versions"
1917 The functions in this module work as well as can be expected when
1918 used on earlier Unicode versions. But, obviously, they use the available data
1919 from that Unicode version. For example, if the Unicode version predates the
1920 definition of the script property (Unicode 3.1), then any function that deals
1921 with scripts is going to return \f(CW\*(C`undef\*(C'\fR for the script portion of the return
1922 value.
1923 .SH AUTHOR
1924 .IX Header "AUTHOR"
1925 Jarkko Hietaniemi. Now maintained by perl5 porters.