NAME

Judy::HS - Efficiet string to integer map

SYNOPSIS

Removing duplicates from a list using sugar

  use Judy::HS qw( Duplicates Free );

  my $judy;
  for (qw( d d c a d b c b a b a c )) {
    print "$_\n" if ! Duplicates( $judy, $_ );
  }
  printf "Freed %d bytes\n", Free( $judy );

Remove duplicates with less sugar

  use Judy::HS qw( Set Get Free );

  my $judy;
  for (qw( d d c a d b c b a b a c )) {
      my ( undef, $value ) = Get( $judy, $_ );
      if ( ! $value ) {
          Set( $judy, $_, 1 );
          print "$_\n";
      }
  }
  printf "Freed %d bytes\n", Free( $judy );

DESCRIPTION

Judy::HS is an equivalent to a hash of integers. The keys are all strings, the values are integers. JudyHS is a hybrid using the best capabilities of hashing and Judy methods. JudyHS does not have a poor performance case where knowledge of the hash algorithm can be used to degrade the performance.

Since JudyHS is based on a hash method, Keys are not stored in any particular order. Therefore the First(), Next(), Prev() and Last() neighbor search functions are not practical. To enumerate a Judy::HS object, see http://perlmonks.org/?node_id=733140. This is not supported but it works.

The hallmark of JudyHS is speed with scalability, but memory efficiency is excelleny. The speed is very competitive with the best hashing methods. The memory efficiency is similar to a linked list of the same Keys and Values. JudyHS is designed to scale from 0 to billions of Keys.

Nothing special is required to allocate a Judy::HS 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::HS array.

DATA TYPES

$Judy - Judy::HS 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 and $Value into $Judy.

Returns $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::HS qw( Set );

  $pvalue = Set( $judy, "al\0ha", 42 );
  printf "al\\0ha=%d\n", Peek( $pvalue );

Note: Set() and Delete can reorganize the JudyHS array. Therefore, pointers returned from previous JudyHS calls become invalid and must be re-acquired (using Get()).

bool = Delete( $Judy, $Key )

Delete the specified $Key/$Value pair from Judy::HS. 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.

SEARCH FUNCTIONS

There are no search functions and no endorsed methods for enumerating the contents of Judy::HS. It's possible though. See http://perlmonks.org/?node_id=733140.

UTILITY FUNCTIONS

bytes = Free( $Judy )

Frees an entire Judy::HS array. $Judy is set to 0.

bytes = MemUsed( $Judy )

Returns the size of a Judy::HS array. This implementation is not supplied by libJudy.

MULTIDIMENSIONAL Judy::HS

See Judy.

ERRORS & WARNINGS

See Judy.

AUTHOR

See Judy.

cpanm Judy

perl -MCPAN -e shell
install Judy