1Tie::IxHash(3) User Contributed Perl Documentation Tie::IxHash(3)
2
6 Tie::IxHash - ordered associative arrays for Perl
7
9 # simple usage
10 use Tie::IxHash;
11 tie HASHVARIABLE, Tie::IxHash [, LIST];
12 # OO interface with more powerful features
14 use Tie::IxHash;
15 TIEOBJECT = Tie::IxHash->new( [LIST] );
16 TIEOBJECT->Splice( OFFSET [, LENGTH [, LIST]] );
17 TIEOBJECT->Push( LIST );
18 TIEOBJECT->Pop;
19 TIEOBJECT->Shift;
20 TIEOBJECT->Unshift( LIST );
21 TIEOBJECT->Keys( [LIST] );
22 TIEOBJECT->Values( [LIST] );
23 TIEOBJECT->Indices( LIST );
24 TIEOBJECT->Delete( [LIST] );
25 TIEOBJECT->Replace( OFFSET, VALUE, [KEY] );
26 TIEOBJECT->Reorder( LIST );
27 TIEOBJECT->SortByKey;
28 TIEOBJECT->SortByValue;
29 TIEOBJECT->Length;
30
32 This Perl module implements Perl hashes that preserve the order in
33 which the hash elements were added. The order is not affected when
34 values corresponding to existing keys in the IxHash are changed. The
35 elements can also be set to any arbitrary supplied order. The familiar
36 perl array operations can also be performed on the IxHash.
37 Standard "TIEHASH" Interface
39 The standard "TIEHASH" mechanism is available. This interface is recom‐
41 mended for simple uses, since the usage is exactly the same as regular
42 Perl hashes after the "tie" is declared.
43 Object Interface
45 This module also provides an extended object-oriented interface that
47 can be used for more powerful operations with the IxHash. The follow‐
48 ing methods are available:
49 FETCH, STORE, DELETE, EXISTS
51 These standard "TIEHASH" methods mandated by Perl can be used
52 directly. See the "tie" entry in perlfunc(1) for details.
53 Push, Pop, Shift, Unshift, Splice
55 These additional methods resembling Perl functions are avail‐
56 able for operating on key-value pairs in the IxHash. The behav‐
57 ior is the same as the corresponding perl functions, except
58 when a supplied hash key already exists in the hash. In that
59 case, the existing value is updated but its order is not
60 affected. To unconditionally alter the order of a supplied
61 key-value pair, first "DELETE" the IxHash element.
62 Keys Returns an array of IxHash element keys corresponding to the
64 list of supplied indices. Returns an array of all the keys if
65 called without arguments. Note the return value is mostly only
66 useful when used in a list context (since perl will convert it
67 to the number of elements in the array when used in a scalar
68 context, and that may not be very useful).
69 If a single argument is given, returns the single key corre‐
71 sponding to the index. This is usable in either scalar or list
72 context.
73 Values Returns an array of IxHash element values corresponding to the
75 list of supplied indices. Returns an array of all the values
76 if called without arguments. Note the return value is mostly
77 only useful when used in a list context (since perl will con‐
78 vert it to the number of elements in the array when used in a
79 scalar context, and that may not be very useful).
80 If a single argument is given, returns the single value corre‐
82 sponding to the index. This is usable in either scalar or list
83 context.
84 Indices Returns an array of indices corresponding to the supplied list
86 of keys. Note the return value is mostly only useful when used
87 in a list context (since perl will convert it to the number of
88 elements in the array when used in a scalar context, and that
89 may not be very useful).
90 If a single argument is given, returns the single index corre‐
92 sponding to the key. This is usable in either scalar or list
93 context.
94 Delete Removes elements with the supplied keys from the IxHash.
96 Replace Substitutes the IxHash element at the specified index with the
98 supplied value-key pair. If a key is not supplied, simply sub‐
99 stitutes the value at index with the supplied value. If an ele‐
100 ment with the supplied key already exists, it will be removed
101 from the IxHash first.
102 Reorder This method can be used to manipulate the internal order of the
104 IxHash elements by supplying a list of keys in the desired
105 order. Note however, that any IxHash elements whose keys are
106 not in the list will be removed from the IxHash.
107 Length Returns the number of IxHash elements.
109 SortByKey
111 Reorders the IxHash elements by textual comparison of the keys.
112 SortByValue
114 Reorders the IxHash elements by textual comparison of the val‐
115 ues.
116
118 use Tie::IxHash;
119 # simple interface
121 $t = tie(%myhash, Tie::IxHash, 'a' => 1, 'b' => 2);
122 %myhash = (first => 1, second => 2, third => 3);
123 $myhash{fourth} = 4;
124 @keys = keys %myhash;
125 @values = values %myhash;
126 print("y") if exists $myhash{third};
127 # OO interface
129 $t = Tie::IxHash->new(first => 1, second => 2, third => 3);
130 $t->Push(fourth => 4); # same as $myhash{'fourth'} = 4;
131 ($k, $v) = $t->Pop; # $k is 'fourth', $v is 4
132 $t->Unshift(neg => -1, zeroth => 0);
133 ($k, $v) = $t->Shift; # $k is 'neg', $v is -1
134 @oneandtwo = $t->Splice(1, 2, foo => 100, bar => 101);
135 @keys = $t->Keys;
137 @values = $t->Values;
138 @indices = $t->Indices('foo', 'zeroth');
139 @itemkeys = $t->Keys(@indices);
140 @itemvals = $t->Values(@indices);
141 $t->Replace(2, 0.3, 'other');
142 $t->Delete('second', 'zeroth');
143 $len = $t->Length; # number of key-value pairs
144 $t->Reorder(reverse @keys);
146 $t->SortByKey;
147 $t->SortByValue;
148
150 You cannot specify a negative length to "Splice". Negative indexes are
151 OK, though.
152 Indexing always begins at 0 (despite the current $[ setting) for all
154 the functions.
155
157 Addition of elements with keys that already exist to the end of the
158 IxHash must be controlled by a switch.
159 Provide "TIEARRAY" interface when it stabilizes in Perl.
161 Rewrite using XSUBs for efficiency.
163
165 Gurusamy Sarathy gsar@umich.edu
166 Copyright (c) 1995 Gurusamy Sarathy. All rights reserved. This program
168 is free software; you can redistribute it and/or modify it under the
169 same terms as Perl itself.
170
172 Version 1.21 20 Nov 1997
173
175 perl(1)
176perl v5.8.8 1997-11-20 Tie::IxHash(3)