NAME
MCE::Shared::Array - Array helper class
VERSION
This document describes MCE::Shared::Array version 1.699_011
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 == != < <= > >= }
# 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 = $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.
SYNTAX for QUERY STRING
Several methods in MCE::Shared::Array
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 = $ar->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 indices in the array
* 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 array-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 ( val [, val, ... ] )
-
Constructs a new object, with an optional list of values.
# non-shared use MCE::Shared::Array; $ar = MCE::Shared::Array->new( @list ); $ar = MCE::Shared::Array->new( ); # shared use MCE::Shared; $ar = MCE::Shared->array( @list ); $ar = MCE::Shared->array( );
- clear
-
Removes all elements from the array.
$ar->clear; @{$ar} = ();
- clone ( index [, index, ... ] )
-
Creates a shallow copy, a
MCE::Shared::Array
object. It returns an exact copy if no arguments are given. Otherwise, the object includes only the given indices in the same order. Indices that do not exist in the array will have theundef
value.$ar2 = $ar->clone( 0, 1 ); $ar2 = $ar->clone;
- delete ( index )
-
Deletes and returns the value associated by index or
undef
if index exceeds the size of the list.$val = $ar->delete( 20 ); $val = delete $ar->[ 20 ];
- del
-
del
is an alias fordelete
. - exists ( index )
-
Determines if an element by its index exists in the array. The behavior is strongly tied to the use of delete on lists.
$ar->push(qw/ value0 value1 value2 value3 /); $ar->exists( 2 ); # True $ar->exists( 2, 3 ); # True $ar->delete( 2 ); # value2 $ar->exists( 2 ); # False $ar->exists( 2, 3 ); # False $ar->exists( 3 ); # True exists $ar->[ 3 ];
- flush ( index [, index, ... ] )
-
Same as
clone
. Though, clears all existing items before returning. - get ( index )
-
Gets the value of an element by its index or
undef
if the index does not exists.$val = $ar->get( 2 ); $val = $ar->[ 2 ];
- iterator ( index [, index, ... ] )
-
Returns a code reference for iterating a list of index-value pairs stored in the array when no arguments are given. Otherwise, returns a code reference for iterating the given indices in the same order. Indices that do not exist will have the
undef
value.The list of indices to return is set when the closure is constructed. New indices added later are not included. Subsequently, the
undef
value is returned for deleted indices.$iter = $ar->iterator; $iter = $ar->iterator( 0, 1 ); while ( my ( $index, $val ) = $iter->() ) { ... }
- iterator ( "query string" )
-
Returns a code reference for iterating a list of index-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 = $ar->iterator( "val eq some value" ); $iter = $ar->iterator( "key >= 50 :AND val =~ /sun|moon|air|wind/" ); $iter = $ar->iterator( "val eq sun :OR val eq moon :OR val eq foo" ); $iter = $ar->iterator( "key =~ /$pattern/" ); while ( my ( $index, $val ) = $iter->() ) { ... }
- keys ( index [, index, ... ] )
-
Returns all indices in the array when no arguments are given. Otherwise, returns the given indices in the same order. Indices that do not exist will have the
undef
value. In scalar context, returns the size of the array.@keys = $ar->keys; @keys = $ar->keys( 0, 1 ); $len = $ar->keys;
- keys ( "query string" )
-
Returns only indices 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 = $ar->keys( "val eq some value" ); @keys = $ar->keys( "key >= 50 :AND val =~ /sun|moon|air|wind/" ); @keys = $ar->keys( "val eq sun :OR val eq moon :OR val eq foo" ); $len = $ar->keys( "key =~ /$pattern/" );
- len ( index )
-
Returns the size of the array when no arguments are given. For the given index, returns the length of the value stored at index or the
undef
value if the index does not exists.$len = $ar->len; $len = $ar->len( 0 ); $len = length $ar->[ 0 ];
- mdel ( index [, index, ... ] )
-
Deletes one or more elements by its index and returns the number of indices deleted. A given index which does not exist in the list is not counted.
$cnt = $ar->mdel( 0, 1 );
- mexists ( index [, index, ... ] )
-
Returns a true value if all given indices exists in the list. A false value is returned otherwise.
if ( $ar->mexists( 0, 1 ) ) { ... }
- mget ( index [, index, ... ] )
-
Gets multiple values from the list by its index. It returns
undef
for indices which do not exists in the list.( $val1, $val2 ) = $ar->mget( 0, 1 );
- mset ( index, value [, index, value, ... ] )
-
Sets multiple index-value pairs in the list and returns the length of the list.
$len = $ar->mset( 0 => "val1", 1 => "val2" );
- merge
-
merge
is an alias formset
. - pairs ( "query string" )
-
Returns index-value pairs in the array when no arguments are given. Otherwise, returns index-value pairs for the given indices in the same order. Indices that do not exist will have the
undef
value. In scalar context, returns the size of the array.@pairs = $ar->pairs; @pairs = $ar->pairs( 0, 1 ); $len = $ar->pairs;
- pairs ( index [, index, ... ] )
-
Returns only index-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 = $ar->pairs( "val eq some value" ); @pairs = $ar->pairs( "key >= 50 :AND val =~ /sun|moon|air|wind/" ); @pairs = $ar->pairs( "val eq sun :OR val eq moon :OR val eq foo" ); $len = $ar->pairs( "key =~ /$pattern/" );
- pop
-
Removes and returns the last value of the list. If there are no elements in the list, returns the undefined value.
$val = $ar->pop;
- push ( value [, value, ... ] )
-
Appends one or multiple values to the tail of the list and returns the new length.
$len = $ar->push( "val1", "val2" );
- set ( index, value )
-
Sets the value of the given array index and returns its new value.
$val = $ar->set( 2, "value" ); $val = $ar->[ 2 ] = "value";
- shift
-
Removes and returns the first value of the list. If there are no elements in the list, returns the undefined value.
$val = $ar->shift;
- range ( start, stop )
-
Returns the specified elements of the list. The offsets
start
andstop
can also be negative numbers indicating offsets starting at the end of the list.An empty list is returned if
start
is larger than the end of the list.stop
is set to the last index of the list if larger than the actual end of the list.@list = $ar->range( 20, 29 ); @list = $ar->range( -4, -1 );
- sort ( "BY val [ ASC | DESC ] [ ALPHA ]" )
-
Returns sorted values in list context, leaving the elements intact. In void context, sorts the list in-place. By default, sorting is numeric when no arguments are given. The
BY val
modifier is optional and may be omitted.@vals = $ar->sort( "BY val" ); $ar->sort();
If the list contains string values and you want to sort them lexicographically, specify the
ALPHA
modifier.@vals = $ar->sort( "BY val ALPHA" ); $ar->sort( "ALPHA" );
The default is
ASC
for sorting the list from small to large. In order to sort the list from large to small, specify theDESC
modifier.@vals = $ar->sort( "DESC ALPHA" ); $ar->sort( "DESC ALPHA" );
- splice ( offset [, length [, list ] ] )
-
Removes the elements designated by
offset
andlength
from the array, and replaces them with the elements oflist
, if any. The behavior is similar to the Perlsplice
function.@items = $ar->splice( 20, 2, @list ); @items = $ar->splice( 20, 2 ); @items = $ar->splice( 20 );
- unshift ( value [, value, ... ] )
-
Prepends one or multiple values to the head of the list and returns the new length.
$len = $ar->unshift( "val1", "val2" );
- values ( index [, index, ... ] )
-
Returns all values in the array when no arguments are given. Otherwise, returns values for the given indices in the same order. Indices that do not exist will have the
undef
value. In scalar context, returns the size of the array.@vals = $ar->values; @vals = $ar->values( 0, 1 ); $len = $ar->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.@keys = $ar->values( "val eq some value" ); @keys = $ar->values( "key >= 50 :AND val =~ /sun|moon|air|wind/" ); @keys = $ar->values( "val eq sun :OR val eq moon :OR val eq foo" ); $len = $ar->values( "key =~ /$pattern/" );
- vals
-
vals
is an alias forvalues
.
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 )
-
Appends a value to a key and returns its new length.
$len = $ar->append( 0, "foo" );
- decr ( key )
-
Decrements the value of a key by one and returns its new value.
$num = $ar->decr( 0 );
- decrby ( key, number )
-
Decrements the value of a key by the given number and returns its new value.
$num = $ar->decrby( 0, 2 );
- getdecr ( key )
-
Decrements the value of a key by one and returns its old value.
$old = $ar->getdecr( 0 );
- getincr ( key )
-
Increments the value of a key by one and returns its old value.
$old = $ar->getincr( 0 );
- getset ( key, value )
-
Sets the value of a key and returns its old value.
$old = $ar->getset( 0, "baz" );
- incr ( key )
-
Increments the value of a key by one and returns its new value.
$num = $ar->incr( 0 );
- incrby ( key, number )
-
Increments the value of a key by the given number and returns its new value.
$num = $ar->incrby( 0, 2 );
CREDITS
The implementation is inspired by Tie::StdArray.
INDEX
AUTHOR
Mario E. Roy, <marioeroy AT gmail DOT com>