NAME

MCE::Shared::Array - Array helper class

VERSION

This document describes MCE::Shared::Array version 1.699_008

SYNOPSIS

   # non-shared
   use MCE::Shared::Array;
   my $ar = MCE::Shared::Array->new( @list );

   # shared
   use MCE::Shared;
   my $ar = MCE::Shared->array( @list );

   # oo interface
   $val   = $ar->set( $index, $val );
   $val   = $ar->get( $index);
   $val   = $ar->delete( $index );            # del is an alias for delete
   $bool  = $ar->exists( $index );
   void   = $ar->clear();
   $len   = $ar->len();                       # scalar @{ $ar }
   $len   = $ar->len( $index );               # length $ar->[ $index ]
   $val   = $ar->pop();
   $len   = $ar->push( @list );
   $val   = $ar->shift();
   $len   = $ar->unshift( @list );
   @list  = $ar->splice( $offset, $length, @list );

   $ar2   = $ar->clone( @indices );           # @indices is optional
   $ar3   = $ar->flush( @indices );
   $iter  = $ar->iterator( @indices );        # ($idx, $val) = $iter->()
   @keys  = $ar->keys( @indices );
   %pairs = $ar->pairs( @indices );
   @vals  = $ar->values( @indices );          # vals is an alias for values

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

   @vals  = $ar->range( $start, $stop );

   @vals  = $ar->sort();                      # $a <=> $b default
   @vals  = $ar->sort( "desc" );              # $b <=> $a
   @vals  = $ar->sort( "alpha" );             # $a cmp $b
   @vals  = $ar->sort( "alpha desc" );        # $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  = $ar->keys( "key =~ /$pattern/i" );
   @keys  = $ar->keys( "key !~ /$pattern/i" );
   @keys  = $ar->keys( "val =~ /$pattern/i" );
   @keys  = $ar->keys( "val !~ /$pattern/i" );

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

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

   # sugar methods without having to call set/get explicitly

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

DESCRIPTION

An array helper class for use with MCE::Shared.

QUERY STRING

Several methods in MCE::Shared::Array 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 indices in the array
      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 ( val [, val, ... ] )

new

clear

clone ( index [, index, ... ] )

clone

delete ( index )

exists ( index )

flush ( index [, index, ... ] )

flush

Same as clone. Clears all existing items before returning.

get ( index )

iterator ( index [, index, ... ] )

iterator ( "query string" )

iterator

keys ( index [, index, ... ] )

keys ( "query string" )

keys

len ( [ index ] )

mdel ( indices )

mexists ( indices )

mget ( indices )

mset ( index/value pairs )

pairs ( index [, index, ... ] )

pairs ( "query string" )

pairs

pop

push ( list )

set ( index, value )

shift

range ( start, stop )

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

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

splice ( offset, length, list )

unshift ( list )

values ( index [, index, ... ] )

values ( "query string" )

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 array index.

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::StdArray.

INDEX

MCE, MCE::Core, MCE::Shared

AUTHOR

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