2 Hash::Normalize - Automatically normalize Unicode hash keys.
8 use Hash::Normalize qw<normalize>;
10 normalize my %hash, 'NFC';
12 $hash{café} = 'coffee'; # NFD, "cafe\x{301}"
14 print $hash{café}; # NFD, "cafe\x{301}"
17 print $hash{café}; # NFC, "caf\x{e9}"
18 # 'coffee' is also printed
21 This module provides an utility routine that augments a given Perl hash
22 table so that its keys are automatically normalized following one of the
23 Unicode normalization schemes. All the following actions on this hash
24 will be made regardless of how the key used for the action is
27 Since this module does not use the "tie" mechanism, normalized hashes
28 are indistinguishable from regular hashes as far as Perl is concerned,
29 but this module also provides "get_normalization" to identify them if
35 normalize %hash, $mode;
37 Applies the Unicode normalization scheme $mode onto %hash. $mode
38 defaults to 'NFC' if omitted, and should match
39 "/^(?:(?:nf)?k?|fc)[cd]$/i" otherwise.
41 "normalize" will first try to forcefully normalize the existing keys in
42 %hash to the new mode, but it will throw an exception if there are
43 distinct keys that have the same normalization. All the keys
44 subsequently used for fetches, stores, exists, deletes and list
45 assignments are then first passed through the according normalization
46 procedure. "keys %hash" will also return the list of normalized keys.
49 my $mode = get_normalization %hash;
50 normalize %hash, $mode;
52 Returns the current Unicode normalization scheme in use for %hash, or
53 "undef" if it is a plain hash.
55 NORMALIZED SYMBOL LOOKUPS
56 Stashes (Perl symbol tables) are implemented as plain hashes, therefore
57 one can use "normalize %Pkg::" on them to make sure that Unicode symbol
58 lookups are made regardless of normalization.
63 require Hash::Normalize;
64 # Enforce NFC normalization
65 Hash::Normalize::normalize(%Foo::, 'NFC')
68 sub café { # NFD, "cafe\x{301}"
73 café() # NFC, "cafe\x{e9}"
77 café() # NFD, "cafe\x{301}"
80 # Both coffee_nfc() and coffee_nfd() return 'coffee'
83 Using a normalized hash is slightly slower than a plain hash, due to the
84 normalization procedure and the overhead of magic.
86 If a hash is initialized from a normalized hash by list assignment
87 ("%new = %normalized"), then the normalization scheme will not be
88 carried over to the new hash, although its keys will initially be
89 normalized like the ones from the original hash.
92 The functions "normalize" and "get_normalization" are only exported on
93 request by specifying their names in the module import list.
98 Carp, Exporter (core since perl 5).
100 Unicode::Normalize (core since perl 5.8).
102 Variable::Magic 0.51.
105 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
107 You can contact me by mail or on "irc.perl.org" (vincent).
110 Please report any bugs or feature requests to "bug-hash-normalize at
111 rt.cpan.org", or through the web interface at
112 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hash-Normalize>. I will
113 be notified, and then you'll automatically be notified of progress on
114 your bug as I make changes.
117 You can find documentation for this module with the perldoc command.
119 perldoc Hash::Normalize
122 Copyright 2017 Vincent Pit, all rights reserved.
124 This program is free software; you can redistribute it and/or modify it
125 under the same terms as Perl itself.