1Hash::StoredIterator(3pUms)er Contributed Perl DocumentatHiaosnh::StoredIterator(3pm)
2
3
4

NAME

6       Hash::StoredIterator - Functions for accessing a hashes internal
7       iterator.
8

DESCRIPTION

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
15       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
20       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
24       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

SYNOPSIS

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
39           my %hash = map { $_ => uc( $_ )} 'a' .. 'z';
40
41           my @keys = hkeys %hash;
42           my @values = hvalues %hash;
43
44       Each section below is functionally identical.
45
46           my $iterator = iterator %hash;
47           while( my ( $k, $v ) = $i->() ) {
48               print "$k: $value\n";
49           }
50
51           hmap { print "$a: $b\n" } %hash;
52
53           hamp { print "$_: $b\n" } %hash;
54
55           hmap {
56               my ( $key, $val ) = @_;
57               print "$key: $val\n";
58           } %hash;
59
60       It is safe to nest calls to hmap(), iterator(), hkeys(), and hvalues()
61
62           hmap {
63               my ( $key, $val ) = @_;
64               print "$key: $val\n";
65               my @keys = hkeys( %hash );
66           } %hash;
67
68       hmap() and iterator() will also properly handle calls to "CORE::each",
69       "CORE::keys", and "Core::values" nested within them.
70
71           hmap {
72               my ( $key, $val ) = @_;
73               print "$key: $val\n";
74
75               # No infinite loop!
76               my @keys = keys %hash;
77           } %hash;
78
79       Low Level:
80
81           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

EXPORTS

88       my $i = iterator %hash
89           Get an iterator that can be used to retrieve key/value pairs.
90
91               my $i = iterator %hash;
92               while( my ($k, $v) = $i->() ) {
93                   ...
94               }
95
96           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
99       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
107           Note: See caveats.
108
109       my @keys = hkeys( %hash )
110           Same as the builtin keys(), except it stores and restores the
111           iterator.
112
113           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
118       my @values = hvalues( %hash )
119           Same as the builtin values(), except it stores and restores the
120           iterator.
121
122           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
127       my $i = hash_get_iterator( \%hash )
128           Get the current iterator value.
129
130       hash_set_iterator( \%hash, $i )
131           Set the iterator value.
132
133           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
137       hash_init_iterator( \%hash )
138           Initialize or reset the hash iterator.
139

DEPRECATED

141       These have been deprecated because they were terrible names. eich was
142       also deprecated because it was unnatural to use.
143
144       eich
145           use iterator() instead
146
147       eech
148           use hmap instead
149

CAVEATS

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
157       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

AUTHORS

163       Chad Granum exodist7@gmail.com
164
166       Copyright (C) 2013 Chad Granum
167
168       Hash-StoredIterator is free software; Standard perl licence.
169
170       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.
174
175
176
177perl v5.38.0                      2023-07-20         Hash::StoredIterator(3pm)
Impressum