/ 
Judy-HS-0.02
/ Judy::HS

NAME

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

SYNOPSIS

Shows an ultra-cheap hash for removing duplicates.

my $judy = 0;
while (<>) {
  my ($ptr,$val) = JHSG($judy,$_);
  print if ! $ptr;
  (undef,$judy) = JHSI( $judy, $_, 0 );
}

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 Index is a pointer to an array-of-bytes of specified length: Length. 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, Indexes are not stored in any particular order. Therefore the JudyHSFirst(), JudyHSNext(), JudyHSPrev() and JudyHSLast() neighbor search functions are not practical. The Length of each array-of-bytes can be from 0 to the limits of malloc() (about 2GB).

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 Indexes and Values. JudyHS is designed to scale from 0 to billions of Indexes.

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

  • $Index - array-of-bytes pointer

BASIC FUNCTIONS

( $PValue, $Judy ) = JHSI( $Judy, $Index, $Value )

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

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

( $Rc_int, $Judy ) = JHSD( $Judy, $Index )

Given a pointer to a JudyHS array ($Judy), delete the specified $Index 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 $Index was not present.

( $PValue, $Value ) = JHSG( $Judy, $Index )

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

Return $PValue pointing to $Index's Value. Return $PValue set to NULL if the $Index was not present.

Return $Value of dereferencing $PValue if the $Index was present. Return undef in $Value otherwise.

( $Rc_word, $Judy ) = JHSFA( $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.