The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
MCE-1.700
River stage three • 21 direct dependents • 313 total dependents
103 ++
/ MCE::Shared::Hash

NAME

MCE::Shared::Hash - Hash helper class

VERSION

This document describes MCE::Shared::Hash version 1.700

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 == != < <= > >= }
   # key/val means to match against actual key/val respectively
   # do not add quotes inside the string unless intended literally
   # 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.

SYNTAX for QUERY STRING

Several methods in MCE::Shared::Hash take a query string for an argument. The format of the string is quoteless. Therefore, any quotes inside the string is treated literally.

   o Basic demonstration: @keys = $ha->keys( "val =~ /pattern/" );
   o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
   o Multiple expressions are delimited by :AND or :OR.

     "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 matches on keys in the hash
     * val matches on values

  • The modifiers :AND and :OR may be mixed case. e.g. :And

  • Mixing :AND and :OR in the query is not supported.

API DOCUMENTATION

This module may involve TIE when accessing the object via hash-like behavior. Only shared instances are impacted if doing so. Although likely fast enough for many use cases, use the OO interface if better performance is desired.

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

Removes all key-value pairs from the hash.

   $ha->clear;
   %{$ha} = ();
clone ( key [, key, ... ] )

Creates a shallow copy, a MCE::Shared::Hash object. It returns an exact copy if no arguments are given. Otherwise, the object includes only the given keys. Keys that do not exist in the hash will have the undef value.

   $ha2 = $ha->clone( "key1", "key2" );
   $ha2 = $ha->clone;
delete ( key )

Deletes and returns the value by given key or undef if the key does not exists in the hash.

   $val = $ha->delete( "some_key" );
   $val = delete $ha->{ "some_key" };
del

del is an alias for delete.

exists ( key )

Determines if a key exists in the hash.

   if ( $ha->exists( "some_key" ) ) { ... }
   if ( exists $ha->{ "some_key" } ) { ... }
flush ( key [, key, ... ] )

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

get ( key )

Gets the value of a hash key or undef if the key does not exists.

   $val = $ha->get( "some_key" );
   $val = $ha->{ "some_key" };
iterator ( key [, key, ... ] )

Returns a code reference for iterating a list of key-value pairs stored in the hash when no arguments are given. Otherwise, returns a code reference for iterating the given keys in the same order. Keys that do not exist will have the undef value.

The list of keys to return is set when the closure is constructed. Later keys added to the hash are not included. Subsequently, the undef value is returned for deleted keys.

   $iter = $ha->iterator;
   $iter = $ha->iterator( "key1", "key2" );

   while ( my ( $key, $val ) = $iter->() ) {
      ...
   }
iterator ( "query string" )

Returns a code reference for iterating a list of key-value pairs that match the given criteria. It returns an empty list if the search found nothing. The syntax for the query string is described above.

   $iter = $ha->iterator( "val eq some_value" );
   $iter = $ha->iterator( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
   $iter = $ha->iterator( "val eq sun :OR val eq moon :OR val eq foo" );
   $iter = $ha->iterator( "key =~ /$pattern/" );

   while ( my ( $key, $val ) = $iter->() ) {
      ...
   }
keys ( key [, key, ... ] )

Returns all keys in the hash when no arguments are given. Otherwise, returns the given keys in the same order. Keys that do not exist will have the undef value. In scalar context, returns the size of the hash.

   @keys = $ha->keys;
   @keys = $ha->keys( "key1", "key2" );
   $len  = $ha->keys;
keys ( "query string" )

Returns only keys that match the given criteria. It returns an empty list if the search found nothing. The syntax for the query string is described above. In scalar context, returns the size of the resulting list.

   @keys = $ha->keys( "val eq some_value" );
   @keys = $ha->keys( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
   @keys = $ha->keys( "val eq sun :OR val eq moon :OR val eq foo" );
   $len  = $ha->keys( "key =~ /$pattern/" );
len ( key )

Returns the size of the hash when no arguments are given. For the given key, returns the length of the value stored at key or the undef value if the key does not exists.

   $size = $ha->len;
   $len  = $ha->len( "key1" );
   $len  = length $ha->{ "key1" };
mdel ( key [, key, ... ] )

Deletes one or more keys in the hash and returns the number of keys deleted. A given key which does not exist in the hash is not counted.

   $cnt = $ha->mdel( "key1", "key2" );
mexists ( key [, key, ... ] )

Returns a true value if all given keys exists in the hash. A false value is returned otherwise.

   if ( $ha->mexists( "key1", "key2" ) ) { ... }
mget ( key [, key, ... ] )

Gets the values of all given keys. It returns undef for keys which do not exists in the hash.

   ( $val1, $val2 ) = $ha->mget( "key1", "key2" );
mset ( key, value [, key, value, ... ] )

Sets multiple key-value pairs in a hash and returns the number of keys stored in the hash.

   $len = $ha->mset( "key1" => "val1", "key2" => "val2" );
merge

merge is an alias for mset.

pairs ( "query string" )

Returns key-value pairs in the hash when no arguments are given. Otherwise, returns key-value pairs for the given keys in the same order. Keys that do not exist will have the undef value. In scalar context, returns the size of the hash.

   @pairs = $ha->pairs;
   @pairs = $ha->pairs( "key1", "key2" );
   $len   = $ha->pairs;
pairs ( key [, key, ... ] )

Returns only key-value pairs that match the given criteria. It returns an empty list if the search found nothing. The syntax for the query string is described above. In scalar context, returns the size of the resulting list.

   @pairs = $ha->pairs( "val eq some_value" );
   @pairs = $ha->pairs( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
   @pairs = $ha->pairs( "val eq sun :OR val eq moon :OR val eq foo" );
   $len   = $ha->pairs( "key =~ /$pattern/" );
set ( key, value )

Sets the value of the given hash key and returns its new value.

   $val = $ha->set( "key", "value" );
   $val = $ha->{ "key" } = "value";
values ( key [, key, ... ] )

Returns all values in the hash when no arguments are given. Otherwise, returns values for the given keys in the same order. Keys that do not exist will have the undef value. In scalar context, returns the size of the hash.

   @vals = $ha->values;
   @vals = $ha->values( "key1", "key2" );
   $len  = $ha->values;
values ( "query string" )

Returns only values that match the given criteria. It returns an empty list if the search found nothing. The syntax for the query string is described above. In scalar context, returns the size of the resulting list.

   @vals = $ha->values( "val eq some_value" );
   @vals = $ha->values( "key eq some_key :AND val =~ /sun|moon|air|wind/" );
   @vals = $ha->values( "val eq sun :OR val eq moon :OR val eq foo" );
   $len  = $ha->values( "key =~ /$pattern/" );
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>