1Hash::StoredIterator(3)User Contributed Perl DocumentatioHnash::StoredIterator(3)
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
12       these all share use of the same iterator, they tend to interact badly
13       with 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
25       "values()" which stash and restore the iterator so that they are safe
26       to use 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
61       "hvalues()"
62
63           hmap {
64               my ( $key, $val ) = @_;
65               print "$key: $val\n";
66               my @keys = hkeys( %hash );
67           } %hash;
68
69       "hmap()" and "iterator()" will also properly handle calls to
70       "CORE::each", "CORE::keys", and "Core::values" nested within them.
71
72           hmap {
73               my ( $key, $val ) = @_;
74               print "$key: $val\n";
75
76               # No infinite loop!
77               my @keys = keys %hash;
78           } %hash;
79
80       Low Level:
81
82           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

EXPORTS

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

DEPRECATED

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

CAVEATS

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

AUTHORS

164       Chad Granum exodist7@gmail.com
165
167       Copyright (C) 2013 Chad Granum
168
169       Hash-StoredIterator is free software; Standard perl licence.
170
171       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.
175
176
177
178perl v5.30.1                      2020-01-30           Hash::StoredIterator(3)
Impressum