view release on metacpan or  search on metacpan

lib/Algorithm/Toy/HashSC.pm  view on Meta::CPAN

=item B<clear_hash>

Clears the contents of the hash and returns the object.

The hash may also be cleared by default when various attributes
are altered.

=item B<get> I<key>

Obtains the value for the given I<key>. The key may be a scalar value,
or a coderef that provides a B<hashcode> method. Equality is tested for
via the C<eq> operator (L<perlop/"Equality Operators">).

Like B<take> but not destructive.

=item B<hash> I<key>

Used internally to calculate the index of the chain (or bucket) where
a given I<key> resides, within the limits of the B<modulus>
attribute. This calculation can be adjusted by supplying keys with a
B<hashcode> method.

=item B<keys>

Returns the keys present in the hash, if any. Keys are ordered based
on the structure of the hash chains, and this ordering will not
change unless the B<modulus> attribute or B<hash> or B<hashcode>
methods are altered.

=item B<keys_in> I<chain-number>

Returns the keys in the given I<chain-number> where I<chain-number> is
less than B<modulus>, if any.

=item B<keys_with> I<key>

Returns the keys in the same chain as the given key, if any. As with
B<keys>, this grouping will not change unless various attributes or
methods are altered. A smaller B<modulus> will cause more keys to
group together.

=item B<put> I<key> I<value>

Adds the given key and value to the hash. The I<key> may be an object
with a B<hashcode> method; this method should return a number that for
the expected set of key values results in evenly distributed numbers
across the given B<modulus>. If the key already exists in the hash, the
value will be updated.

=item B<take> I<key>

Deletes the given key/value pair from the hash, and returns the value. A
destructive version of B<get>.

=back

=head1 BUGS

=head2 Reporting Bugs

Bugs, patches, and whatnot might best be applied towards:

L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Algorithm-Toy-HashSC>

L<https://github.com/thrig/Algorithm-Toy-HashSC>

=head2 Known Issues

The default hash code calculation has not been tested to determine how
evenly it spreads keys out across the modulus space. As a workaround,
the hash key can be an object that provides a B<hashcode> method, in
which case this issue falls out of scope of this module.

=head1 SEE ALSO

L<perlsec/"Algorithmic Complexity Attacks"> - details on why Perl's hash
do not behave so simply as that of this module do.

"Algorithms" (4th Edition) by Robert Sedgewick and Kevin Wayne.

L<Hash::Util> - insight into Perl's hashes.

The "smhasher" project may help verify whether B<hashcode> functions are
as perfect as possible.

=head1 COPYRIGHT AND LICENSE

Copyright 2015 Jeremy Mates

This program is distributed under the (Revised) BSD License:
L<https://opensource.org/licenses/BSD-3-Clause>

=cut