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.

cpanm Judy

perl -MCPAN -e shell
install Judy