NAME

Judy::HS - Library for creating and accessing a dynamic array, using an array-of-bytes as an Key and a word as a Value.

SYNOPSIS

Shows an ultra-cheap hash for removing duplicates.

my $judy = 0;
while (<>) {
  my ($ptr,$val) = Get( $judy, $_ );
  print if ! $ptr;
  Set( $judy, $_, 1 );
}

DESCRIPTION

Judy::HS is an interface to the JudyHS macros in the Judy array library.

A JudyHS array is the equivalent of an array of word-sized value/pointers. An Key is a pointer to an array-of-bytes. Rather than using a null terminated string, this difference from JudySL(3X) allows strings to contain all bits (specifically the null character). This new addition (May 2004) to Judy arrays 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 JudyHSFirst(), JudyHSNext(), JudyHSPrev() and JudyHSLast() neighbor search functions are not practical.

The hallmark of JudyHS is speed with scalability, but memory efficiency is excellent. 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.

A JudyHS array is allocated with an undefined or 0 value.

my $judy = 0;

EXPORT

All functions are exportable by Sub::Exporter.

DATA TYPES

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

  • $Rc_int - return flag.

  • $Rc_word - full word return value

  • $Judy - JudyHS array

  • $Key - array-of-bytes pointer

BASIC FUNCTIONS

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

Given a pointer to a JudyHS array ($Judy), insert an $Key string and a $Value into the JudyHS array: $Judy. Sets the value to $Value.

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()).

$Rc_int = Delete( $Judy, $Key )

Given a pointer to a JudyHS array ($Judy), delete the specified $Key along with the $Value from the JudyHS array.

Return $Rc_int set to 1 if successfully removed from the array. Return $Rc_int set to 0 if $Key was not present.

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

Given a pointer to a JudyHS array ($Judy), find $Value associated with $Key.

If $Key is in the hash, return $PValue a pointer to $Value and $Value. Return nothing if $Key is not in the hash.

$Rc_word = Free( $Judy )

Given a pointer to a JudyHS array ($Judy), free the entire array.

Return $Rc_word set to the number of bytes freed and $Judy set to NULL.

AUTHOR

Joshua ben Jore, <jjore at cpan.org>

JudyHS was invented and implemented by Doug Baskins after retiring from Hewlett-Packard.

SOURCE AVAILABILITY

This source is in Github: git://github.com/jbenjore/judy-hs.git

BUGS

Please report any bugs or feature requests to bug-Judy-HS at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Judy-HS. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Judy::HS

You can also look for information at:

ACKNOWLEDGEMENTS

Doug Baskins, totally.

COPYRIGHT & LICENSE

Copyright 2008 Joshua ben Jore, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.