/ 
Judy-0.41
River stage one • 1 direct dependent • 1 total dependent
/ Judy::SL

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.