1Judy::SL(3) User Contributed Perl Documentation Judy::SL(3)
2
6 Judy::SL - Efficient null-terminated string to integer map
7
9 A simple string sort
10 use Judy::SL qw( Set First Next );
12 my $judy;
14 Set( $judy, 'The cupcake is a lie', 0 );
15 Set( $judy, 'The cake is a lie', 0 );
16 Set( $judy, 'The moose is a moose', 0 );
17 my (undef,undef,$key) = First($judy,'');
19 while ( defined $key ) {
20 print "$key\n";
21 ( undef, undef, $key ) = Next( $judy, $key );
22 }
23
25 All functions are exportable by Sub::Exporter.
26
28 Judy::SL is the equivalent of a sorted set of strings, each associated
29 with an integer. JudySL, the backing C library uses null-terminated
30 strings so it'll do the wrong thing if your string has null characters
31 in the middle of it. The perl wrapper automatically ensures your
32 strings end in a null.
33 This is a form of "hash", where array elements are also sorted
35 lexicographically (case-sensitive) by keys. This could be thought of as
36 @judy = ("Toto, I don't think we're in Kansas any more");
38 Nothing special is required to allocate a Judy::SL array. Just start
40 using it.
41 my $judy;
43 if ( Get( $judy, 'omg' ) ) {
44 Set( $judy, 'zomg', 42 );
45 ...
46 }
47 As with an ordinary array, there are no duplicate keys in a Judy::SL
49 array.
50
52 $Judy - Judy::SL array
53 $Key - a string with no null characters
54 $Value - integer
55 $PValue - pointer to integer
57 $PValue = Set( $Judy, $Key, $Value )
58 Insert/set a $Key string and $Value into $Judy.
59 Return $PValue pointing to the stored $Value. Your program can use this
61 pointer to modify the stored $Value until the next "Set()", "Delete()",
62 "Free()". Example:
63 use Judy::Mem qw( Peek );
65 use Judy::SL qw( Set );
66 $pvalue = Set( $judy, 'aloha', 42 );
68 printf "aloha=%d\n", Peek( $pvalue );
69 Note: Set() and Delete() reorganize the JudySL array. Therefore,
71 pointers returned from previous JudySL calls become invalid and must be
72 reacquired.
73 bool = Delete( $Judy, $Key )
75 Delete the specified $Key/$Value pair from Judy::SL. Returns true if
76 the element was removed, false otherwise.
77 ( $PValue, $Value ) = Get( $Judy, $Key )
79 Get $Key's $Value. If $Key exists in $Judy, return $PValue pointing to
80 $Key's $Value and $Value in a list. Return nothing if $Key isn't
81 present.
82 bytes = Free( $Judy )
84 Frees an entire Judy::SL array. Much faster than a "First()",
85 "Delete()" loop. Returns number of byes freed. $Judy is set to 0.
86
88 The Judy::SL search functions allow you to search for keys in the
89 array. You may search inclusively or exclusively, in either forward or
90 reverse directions.
91 ( $PValue, $Value, $FoundKey ) = First( $Judy, $Key )
93 Search (inclusive) for the first $Key present that is equal to or
94 greater than the passed $Key string. Start with an empty string to find
95 the first key in the array. First() is typically used to begin a
96 sorted-order scan of the valid $Keys in a JudySL array.
97 my ( undef, $value, $key ) = First( $judy, '' );
99 while ( defined $Key ) {
100 print "$key=$value\n";
101 ( undef, $value, $key ) = Next( $judy, $key );
102 }
103 ( $PValue, $Value, $FoundKey ) = Next( $Judy, $Key )
105 Search (inclusive) for the first $Key present that is greater than the
106 passed $Key string. "Next()" is typically used to continue a sorted-
107 order scan of the valid $Keys in a JudySL array.
108 ( $PValue, $Value, $FoundKey ) = Last( $Judy, $Key )
110 Search (inclusive) for the first $Key present that is less than or
111 equal to the passed $Key string. Start with a maximum-valued string to
112 look up the last $Key in the array, such as a max-length string of 0xff
113 bytes. "Last()" is typically used to "begin" a reverse-sorted-order
114 scan of the valid keys in a JudySL array.
115 use constant MAXLENGTH => 100;
117 my ( undef, $value, $key ) = Last( $judy, "\xff" x MAXLENGTH );
118 while ( defined $key ) {
119 print "$key=$value\n";
120 ( undef, $value, $key ) = Prev( $judy, $key );
121 }
122 ( $PValue, $Value, $FoundKey ) = Prev( $Judy, $Key )
124 Search (inclusive) for the first $Key present that is less than the
125 passed $Key string. "Prev()" is typically used to "continue" a reverse-
126 sorted-order scan of the valid keys in a JudySL array.
127
130 Frees an entire Judy::SL array. This is much faster than a
131 "Next"/"Delete" loop. Return number of bytes freed. $Judy is set to 0.
132
134 See Judy.
135
137 See Judy.
138
140 See Judy.
141perl v5.34.0 2022-01-21 Judy::SL(3)