/ 
Judy-HS-0.08
/ Judy::SL

NAME

Judy::SL - Library for creating and accessing a dynamic array (hash), using a null-terminated string as a key

SYNOPSIS

Shows a string sort routine

my $judy = 0;
while (<>) {
    Insert($judy,$_,0);
}

my(undef,undef,$key) = First($judy,'');
if ( defined $key ) {
    print $key;
    print $key while (undef,undef,$key) = Next($judy,$key);
}

DESCRIPTION

A JudySL array is the equivalent of a sorted set of strings, each associated with a Value (word). A Value is addressed by a Key, which is a null-terminated character string of any length. Memory to support the array is allocated as key/value pairs are inserted, and released as key/value pairs are deleted. This is a form of "hash", where array elements are also sorted lexicographically (case-sensitive) by keys. This could be thought of as

@JudySLArray = ("Toto, I don't think we're in Kansas any more");

A Judy::SL array is allocated with a NULL pointer

my $judy = 0;

There are no duplicate keys in a Judy::SL array.

The default error handling sends a message to the standard error and terminates the program with exit(1).

EXPORT

All functions are exportable by Sub::Exporter.

DATA TYPES

  • $Judy - Judy::SL array

  • $Key - bytes

  • $Value - Stored integer

  • $PValue - JudySL array element. A pointer cast to integer.

  • $Rc - Return flag

BASIC FUNCTIONS

$PValue = Set( $Judy, $Key, $Value )

Insert a $Key string and $Value in the JudySL array. The stored $Value is updated to the passed-in $Value.

Return $PValue pointing to the stored $Value. Your program can use this pointer to modify the stored $Value, for example:

use Judy::Mem 'Poke';
my $Judy = 0;
my $PValue = Set( $Judy, 'Aloha', 0 );

Poke( $PValue, 1234 );

Note: Set() and Delete() reorganize the JudySL array. Therefore, pointers returned from previous JudySL calls become invalid and must be reacquired.

$Rc = Delete( $Judy, $Key )

Delete the specified $Key/$Value pair (array element) from the JudySL array.

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 an empty list if $Key is not present.

$Rc = Free( $Judy )

Given a pointer to a JudySL array ($Judy), free the entire array (much faster than using a First(), Delete() loop.)

Return $Rc set to the number of bytes freed and $Judy set to 0.

BASIC SEARCH FUNCTIONS

The JudySL search functions allow you to search for keyss in the array. You may search inclusively or exclusively, in either forward or reverse directions.

If successful, $PValue is returned set to a pointer to $Value, $Value is returned, and $Key is returned set to the found index. If unsuccessful, nothing is returned.

( $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 ( $Key ) {
    print "$Key=$Value\n";
    ( undef, $Value, $Key ) = Next( $Judy, $Key );
}

Search (exclusive) for the previous index present that is less than the passed Index string. JSLP() is typically used to continue a reverse-sorted-order scan of the valid indexes in a JudySL array, or to locate a "neighbor" of a given index.

JSLF() is typically u

( $PValue, $Value, $FoundKey ) = Next( $Judy, $Key )

Search (inclusive) for the first $Key present that is greater than the passed $Key string. (Start with an empty string to find the first key in the array.) 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.

my ( undef, $Value, $Key ) = Last( $Judy, '' );
while ( $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.