NAME

MCE::Shared::Hash - Hash helper class

VERSION

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

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, ... ] )

Constructs a new object, with an optional list of key-value pairs.

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

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

   # shared
   use MCE::Shared;

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

clear

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

clone

delete ( key )

del

del is an alias for delete.

exists ( key )

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

flush

Same as clone. Though, clears all existing items before returning.

get ( key )

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

iterator ( "query string" )

iterator

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

keys ( "query string" )

keys

len ( key )

Returns the length of the value stored at key.

   $len = $ha->len( $key );

len

Returns the number of keys stored in the hash.

   $len = $ha->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 )

Appends a value to a key and returns its new length.

   $len = $ha->append( $key, 'foo' );

decr ( key )

Decrements the value of a key by one and returns its new value.

   $num = $ha->decr( $key );

decrby ( key, number )

Decrements the value of a key by the given number and returns its new value.

   $num = $ha->decrby( $key, 2 );

getdecr ( key )

Decrements the value of a key by one and returns its old value.

   $old = $ha->getdecr( $key );

getincr ( key )

Increments the value of a key by one and returns its old value.

   $old = $ha->getincr( $key );

getset ( key, value )

Sets the value of a key and returns its old value.

   $old = $ha->getset( $key, 'baz' );

incr ( key )

Increments the value of a key by one and returns its new value.

   $num = $ha->incr( $key );

incrby ( key, number )

Increments the value of a key by the given number and returns its new value.

   $num = $ha->incrby( $key, 2 );

CREDITS

The implementation is inspired by Tie::StdHash.

INDEX

MCE, MCE::Core, MCE::Shared

AUTHOR

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