1Tie::Hash::MultiValue(3U)ser Contributed Perl DocumentatiToine::Hash::MultiValue(3)
2
3
4

NAME

6       Tie::Hash::MultiValue - store multiple values per key
7

SYNOPSIS

9         use Tie::Hash::MultiValue;
10         my $controller = tie %hash, 'Tie::Hash::MultiValue';
11         $hash{'foo'} = 'one';
12         $hash{'bar'} = 'two';
13         $hash{'bar'} = 'three';
14
15         # Fetch the values as references to arrays.
16         $controller->refs;
17         my @values  = @{$hash{'foo'}};   # @values = ('one');
18         my @more    = @{$hash{'bar'}};   # @more   = ('two', 'three');
19         my @nothing = @{$hash{'baz'}};   # empty list if nothing there
20
21         # You can tie an anonymous hash as well.
22         my $hashref = {};
23         tie %$hashref, 'Tie::Hash::MultiValue';
24         $hashref->{'sample'} = 'one';
25         $hashref->{'sample'} = 'two';
26         # $hashref->{'sample'} now contains ['one','two']
27
28         # Iterate over the items stored under a key.
29         $controller->iterators;
30         while(my $value = $hash{bar}) {
31           print "bar: $value\n";
32         }
33         # prints
34         #   bar: two
35         #   bar: three
36

DESCRIPTION

38       "Tie::Hash::MultiValue" allows you to have hashes which store their
39       values in anonymous arrays, appending any new value to the already-
40       existing ones.
41
42       This means that you can store as many items as you like under a single
43       key, and access them all at once by accessing the value stored under
44       the key.
45

USAGE

47       See the synopsis for a typical usage.
48

BUGS

50       None currently known.
51

SUPPORT

53       Contact the author for support.
54

AUTHOR

56               Joe McMahon
57               CPAN ID: MCMAHON
58               mcmahon@ibiblio.org
59               http://ibiblio.org/mcmahon
60
62       This program is free software; you can redistribute it and/or modify it
63       under the same terms as Perl itself.
64
65       The full text of the license can be found in the LICENSE file included
66       with this module.
67

SEE ALSO

69       Tie::Hash, perl(1), Perl Cookbook (1st version) recipe 13.15, program
70       13-5.
71

METHODS

73       This class is a subclass of "Tie::ExtraHash"; it needs to override the
74       "TIEHASH" method to save the instance data (in $self->[1]), and the
75       "STORE" method to actually save the values in an anonymous array.
76
77   TIEHASH
78       If the 'unique' argument is supplied, we check to see if it supplies a
79       subroutine reference to be used to compare items. If it does, we store
80       that reference in the object describing this tie; if not, we supply a
81       function which simply uses 'eq' to test for equality.
82
83       The 'unique' function
84
85       This funtion will receive two scalar arguments. No assumption is made
86       about whether or not either argument is defined, nor whether these are
87       simple scalars or references. You can make any of these assumptions if
88       you choose, but you are responsible for checking your input.
89
90       You can perform whatever tests you like in your routine; you should
91       return a true value if the arguments are determined to be equal, and a
92       false one if they are not.
93
94   STORE
95       Push the value(s) supplied onto the list of values stored here. The
96       anonymous array is created automatically if it doesn't yet exist.
97
98       If the 'unique' argument was supplied at the time the hash was tied, we
99       will use the associated function (either yours, if you supplied one; or
100       ours, if you didn't) and only add the item or items that are not
101       present.
102
103   FETCH
104       Fetches the current value(s) for a key, depending on the current mode
105       we're in.
106
107       •   'refs' mode
108
109           Always returns an anonymous array containing the values stored
110           under this key, or an empty anonymous array if there are none.
111
112       •   'iterators' mode
113
114           If there is a single entry, acts just like a normal hash fetch. If
115           there are multiple entries for a key, we automatically iterate over
116           the items stored under the key, returning undef when the last item
117           under that key has been fetched.
118
119           Storing more elements into a key while you're iterating over it
120           will result in the new elements being returned at the end of the
121           list. If you've turned on 'unique', remember that they won't be
122           stored if they're already in the value list for the key.
123
124               NOTE: If you store undef in your hash, and then store other
125               values, the iterator will, when it sees your undef, return it
126               as a normal value. This means that you won't be able to tell
127               whether that's your undef, or the 'I have no more data here'
128               undef. Using 'list' or 'refs' mode is strongly suggested if you
129               need to store data that may include undefs.
130
131           Note that every key has its own iterator, so you can mix accesses
132           across keys and still get all the values:
133
134             my $controller = tie %hash, 'Tie::Hash::MultiValue';
135             $controller->iterators;
136             $hash{x} = $_ for qw(a b c);
137             $hash{y} = $_ for qw(d e f);
138             while ( my($x, $y) = ($hash{x}, $hash{y}) {
139                # gets (a,d) (b,e) (c,f)
140             }
141
142   iterators
143       Called on the object returned from tie(). Tells FETCH to return
144       elements one at a time each time the key is accessed until no more
145       element remain.
146
147   refs
148       Tells FETCH to always return the reference associated with a key. (This
149       allows you to, for instance, replace all of the values at once with
150       different ones.)
151
152   mode
153       Tells you what mode you're currently in. Does not let you change it!
154
155
156
157perl v5.36.0                      2022-07-22          Tie::Hash::MultiValue(3)
Impressum