NAME
Judy::SL - Efficient null-terminated string to integer map
SYNOPSIS
A simple string sort
use Judy::SL qw( Set First Next );
my $judy;
Set( $judy, 'The cupcake is a lie', 0 );
Set( $judy, 'The cake is a lie', 0 );
Set( $judy, 'The moose is a moose', 0 );
my (undef,undef,$key) = First($judy,'');
while ( defined $key ) {
print "$key\n";
( undef, undef, $key ) = Next( $judy, $key );
}EXPORT
All functions are exportable by Sub::Exporter.
DESCRIPTION
Judy::SL is the equivalent of a sorted set of strings, each associated with an integer. JudySL, the backing C library uses null-terminated strings so it'll do the wrong thing if your string has null characters in the middle of it. The perl wrapper automatically ensures your strings end in a null.
This is a form of "hash", where array elements are also sorted lexicographically (case-sensitive) by keys. This could be thought of as
@judy = ("Toto, I don't think we're in Kansas any more");Nothing special is required to allocate a Judy::SL array. Just start using it.
my $judy;
if ( Get( $judy, 'omg' ) ) {
Set( $judy, 'zomg', 42 );
...
}As with an ordinary array, there are no duplicate keys in a Judy::SL array.
DATA TYPES
$Judy - Judy::SL array
$Key - a string with no null characters
$Value - integer
$PValue - pointer to integer
BASIC FUNCTIONS
$PValue = Set( $Judy, $Key, $Value )
Insert/set a $Key string and $Value into $Judy.
Return $PValue pointing to the stored $Value. Your program can use this pointer to modify the stored $Value until the next Set(), Delete(), Free(). Example:
use Judy::Mem qw( Peek );
use Judy::SL qw( Set );
$pvalue = Set( $judy, 'aloha', 42 );
printf "aloha=%d\n", Peek( $pvalue );Note: Set() and Delete() reorganize the JudySL array. Therefore, pointers returned from previous JudySL calls become invalid and must be reacquired.
bool = Delete( $Judy, $Key )
Delete the specified $Key/$Value pair from Judy::SL. Returns true if the element was removed, false otherwise.
( $PValue, $Value ) = Get( $Judy, $Key )
Get $Key's $Value. If $Key exists in $Judy, return $PValue pointing to $Key's $Value and $Value in a list. Return nothing if $Key isn't present.
bytes = Free( $Judy )
Frees an entire Judy::SL array. Much faster than a First(), Delete() loop. Returns number of byes freed. $Judy is set to 0.
SEARCH FUNCTIONS
The Judy::SL search functions allow you to search for keys in the array. You may search inclusively or exclusively, in either forward or reverse directions.
( $PValue, $Value, $FoundKey ) = First( $Judy, $Key )
Search (inclusive) for the first $Key present that is equal to or greater than the passed $Key string. Start with an empty string to find the first key in the array. First() is typically used to begin a sorted-order scan of the valid $Keys in a JudySL array.
my ( undef, $value, $key ) = First( $judy, '' );
while ( defined $Key ) {
print "$key=$value\n";
( undef, $value, $key ) = Next( $judy, $key );
}( $PValue, $Value, $FoundKey ) = Next( $Judy, $Key )
Search (inclusive) for the first $Key present that is greater than the passed $Key string. Next() is typically used to continue a sorted-order scan of the valid $Keys in a JudySL array.
( $PValue, $Value, $FoundKey ) = Last( $Judy, $Key )
Search (inclusive) for the first $Key present that is less than or equal to the passed $Key string. Start with a maximum-valued string to look up the last $Key in the array, such as a max-length string of 0xff bytes. Last() is typically used to begin a reverse-sorted-order scan of the valid keys in a JudySL array.
use constant MAXLENGTH => 100;
my ( undef, $value, $key ) = Last( $judy, "\xff" x MAXLENGTH );
while ( defined $key ) {
print "$key=$value\n";
( undef, $value, $key ) = Prev( $judy, $key );
}( $PValue, $Value, $FoundKey ) = Prev( $Judy, $Key )
Search (inclusive) for the first $Key present that is less than the passed $Key string. Prev() is typically used to continue a reverse-sorted-order scan of the valid keys in a JudySL array.
UTILITY FUNCTIONS
bytes = Free( $Judy )
Frees an entire Judy::SL array. This is much faster than a Next/Delete loop. Return number of bytes freed. $Judy is set to 0.
MULTIDIMENSIONAL Judy::L
See Judy.
ERRORS & WARNINGS
See Judy.
AUTHOR
See Judy.