1Hash::StoredIterator(3)User Contributed Perl DocumentatioHnash::StoredIterator(3)
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
12 these all share use of the same iterator, they tend to interact badly
13 with 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
25 "values()" which stash and restore the iterator so that they are safe
26 to use 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
61 "hvalues()"
62 hmap {
64 my ( $key, $val ) = @_;
65 print "$key: $val\n";
66 my @keys = hkeys( %hash );
67 } %hash;
68 "hmap()" and "iterator()" will also properly handle calls to
70 "CORE::each", "CORE::keys", and "Core::values" nested within them.
71 hmap {
73 my ( $key, $val ) = @_;
74 print "$key: $val\n";
75 # No infinite loop!
77 my @keys = keys %hash;
78 } %hash;
79 Low Level:
81 hash_init_iterator( \%hash );
83 my $iter = hash_get_iterator( \%hash );
84 # NOTE: Never manually specify an $iter value, ALWAYS use a value from
85 # hash_get_iterator.
86 hash_set_iterator( \%hash, $iter );
87
89 my $i = iterator %hash
90 Get an iterator that can be used to retrieve key/value pairs.
91 my $i = iterator %hash;
93 while( my ($k, $v) = $i->() ) {
94 ...
95 }
96 The iterator is a coderef, so you call it like this: "$i-"()>. You
98 can also use the sub anywhere you would use any other coderef.
99 hmap( \&callback, %hash )
101 hmap { ... } %hash
102 Iterate each key/pair calling "$callback-"( $key, $value )> for
103 each set. In addition $a and $_ are set to the key, and $b is set
104 to the value. This is done primarily for convenience of matching
105 against the key, and short callbacks that will be cluttered by
106 parsing @_ noise.
107 Note: See caveats.
109 my @keys = hkeys( %hash )
111 Same as the builtin "keys()", except it stores and restores the
112 iterator.
113 Note: Overriding the builtin keys(), even locally, causes strange
115 interactions with other builtins. When trying to export hkeys as
116 keys, a call to "sort keys %hash" would cause undef to be passed
117 into keys() as the first and only argument.
118 my @values = hvalues( %hash )
120 Same as the builtin "values()", except it stores and restores the
121 iterator.
122 Note: Overriding the builtin values(), even locally, causes strange
124 interactions with other builtins. When trying to export hvalues as
125 values, a call to "sort values %hash" would cause undef to be
126 passed into values() as the first and only argument.
127 my $i = hash_get_iterator( \%hash )
129 Get the current iterator value.
130 hash_set_iterator( \%hash, $i )
132 Set the iterator value.
133 Note: Only ever set this to the value retrieved by
135 "hash_get_iterator()", setting the iterator in any other way is
136 untested, and may result in undefined behavior.
137 hash_init_iterator( \%hash )
139 Initialize or reset the hash iterator.
140
142 These have been deprecated because they were terrible names. eich was
143 also deprecated because it was unnatural to use.
144 eich
146 use iterator() instead
147 eech
149 use hmap instead
150
152 Modification of hash during iteration
153 Just like with the builtin "each()" modifying the hash between
154 calls to each is not recommended and can result in undefined
155 behavior. The builtin "each()" does allow for deleting the
156 iterations key, however that is NOT supported by this library.
157 sort() edge case
159 For some reason "[sort hkeys %hash]" and "[sort hkeys(%hash)]" both
160 result in a list that has all the keys and values (and strangely
161 not in sorted order). However "[sort(hkeys(%hash))]" works fine.
162
164 Chad Granum exodist7@gmail.com
165
167 Copyright (C) 2013 Chad Granum
168 Hash-StoredIterator is free software; Standard perl licence.
170 Hash-StoredIterator is distributed in the hope that it will be useful,
172 but WITHOUT ANY WARRANTY; without even the implied warranty of
173 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license
174 for more details.
175perl v5.34.0 2022-01-21 Hash::StoredIterator(3)