NAME

MCE::Shared::Array - Array helper class

VERSION

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

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 )

del

del is an alias for delete.

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 )

len

mdel ( index [, index, ... ] )

mexists ( index [, index, ... ] )

mget ( index [, index, ... ] )

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

merge

merge is an alias for mset.

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

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 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>