NAME

MCE::Shared::Ordhash - Ordered-hash helper class

VERSION

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

SYNOPSIS

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

   my $oh = MCE::Shared::Ordhash->new( @pairs );

   # shared
   use MCE::Shared;

   my $oh = MCE::Shared->ordhash( @pairs );

   # oo interface
   $val   = $oh->set( $key, $val );
   $val   = $oh->get( $key );
   $val   = $oh->delete( $key );              # del is an alias for delete
   $bool  = $oh->exists( $key );
   void   = $oh->clear();
   $len   = $oh->len();                       # scalar keys %{ $oh }
   $len   = $oh->len( $key );                 # length $oh->{ $key }
   @pair  = $oh->pop();
   $len   = $oh->push( @pairs );
   @pair  = $oh->shift();
   $len   = $oh->unshift( @pairs );
   %pairs = $oh->splice( $offset, $length, @pairs );

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

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

   @vals  = $oh->sort();                      # by val $a <=> $b default
   @vals  = $oh->sort( "desc" );              # by val $b <=> $a
   @vals  = $oh->sort( "alpha" );             # by val $a cmp $b
   @vals  = $oh->sort( "alpha desc" );        # by val $b cmp $a

   @vals  = $oh->sort( "key" );               # by key $a <=> $b
   @vals  = $oh->sort( "key desc" );          # by key $b <=> $a
   @vals  = $oh->sort( "key alpha" );         # by key $a cmp $b
   @vals  = $oh->sort( "key alpha desc" );    # by key $b cmp $a

   # 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  = $oh->keys( "key =~ /$pattern/i" );
   @keys  = $oh->keys( "key !~ /$pattern/i" );
   @keys  = $oh->keys( "val =~ /$pattern/i" );
   @keys  = $oh->keys( "val !~ /$pattern/i" );

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

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

   # sugar methods without having to call set/get explicitly

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

DESCRIPTION

An ordered-hash helper class for use with MCE::Shared.

QUERY STRING

Several methods in MCE::Shared::Ordhash 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

pop

purge

push ( key/value pairs )

set ( key, value )

shift

sort ( "BY key [ ASC | DESC ] [ ALPHA ]" )

sort ( "BY val [ ASC | DESC ] [ ALPHA ]" )

sort ( "[ ASC | DESC ] [ ALPHA ]" )

splice ( offset, length, key/value pairs )

unshift ( key/value pairs )

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 Hash::Ordered.

INDEX

MCE, MCE::Core, MCE::Shared

AUTHOR

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