1Judy::L(3) User Contributed Perl Documentation Judy::L(3)
2
6 Judy::L - Efficient integer to integer map
7
9 Read a series of key/value pairs from the standard input, store in a
10 JudyL array, and then print out in sorted order.
11 use Judy::L qw( Set First Next Last Prev Delete Free );
13 # Load judy.
15 my $judy;
16 Set( $judy, 123, 345 );
17 Set( $judy, 324, 456 );
18 Set( $judy, 234, 567 );
19 # Print in ascending order.
21 print "ascending\n";
22 my ( undef, $value , $key ) = First( $judy, 0 );
23 while ( defined $key ) {
24 print "$key=$value\n";
25 ( undef, $value, $key ) = Next( $judy, $key );
26 }
27 # Now in descending order, deleting on the way.
29 print "descending\n";
30 ( undef, $value, $key ) = Last( $judy, -1 );
31 while ( defined $key ) {
32 print "$key=$value\n";
33 Delete( $judy, $key );
34 ( undef, $value, $key ) = Prev( $judy, $key );
35 }
36 # Ought to be a no-op since Judy is already empty.
38 Free( $judy );
39
41 All functions are exportable by Sub::Exporter.
42
44 Judy::L is the equivalent of a sparse array of integers. Memory to
45 support the array is allocated as key/value pairs are inserted, and
46 released as key/value pairs are deleted.
47 The value may be used as a scalar, or a pointer to a structure or block
49 of data (or even another Judy array). JudySL and JudyHS are implemented
50 on top of JudyL where the values are pointers. See
51 <http://perlmonks.org/?node_id=733140> for an example.
52 Nothing special is required to allocate a Judy::L array. Just start
54 using it.
55 my $judy;
57 if ( Get( $judy, 10 ) ) {
58 ....
59 }
60 As with an ordinary array, there are no duplicate keys in a Judy::L
62 array.
63
65 $Judy - Judy::L array
66 $Key - integer
67 $Value - integer
68 $PValue - pointer to integer
69 $Nth - integer
71 $PValue = Set( $Judy, $Key, $Value )
72 Insert/set an $Key and $Value into the Judy::L array $Judy.
73 Return $PValue pointing to $Value. Your program can use this pointer to
75 read or modify $Value until the next "Set()", "Delete()", "Free()" is
76 executed on $Judy. Examples:
77 use Judy::L qw( Set );
79 use Judy::Mem qw( Poke Peek );
80 $pvalue = Set( $judy, 2, 43 );
82 Poke( $pvalue, 44 );
84 44 == Peek( $pvalue );
85 Note: "Set()" and "Delete()" reorganize the Judy::L array. Therefore,
87 $PValue returned from previous Judy::L calls become invalid and must be
88 re-acquired.
89 Modifies $Judy to point to allocated Judy::L object.
91 bool = Delete( $Judy, $Key )
93 Delete the $Key/$Value pair from the Judy::L array. Return true if the
94 key was removed.
95 ($PValue, $Value) = Get( $Judy, $Key )
97 Get the pointer $PValue and value $Value associated with $Key in the
98 $Judy Judy array.
99 Return $PValue pointing to $Value and $Value. Return nothing if the
101 $Key was not present.
102
104 "First()", "Next()", "Last()", "Prev()" allow you to search for keys in
105 the array. You may search inclusively or exclusively, in either forward
106 or reverse directions. If successful, $Key is returned set to the found
107 key, $PValue is returned set to a pointer to $Key's $Value and $Value
108 is returned. If unsuccessful, nothing is returned.
109 FirstEmpty(), NextEmpty(), LastEmpty(), PrevEmpty() allow you to search
111 for keys that are not present ("empty") in the array. You may search
112 inclusively or exclusively, in either forward or reverse directions. If
113 successful, an $Key is returned set to a not present ("empty") key. If
114 unsuccessful, nothing is returned.
115 ( $PValue, $Value, $Key ) = First( $Judy, $Key )
117 Search (inclusive) for the first key present that is equal to or
118 greater than the passed $Key. (Start with "$Key = 0" to find the first
119 key in the array.) "First()" is typically used to begin a sorted-order
120 scan of the keys present in a JudyL array.
121 Returns nothing if the search finds nothing.
123 ( $PValue, $Value, $Key ) = Next( $Judy, $Key )
125 Search (exclusive) for the next key present that is greater than the
126 passed Key. Next() is typically used to continue a sorted-order scan of
127 the keys present in a JudyL array, or to locate a "neighbor" of a given
128 key.
129 # Prints the contents of $judy
131 my ( undef, $value, $key ) = First( $judy, 0 );
132 while ( defined $key ) {
133 print "$key=$value\n";
134 ( undef, $value, $key ) = Next( $judy, $key );
136 }
137 Returns nothing if the search finds nothing.
139 ( $PValue, $Value, $Key ) = Last( $Judy, $Key)
141 Search (inclusive) for the last key present that is equal to or less
142 than the passed $Key. (Start with "$Key = -1", that is, all ones, to
143 find the last key in the array.) Last() is typically used to begin a
144 reverse-sorted-order scan of the keys present in a JudyL array.
145 Returns nothing if the search finds nothing.
147 ( $PValue, $Value, $Key ) = Prev( $Judy, $Key )
149 Search (exclusive) for the previous key present that is less than the
150 passed $Key. Prev() is typically used to continue a reverse-sorted-
151 order scan of the keys present in a JudyL array, or to locate a
152 "neighbor" of a given key.
153 Returns nothing if the search finds nothing.
155 $Key = FirstEmpty( $Judy, $Key )
157 Search (inclusive) for the first key absent that is equal to or greater
158 than the passed $Key. (Start with $Key = 0 to find the first key absent
159 in the array.)
160 Returns nothing if the search finds nothing.
162 $Key = NextEmpty( $Judy, $Key )
164 Search (exclusive) for the next key absent that is greater than the
165 passed $Key.
166 Returns nothing if the search finds nothing.
168 $Key = LastEmpty( $Judy, $Key )
170 Search (inclusive) for the last key absent that is equal to or less
171 than the passed $Key. (Start with $Key = -1, that is, all ones, to find
172 the last key absent in the array.)
173 Returns nothing if the search finds nothing.
175 $Indx = PrevEmpty( $Judy, $Key )
177 Search (exclusive) for the previous key absent that is less than the
178 passed $Key.
179 Returns nothing if the search finds nothing.
181 $Rc = Count( $Judy, $Key1, $Key2 )
183 Count the number of keys present in $Judy between $Key1 and $Key2
184 (inclusive).
185 Return the count. A return value of 0 can be valid as a count.
187 To count all keys present in a Judy::L array, use:
189 my $count = Count( $judy, 0, -1 );
191 ( $PValue, $Value, $Key ) = Nth( $Judy, $Nth )
193 Locate the $Nth key that is present in $Judy ($Nth = 1 returns the
194 first key present).
195 Return pointer to value, value, and key. Return nothing if there isn't
197 an $Nth element.
198
200 bytes = Free( $Judy )
201 Frees an entire Judy::L array. This is much faster than a
202 "Next"/"Delete" loop. Return number of bytes freed. $Judy is set to 0.
203 bytes = MemUsed( $Judy )
205 Return the number of bytes of memory malloc()'ed by $Judy. This is a
206 very fast routine, and may be used before and after a "Set()" or
207 "Delete()" call with little performance impact.
208
210 See Judy.
211
213 See Judy.
214
216 See Judy.
217perl v5.34.0 2021-07-22 Judy::L(3)