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

NAME

6       Judy::SL - Efficient null-terminated string to integer map
7

SYNOPSIS

9       A simple string sort
10
11         use Judy::SL qw( Set First Next );
12
13         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
18         my (undef,undef,$key) = First($judy,'');
19         while ( defined $key ) {
20           print "$key\n";
21           ( undef, undef, $key ) = Next( $judy, $key );
22         }
23

EXPORT

25       All functions are exportable by Sub::Exporter.
26

DESCRIPTION

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
34       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
37         @judy = ("Toto, I don't think we're in Kansas any more");
38
39       Nothing special is required to allocate a Judy::SL array. Just start
40       using it.
41
42           my $judy;
43           if ( Get( $judy, 'omg' ) ) {
44               Set( $judy, 'zomg', 42 );
45               ...
46           }
47
48       As with an ordinary array, there are no duplicate keys in a Judy::SL
49       array.
50

DATA TYPES

52   $Judy - Judy::SL array
53   $Key - a string with no null characters
54   $Value - integer
55   $PValue - pointer to integer

BASIC FUNCTIONS

57   $PValue = Set( $Judy, $Key, $Value )
58       Insert/set a $Key string and $Value into $Judy.
59
60       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
64           use Judy::Mem qw( Peek );
65           use Judy::SL qw( Set );
66
67           $pvalue = Set( $judy, 'aloha', 42 );
68           printf "aloha=%d\n", Peek( $pvalue );
69
70       Note: Set() and Delete() reorganize the JudySL array. Therefore,
71       pointers returned from previous JudySL calls become invalid and must be
72       reacquired.
73
74   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
78   ( $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
83   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

SEARCH FUNCTIONS

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
92   ( $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
98           my ( undef, $value, $key ) = First( $judy, '' );
99           while ( defined $Key ) {
100               print "$key=$value\n";
101               ( undef, $value, $key ) = Next( $judy, $key );
102           }
103
104   ( $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
109   ( $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
116         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
123   ( $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

UTILITY FUNCTIONS

bytes = Free( $Judy )

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

MULTIDIMENSIONAL Judy::L

134       See Judy.
135

ERRORS & WARNINGS

137       See Judy.
138

AUTHOR

140       See Judy.
141
142
143
144perl v5.34.0                      2022-01-21                       Judy::SL(3)
Impressum