1Hash::StoredIterator(3pUms)er Contributed Perl DocumentatHiaosnh::StoredIterator(3pm)
2
6 Hash::StoredIterator - Functions for accessing a hashes internal
7 iterator.
8
10 In perl all hashes have an internal iterator. This iterator is used by
11 the each() function, as well as by keys() and values(). Because these
12 all share use of the same iterator, they tend to interact badly with
13 each other when nested.
14 Hash::StoredIterator gives you access to get, set, and init the
16 iterator inside a hash. This allows you to store the current iterator,
17 use each/keys/values/etc, and then restore the iterator, this helps you
18 to ensure you do not interact badly with other users of the iterator.
19 Along with low-level get/set/init functions, there are also 2
21 variations of each() which let you act upon each key/value pair in a
22 safer way than vanilla each()
23 This module can also export new implementations of keys() and values()
25 which stash and restore the iterator so that they are safe to use
26 within each().
27
29 use Hash::StoredIterator qw{
30 hmap
31 hkeys
32 hvalues
33 iterator
34 hash_get_iterator
35 hash_set_iterator
36 hash_init_iterator
37 };
38 my %hash = map { $_ => uc( $_ )} 'a' .. 'z';
40 my @keys = hkeys %hash;
42 my @values = hvalues %hash;
43 Each section below is functionally identical.
45 my $iterator = iterator %hash;
47 while( my ( $k, $v ) = $i->() ) {
48 print "$k: $value\n";
49 }
50 hmap { print "$a: $b\n" } %hash;
52 hamp { print "$_: $b\n" } %hash;
54 hmap {
56 my ( $key, $val ) = @_;
57 print "$key: $val\n";
58 } %hash;
59 It is safe to nest calls to hmap(), iterator(), hkeys(), and hvalues()
61 hmap {
63 my ( $key, $val ) = @_;
64 print "$key: $val\n";
65 my @keys = hkeys( %hash );
66 } %hash;
67 hmap() and iterator() will also properly handle calls to "CORE::each",
69 "CORE::keys", and "Core::values" nested within them.
70 hmap {
72 my ( $key, $val ) = @_;
73 print "$key: $val\n";
74 # No infinite loop!
76 my @keys = keys %hash;
77 } %hash;
78 Low Level:
80 hash_init_iterator( \%hash );
82 my $iter = hash_get_iterator( \%hash );
83 # NOTE: Never manually specify an $iter value, ALWAYS use a value from
84 # hash_get_iterator.
85 hash_set_iterator( \%hash, $iter );
86
88 my $i = iterator %hash
89 Get an iterator that can be used to retrieve key/value pairs.
90 my $i = iterator %hash;
92 while( my ($k, $v) = $i->() ) {
93 ...
94 }
95 The iterator is a coderef, so you call it like this: "$i-"()>. You
97 can also use the sub anywhere you would use any other coderef.
98 hmap( \&callback, %hash )
100 hmap { ... } %hash
101 Iterate each key/pair calling "$callback-"( $key, $value )> for
102 each set. In addition $a and $_ are set to the key, and $b is set
103 to the value. This is done primarily for convenience of matching
104 against the key, and short callbacks that will be cluttered by
105 parsing @_ noise.
106 Note: See caveats.
108 my @keys = hkeys( %hash )
110 Same as the builtin keys(), except it stores and restores the
111 iterator.
112 Note: Overriding the builtin keys(), even locally, causes strange
114 interactions with other builtins. When trying to export hkeys as
115 keys, a call to "sort keys %hash" would cause undef to be passed
116 into keys() as the first and only argument.
117 my @values = hvalues( %hash )
119 Same as the builtin values(), except it stores and restores the
120 iterator.
121 Note: Overriding the builtin values(), even locally, causes strange
123 interactions with other builtins. When trying to export hvalues as
124 values, a call to "sort values %hash" would cause undef to be
125 passed into values() as the first and only argument.
126 my $i = hash_get_iterator( \%hash )
128 Get the current iterator value.
129 hash_set_iterator( \%hash, $i )
131 Set the iterator value.
132 Note: Only ever set this to the value retrieved by
134 hash_get_iterator(), setting the iterator in any other way is
135 untested, and may result in undefined behavior.
136 hash_init_iterator( \%hash )
138 Initialize or reset the hash iterator.
139
141 These have been deprecated because they were terrible names. eich was
142 also deprecated because it was unnatural to use.
143 eich
145 use iterator() instead
146 eech
148 use hmap instead
149
151 Modification of hash during iteration
152 Just like with the builtin each() modifying the hash between calls
153 to each is not recommended and can result in undefined behavior.
154 The builtin each() does allow for deleting the iterations key,
155 however that is NOT supported by this library.
156 sort() edge case
158 For some reason "[sort hkeys %hash]" and "[sort hkeys(%hash)]" both
159 result in a list that has all the keys and values (and strangely
160 not in sorted order). However "[sort(hkeys(%hash))]" works fine.
161
163 Chad Granum exodist7@gmail.com
164
166 Copyright (C) 2013 Chad Granum
167 Hash-StoredIterator is free software; Standard perl licence.
169 Hash-StoredIterator is distributed in the hope that it will be useful,
171 but WITHOUT ANY WARRANTY; without even the implied warranty of
172 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license
173 for more details.
174perl v5.38.0 2023-07-20 Hash::StoredIterator(3pm)