NAME

MCE::Shared::Hash - Hash helper class

VERSION

This document describes MCE::Shared::Hash version 1.699_009

SYNOPSIS

# non-shared
use MCE::Shared::Hash;

my $ha = MCE::Shared::Hash->new( @pairs );

# shared
use MCE::Shared;

my $ha = MCE::Shared->hash( @pairs );

# oo interface
$val   = $ha->set( $key, $val );
$val   = $ha->get( $key );
$val   = $ha->delete( $key );              # del is an alias for delete
$bool  = $ha->exists( $key );
void   = $ha->clear();
$len   = $ha->len();                       # scalar keys %{ $ha }
$len   = $ha->len( $key );                 # length $ha->{ $key }

$ha2   = $ha->clone( @keys );              # @keys is optional
$ha3   = $ha->flush( @keys );
$iter  = $ha->iterator( @keys );           # ($key, $val) = $iter->()
@keys  = $ha->keys( @keys );
%pairs = $ha->pairs( @keys );
@vals  = $ha->values( @keys );             # vals is an alias for values

$cnt   = $ha->mdel( @keys );
@vals  = $ha->mget( @keys );
$bool  = $ha->mexists( @keys );            # true if all keys exists
$len   = $ha->mset( $key/$val pairs );     # merge is an alias for mset

# search capability key/val { =~ !~ eq ne lt le gt ge == != < <= > >= }
# query string is quoteless, otherwise quote(s) are treated literally
# key/val means to match against actual key/val respectively
# do not mix :AND(s) and :OR(s) together

@keys  = $ha->keys( "key =~ /$pattern/i" );
@keys  = $ha->keys( "key !~ /$pattern/i" );
@keys  = $ha->keys( "val =~ /$pattern/i" );
@keys  = $ha->keys( "val !~ /$pattern/i" );

%pairs = $ha->pairs( "key == $number" );
%pairs = $ha->pairs( "key != $number :AND val > 100" );
%pairs = $ha->pairs( "key <  $number :OR key > $number" );
%pairs = $ha->pairs( "val <= $number" );
%pairs = $ha->pairs( "val >  $number" );
%pairs = $ha->pairs( "val >= $number" );

@vals  = $ha->values( "key eq $string" );
@vals  = $ha->values( "key ne $string with space" );
@vals  = $ha->values( "key lt $string :OR val =~ /$pat1|$pat2/" );
@vals  = $ha->values( "val le $string :AND val eq foo bar" );
@vals  = $ha->values( "val gt $string" );
@vals  = $ha->values( "val ge $string" );

# sugar methods without having to call set/get explicitly

$len   = $ha->append( $key, $string );     #   $val .= $string
$val   = $ha->decr( $key );                # --$val
$val   = $ha->decrby( $key, $number );     #   $val -= $number
$val   = $ha->getdecr( $key );             #   $val--
$val   = $ha->getincr( $key );             #   $val++
$val   = $ha->incr( $key );                # ++$val
$val   = $ha->incrby( $key, $number );     #   $val += $number
$old   = $ha->getset( $key, $new );        #   $o = $v, $v = $n, $o

DESCRIPTION

A hash helper class for use with MCE::Shared.

QUERY STRING

Several methods in MCE::Shared::Hash receive a query string argument. The string is quoteless. Basically, any quotes inside the string will be treated literally.

Search capability: =~ !~ eq ne lt le gt ge == != < <= > >=

"key =~ /pattern/i :AND val =~ /pattern/i"
"key =~ /pattern/i :AND val eq foo bar"     # val eq foo bar
"val eq foo baz :OR key !~ /pattern/i"

   key means to match against keys in the hash
   likewise, val means to match against values

:AND(s) and :OR(s) mixed together is not supported

API DOCUMENTATION

To be completed before the final 1.700 release.

new ( key, value [, key, value, ... ] )

new

clear

clone ( key [, key, ... ] )

clone

delete ( key )

del

del is an alias for delete.

exists ( key )

flush ( key [, key, ... ] )

flush

Same as clone. Clears all existing items before returning.

get ( key )

iterator ( key [, key, ... ] )

iterator ( "query string" )

iterator

keys ( key [, key, ... ] )

keys ( "query string" )

keys

len ( key )

len

mdel ( key [, key, ... ] )

mexists ( key [, key, ... ] )

mget ( key [, key, ... ] )

mset ( key, value [, key, value, ... ] )

merge

merge is an alias for mset.

pairs ( key [, key, ... ] )

pairs ( "query string" )

pairs

set ( key, value )

values ( key [, key, ... ] )

values ( "query string" )

values

vals

vals is an alias for values.

SUGAR METHODS

This module is equipped with sugar methods to not have to call set and get explicitly. The API resembles a subset of the Redis primitives http://redis.io/commands#strings with key representing the hash key.

append ( key, string )

Append a value to a key.

decr ( key )

Decrement the value of a key by one and return its new value.

decrby ( key, number )

Decrement the value of a key by the given number and return its new value.

getdecr ( key )

Decrement the value of a key by one and return its old value.

getincr ( key )

Increment the value of a key by one and return its old value.

getset ( key, value )

Set the value of a key and return its old value.

incr ( key )

Increment the value of a key by one and return its new value.

incrby ( key, number )

Increment the value of a key by the given number and return its new value.

CREDITS

The implementation is inspired by Tie::StdHash.

INDEX

MCE, MCE::Core, MCE::Shared

AUTHOR

Mario E. Roy, <marioeroy AT gmail DOT com>