1Judy::L(3)            User Contributed Perl Documentation           Judy::L(3)
2
3
4

NAME

6       Judy::L - Efficient integer to integer map
7

SYNOPSIS

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
12         use Judy::L qw( Set First Next Last Prev Delete Free );
13
14         # Load judy.
15         my $judy;
16         Set( $judy, 123, 345 );
17         Set( $judy, 324, 456 );
18         Set( $judy, 234, 567 );
19
20         # 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
28         # 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
37         # Ought to be a no-op since Judy is already empty.
38         Free( $judy );
39

EXPORT

41       All functions are exportable by Sub::Exporter.
42

DESCRIPTION

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
48       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
53       Nothing special is required to allocate a Judy::L array. Just start
54       using it.
55
56           my $judy;
57           if ( Get( $judy, 10 ) ) {
58               ....
59           }
60
61       As with an ordinary array, there are no duplicate keys in a Judy::L
62       array.
63

DATA TYPES

65   $Judy - Judy::L array
66   $Key - integer
67   $Value - integer
68   $PValue - pointer to integer
69   $Nth - integer

BASIC FUNCTIONS

71   $PValue = Set( $Judy, $Key, $Value )
72       Insert/set an $Key and $Value into the Judy::L array $Judy.
73
74       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
78           use Judy::L   qw( Set         );
79           use Judy::Mem qw( Poke Peek );
80
81           $pvalue = Set( $judy, 2, 43 );
82
83           Poke( $pvalue, 44 );
84           44 == Peek( $pvalue );
85
86       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
90       Modifies $Judy to point to allocated Judy::L object.
91
92   bool = Delete( $Judy, $Key )
93       Delete the $Key/$Value pair from the Judy::L array. Return true if the
94       key was removed.
95
96   ($PValue, $Value) = Get( $Judy, $Key )
97       Get the pointer $PValue and value $Value associated with $Key in the
98       $Judy Judy array.
99
100       Return $PValue pointing to $Value and $Value. Return nothing if the
101       $Key was not present.
102

Search Functions

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
110       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
116   ( $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
122       Returns nothing if the search finds nothing.
123
124   ( $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
130         # Prints the contents of $judy
131         my ( undef, $value, $key ) = First( $judy, 0 );
132         while ( defined $key ) {
133             print "$key=$value\n";
134
135             ( undef, $value, $key ) = Next( $judy, $key );
136         }
137
138       Returns nothing if the search finds nothing.
139
140   ( $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
146       Returns nothing if the search finds nothing.
147
148   ( $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
154       Returns nothing if the search finds nothing.
155
156   $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
161       Returns nothing if the search finds nothing.
162
163   $Key = NextEmpty( $Judy, $Key )
164       Search (exclusive) for the next key absent that is greater than the
165       passed $Key.
166
167       Returns nothing if the search finds nothing.
168
169   $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
174       Returns nothing if the search finds nothing.
175
176   $Indx = PrevEmpty( $Judy, $Key )
177       Search (exclusive) for the previous key absent that is less than the
178       passed $Key.
179
180       Returns nothing if the search finds nothing.
181
182   $Rc = Count( $Judy, $Key1, $Key2 )
183       Count the number of keys present in $Judy between $Key1 and $Key2
184       (inclusive).
185
186       Return the count. A return value of 0 can be valid as a count.
187
188       To count all keys present in a Judy::L array, use:
189
190         my $count = Count( $judy, 0, -1 );
191
192   ( $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
196       Return pointer to value, value, and key. Return nothing if there isn't
197       an $Nth element.
198

UTILITY FUNCTIONS

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

MULTIDIMENSIONAL Judy::L

210       See Judy.
211

ERRORS & WARNINGS

213       See Judy.
214

AUTHOR

216       See Judy.
217
218
219
220perl v5.32.1                      2021-01-27                        Judy::L(3)
Impressum