The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
MCE-Shared-1.808
River stage one • 2 direct dependents • 3 total dependents
15 ++
/ MCE::Shared::Minidb

NAME

MCE::Shared::Minidb - A pure-Perl in-memory data store

VERSION

This document describes MCE::Shared::Minidb version 1.808

SYNOPSIS

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

   my $db = MCE::Shared::Minidb->new();

   # shared
   use MCE::Shared;

   my $db = MCE::Shared->minidb();

   # HoH
   $db->hset( "key1", "f1", "foo" );
   $db->hset( "key2", "f1", "bar", "f2", "baz" );

   $val = $db->hget( "key2", "f2" );  # "baz"

   # HoA
   $db->lset( "key1", 0, "foo" );
   $db->lset( "key2", 0, "bar", 1, "baz" );

   $val = $db->lget( "key2", 1 );     # "baz"

DESCRIPTION

A tiny in-memory NoSQL-like database for use with MCE::Shared. Although several methods resemble the Redis API, it is not the intent for this module to become 100% compatible with it.

This module was created mainly for having an efficient manner in which to manipulate hashes-of-hashes (HoH) and hashes-of-arrays (HoA) structures with MCE::Shared. Both are supported simultaneously due to being unique objects inside the $db object.

   sub new {
      # Parallel Hashes: [ HoH, HoA ]
      bless [
         MCE::Shared::Ordhash->new(),  # Hash of Hashes (HoH)
         MCE::Shared::Ordhash->new(),  # Hash of Arrays (HoA)
      ], shift;
   }

   # Ho(H) key => MCE::Shared::Hash->new();
   # Ho(A) key => MCE::Shared::Array->new()

SYNTAX for QUERY STRING

Several methods in MCE::Shared::Minidb take a query string.

   o Basic demonstration: @keys = $db->hkeys( "key", "val =~ /pattern/" );
   o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
   o Multiple expressions delimited by :AND or :OR
   o Quoting optional inside the string
  
     "key eq 'some key' :or (field > 5 :and field < 9)"
     "key eq some key :or (field > 5 :and field < 9)"
     "key =~ /pattern/i :and field =~ /pattern/i"
     "key =~ /pattern/i :and index =~ /pattern/i"
     "key =~ /pattern/i :and field eq 'foo bar'"   # address eq "foo bar"
     "key =~ /pattern/i :and field eq foo bar"     # address eq "foo bar"
     "index eq foo baz :or key !~ /pattern/i"      # 9 eq "foo baz"

     * key   matches on primary keys in the hash (H)oH or (H)oA
     * field matches on HoH->{key}{field} e.g. address
     * index matches on HoA->{key}[index] e.g. 9

  • Primary keys (H)oH may have spaces, but not secondary field names.

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

API DOCUMENTATION - DB

new

Constructs an empty in-memory HoH and HoA key-store database structure.

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

   $db = MCE::Shared::Minidb->new();

   # shared
   use MCE::Shared;

   $db = MCE::Shared->minidb();
dump ( "file.dat" )

Dumps the in-memory content to a file.

   $db->dump( "content.dat" );
restore ( "file.dat" )

Restores the in-memory content from a file.

   $db->restore( "content.dat" );
select_aref ( ":hashes", "select string" )
select_href ( ":hashes", "select string" )

Returns a list containing [ key, aref ] pairs or [ key, href ] pairs from the hash of hashes (HoH).

The select_aref and select_href methods take a select string supporting field names and optionally sort modifiers. The syntax for the query string, between :WHERE and :ORDER BY, is the same as described above.

The modifiers :WHERE, :AND, :OR, ORDER BY, ASC, DESC, and ALPHA may be mixed case. e.g. :Where

HoH select string:

   "f1 f2 f3 :WHERE f4 > 20 :AND key =~ /foo/ :ORDER BY f5 DESC ALPHA"
   "f5 f1 f2 :WHERE fN > 40 :AND key =~ /bar/ :ORDER BY key ALPHA"
   "f5 f1 f2 :WHERE fN > 40 :AND key =~ /bar/"
   "f5 f1 f2"

   * key matches on keys stored in the primary level hash (H)oH

HoH select synopsis:

   @rows = $db->select_aref( ":hashes", "some_field :ORDER BY some_field" );
   @rows = $db->select_aref( ":hashes", "f2 f6 f5 :ORDER BY f4" );

   # $rows[0] = [ "key1", [ "f2_val", "f6_val", "f5_val" ] ]
   # $rows[1] = [ "key2", [ "f2_val", "f6_val", "f5_val" ] ]
   # $rows[2] = [ "key3", [ "f2_val", "f6_val", "f5_val" ] ]
   # ...
   # $rows[N] = [ "keyN", [ "f2_val", "f6_val", "f5_val" ] ]

   @rows = $db->select_href( ":hashes", "some_field :ORDER BY some_field" );
   @rows = $db->select_href( ":hashes", "f2 f6 f5 :ORDER BY f4" );

   # $rows[0] = [ "key1", { f2 => "val", f6 => "val", f5 => "val" } ]
   # $rows[1] = [ "key2", { f2 => "val", f6 => "val", f5 => "val" } ]
   # $rows[2] = [ "key3", { f2 => "val", f6 => "val", f5 => "val" } ]
   # ...
   # $rows[N] = [ "keyN", { f2 => "val", f6 => "val", f5 => "val" } ]
select_aref ( ":lists", "select string" )
select_href ( ":lists", "select string" )

Returns a list containing [ key, aref ] pairs or [ key, href ] pairs from the hash of lists (HoA).

The select_aref and select_href methods take a select string supporting field indices and optionally sort modifiers. The syntax for the query string, between :WHERE and :ORDER BY, is the same as described above.

The modifiers :WHERE, :AND, :OR, ORDER BY, ASC, DESC, and ALPHA may be mixed case. e.g. :Where

HoA select string:

   "17 15 11 :WHERE 12 > 20 :AND key =~ /foo/ :ORDER BY 10 DESC ALPHA"
   "17 15 11 :WHERE 12 > 40 :AND key =~ /bar/ :ORDER BY key ALPHA"
   "17 15 11 :WHERE 12 > 40 :AND key =~ /bar/"
   "17 15 11"

   * key matches on keys stored in the primary level hash (H)oA
   * above, list indices are given as 17, 15, 11, 12, and 10
   * the shorter form is allowed e.g. "4 > 20 :AND key =~ /baz/"

HoA select synopsis:

   @rows = $db->select_aref( ":lists", "some_index :ORDER BY some_index" );
   @rows = $db->select_aref( ":lists", "2 6 5 :ORDER BY 4" );

   # $rows[0] = [ "key1", [ "2_val", "6_val", "5_val" ] ]
   # $rows[1] = [ "key2", [ "2_val", "6_val", "5_val" ] ]
   # $rows[2] = [ "key3", [ "2_val", "6_val", "5_val" ] ]
   # ...
   # $rows[N] = [ "keyN", [ "2_val", "6_val", "5_val" ] ]

   @rows = $db->select_href( ":lists", "some_index :ORDER BY some_index" );
   @rows = $db->select_href( ":lists", "2 6 5 :ORDER BY 4" );

   # $rows[0] = [ "key1", { 2 => "val", 6 => "val", 5 => "val" } ]
   # $rows[1] = [ "key2", { 2 => "val", 6 => "val", 5 => "val" } ]
   # $rows[2] = [ "key3", { 2 => "val", 6 => "val", 5 => "val" } ]
   # ...
   # $rows[N] = [ "keyN", { 2 => "val", 6 => "val", 5 => "val" } ]

API DOCUMENTATION - HASHES ( HoH )

hassign ( key, field, value [, field, value, ... ] )

Clears the hash stored at key, then sets the value of a hash field and returns its new value. Multiple field_value pairs may be set at once. In that case, the number of fields is returned. This is equivalent to hclear, hset.

   $val = $db->hassign( "some_key", "field", "value" );
   $len = $db->hassign( "some_key", "f1" => "val1", "f2" => "val2" );

API available since 1.007.

hclear ( key )

Removes all key-value pairs from the first level hash (H)oH when no arguments are given. Otherwise, removes all field-value pairs stored at key.

   $db->hclear;
   $db->hclear( "some_key" );
hdel ( key, field [, field, ... ] )

Deletes one or more hash fields. It returns the value associated with the field if a single field is given. Otherwise, it returns the number of fields actually removed from the hash stored at key. A field which does not exist in the hash is not counted.

   $val = $db->hdel( "some_key", "some_field" );
   $cnt = $db->hdel( "some_key", "field1", "field2" );
hdel ( key )

Deletes and returns the MCE::Shared::Hash object stored at key or undef if the key does not exists in the first level hash (H)oH.

   $ha_obj = $db->hdel( "some_key" );
hexists ( key, field [, field, ... ] )

Determines if a hash field exists. For multiple fields, a truth value is returned only if all given fields exist in the hash stored at key.

   if ( $db->hexists( "some_key", "some_field" ) ) { ... }
   if ( $db->hexists( "some_key", "f1", "f5" ) ) { ... }
hexists ( key )

Determines if a key exists in the first level hash (H)oH.

   if ( $db->hexists( "some_key" ) ) { ... }
hget ( key, field [, field, ... ] )

Gets the values of all given hash fields. The undef value is returned for fields which do not exists in the hash stored at key. Likewise, the undef value is returned if the key does not exists in the first level hash (H)oH.

   $val = $db->hget( "some_key", "field" );

   ( $val1, $val2 ) = $db->hget( "some_key", "field1", "field2" );
hget ( key )

Gets the MCE::Shared::Hash object for the hash stored at key or undef if the key does not exists in the first level hash (H)oH.

   $ha_obj = $db->hget( "some_key" );
hkeys ( key, [ field [, field, ... ] ] )

Returns keys stored in the first level hash (H)oH when no arguments are given. Otherwise, returns the given fields in the hash stored at key. Fields that do not exist will have the undef value. In scalar context, returns the size of the object, either the hash store at key or the first level hash.

   @keys   = $db->hkeys;
   @fields = $db->hkeys( "some_key" );
   @fields = $db->hkeys( "some_key", "field1", "field2" );
   $len    = $db->hkeys( "some_key" );
   $len    = $db->hkeys;
hkeys ( key, "query string" )

Returns only fields stored at key 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 = $db->hkeys( "some_key", "val eq some_value" );
   @keys = $db->hkeys( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
   @keys = $db->hkeys( "some_key", "val eq sun :OR val eq moon );
   $len  = $db->hkeys( "some_key", "key =~ /$pattern/" );
hkeys ( "query string" )

For the one argument form, the search is applied to keys stored in the primary hash only (H)oH. Therefore, the key modifier is the only thing possible if wanting any result.

   @keys = $db->hkeys( "key =~ /$pattern/" );
   $len  = $db->hkeys( "key =~ /$pattern/" );
hlen ( key [, field ] )

Returns the size of the first level hash (H)oH when no arguments are given. For the given key, returns the size of hash stored at key or optionally, the length of the value stored at key-field. It returns the undef value if either the given key or given field does not exists.

   $len = $db->hlen;
   $len = $db->hlen( $key );
   $len = $db->hlen( $key, $field );
hpairs ( key, [ field [, field, ... ] ] )

Returns key-value pairs stored in the first level hash (H)oH when no arguments are given. Otherwise, returns field-value pairs for the given fields in the hash stored at key. Fields that do not exist will have the undef value. In scalar context, returns the size of the object, either the hash store at key or the first level hash.

   @pairs = $db->hpairs;                 # ( key => href, ... )
   @pairs = $db->hpairs( "some_key" );   # ( field => value, ... )
   @pairs = $db->hpairs( "some_key", "field1", "field2" );
   $len   = $db->hpairs( "some_key" );
   $len   = $db->hpairs;
hpairs ( key, "query string" )

Returns only field-value pairs stored at key 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 = $db->hpairs( "some_key", "val eq some_value" );
   @pairs = $db->hpairs( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
   @pairs = $db->hpairs( "some_key", "val eq sun :OR val eq moon" );
   $len   = $db->hpairs( "some_key", "key =~ /$pattern/" );
hpairs ( "query string" )

For the one argument form, the search is applied to keys stored in the primary hash only (H)oH. Therefore, the key modifier is the only thing possible if wanting any result.

   @keys = $db->hpairs( "key =~ /$pattern/" );
   $len  = $db->hpairs( "key =~ /$pattern/" );
hset ( key, field, value [, field, value, ... ] )

Sets the value of a hash field and returns its new value. Multiple field_value pairs may be set at once. In that case, the number of fields stored at key is returned.

   $val = $db->hset( "some_key", "field", "value" );
   $len = $db->hset( "some_key", "f1" => "val1", "f2" => "val2" );
hshift

Removes and returns the first key-value pair or value in scalar context from the first-level hash (H)oH. If the HASH is empty, returns the undefined value.

   ( $key, $href ) = $db->hshift;

   $href = $db->hshift;
hsort ( "BY key [ ASC | DESC ] [ ALPHA ]" )
hsort ( "BY field [ ASC | DESC ] [ ALPHA ]" )

Returns sorted keys from the first level hash (H)oH, leaving the elements intact. In void context, sorts the first level hash in-place. Sorting is numeric by default.

   @keys = $db->hsort( "BY key" );
   @keys = $db->hsort( "BY some_field" );

   $db->hsort( "BY key" );
   $db->hsort( "BY some_field" );

If the keys or field values contain string values and you want to sort them lexicographically, specify the ALPHA modifier.

   @keys = $db->hsort( "BY key ALPHA" );
   @keys = $db->hsort( "BY some_field ALPHA" );

   $db->hsort( "BY key ALPHA" );
   $db->hsort( "BY some_field ALPHA" );

The default is ASC for sorting the elements from small to large. In order to sort from large to small, specify the DESC modifier.

   @keys = $db->hsort( "BY key DESC ALPHA" );
   @keys = $db->hsort( "BY some_field DESC ALPHA" );

   $db->hsort( "BY key DESC ALPHA" );
   $db->hsort( "BY some_field DESC ALPHA" );
hvals ( key, [ field [, field, ... ] ] )

Returns values stored in the first level hash (H)oH when no arguments are given. Otherwise, returns values for the given fields in the hash stored at key. Fields that do not exist will have the undef value. In scalar context, returns the size of the object, either the hash store at key or the first level hash.

   @hrefs = $db->hvals;
   @vals  = $db->hvals( "some_key" );
   @vals  = $db->hvals( "some_key", "field1", "field2" );
   $len   = $db->hvals( "some_key" );
   $len   = $db->hvals;
hvals ( key, "query string" )

Returns only values stored at key 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 = $db->hvals( "some_key", "val eq some_value" );
   @vals = $db->hvals( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
   @vals = $db->hvals( "some_key", "val eq sun :OR val eq moon" );
   $len  = $db->hvals( "some_key", "key =~ /$pattern/" );
hvals ( "query string" )

For the one argument form, the search is applied to keys stored in the primary hash only (H)oH. Therefore, the key modifier is the only thing possible if wanting any result.

   @keys = $db->hvals( "key =~ /$pattern/" );
   $len  = $db->hvals( "key =~ /$pattern/" );

SUGAR METHODS - HASHES ( HoH )

happend ( key, field, string )

Appends a value to key-field and returns its new length.

   $len = $db->happend( $key, $field, "foo" );
hdecr ( key, field )

Decrements the value of key-field by one and returns its new value.

   $num = $db->hdecr( $key, $field );
hdecrby ( key, field, number )

Decrements the value of key-field by the given number and returns its new value.

   $num = $db->hdecrby( $key, $field, 2 );
hgetdecr ( key, field )

Decrements the value of key-field by one and returns its old value.

   $old = $db->hgetdecr( $key, $field );
hgetincr ( key, field )

Increments the value of key-field by one and returns its old value.

   $old = $db->hgetincr( $key, $field );
hgetset ( key, field, value )

Sets the value of key-field and returns its old value.

   $old = $db->hgetset( $key, $field, "baz" );
hincr ( key, field )

Increments the value of key-field by one and returns its new value.

   $num = $db->hincr( $key, $field );
hincrby ( key, field, number )

Increments the value of key-field by the given number and returns its new value.

   $num = $db->hincrby( $key, $field, 2 );

API DOCUMENTATION - LISTS ( HoA )

lassign ( key, value [, value, ... ] )

Clears the list stored at key, then prepends one or multiple values and returns the new length. This is equivalent to lclear, lpush.

   $len = $db->lassign( "some_key", "val1", "val2" );

API available since 1.007.

lclear ( key )

Removes all key-value pairs from the first level hash (H)oA when no arguments are given. Otherwise, removes all elements from the list stored at key.

   $db->lclear;
   $db->lclear( "some_key" );
ldel ( key, index [, index, ... ] )

Deletes one or more elements by their indices. It returns the value associated with the index if a single index is given. Otherwise, it returns the number of elements actually removed from the list stored at key. An index which does not exists in the list is not counted.

   $val = $db->ldel( "some_key", 20 );
   $cnt = $db->ldel( "some_key", 0, 1 );
ldel ( key )

Deletes and returns the MCE::Shared::Array object stored at key or undef if the key does not exists in the first level hash (H)oA.

   $ar_obj = $db->ldel( "some_key" );
lexists ( key, index [, index, ... ] )

Determines if elements by their indices exist in the list. For multiple indices, a truth value is returned only if all given indices exist in the list stored at key. The behavior is strongly tied to the use of delete on lists.

   $db->lset( "some_key", 0, "value0" );
   $db->lset( "some_key", 1, "value1" );
   $db->lset( "some_key", 2, "value2" );
   $db->lset( "some_key", 3, "value3" );

   $db->lexists( "some_key", 2 );     # True
   $db->lexists( "some_key", 2, 3 );  # True
   $db->ldel   ( "some_key", 2 );     # value2

   $db->lexists( "some_key", 2 );     # False
   $db->lexists( "some_key", 2, 3 );  # False
   $db->lexists( "some_key", 3 );     # True
lexists ( key )

Determines if a key exists in the first level hash (H)oA.

   if ( $db->lexists( "some_key" ) ) { ... }
lget ( key, index [, index, ... ] )

Gets the values of all given list indices. The undef value is returned for indices which do not exists in the list stored at key. Likewise, the undef value is returned if the key does not exists in the first level hash (H)oA.

   $val = $db->lget( "some_key", 20 );

   ( $val1, $val2 ) = $db->lget( "some_key", 0, 1 );
lget ( key )

Gets the MCE::Shared::Array object for the list stored at key or undef if the key does not exists in the first level hash (H)oA.

   $ar_obj = $db->lget( "some_key" );
lkeys ( key, [ index [, index, ... ] ] )

Returns keys stored in the first level hash (H)oA when no arguments are given. Otherwise, returns the given indices in the list stored at key. Indices that do not exist will have the undef value. In scalar context, returns the size of the object, either the list store at key or the first level hash.

   @keys    = $db->lkeys;
   @indices = $db->lkeys( "some_key" );
   @indices = $db->lkeys( "some_key", 0, 1 );
   $len     = $db->lkeys( "some_key" );
   $len     = $db->lkeys;
lkeys ( key, "query string" )

Returns only indices stored at key 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 = $db->lkeys( "some_key", "val eq some_value" );
   @keys = $db->lkeys( "some_key", "key >= 50 :AND val =~ /sun|moon/" );
   @keys = $db->lkeys( "some_key", "val eq sun :OR val eq moon" );
   $len  = $db->lkeys( "some_key", "key =~ /$pattern/" );
lkeys ( "query string" )

For the one argument form, the search is applied to keys stored in the primary hash only (H)oA. Therefore, the key modifier is the only thing possible if wanting any result.

   @keys = $db->lkeys( "key =~ /$pattern/" );
   $len  = $db->lkeys( "key =~ /$pattern/" );
llen ( key [, index ] )

Returns the size of the first level hash (H)oA when no arguments are given. For the given index, returns the size of list stored at key or optionally, the length of the value stored at key-index. It returns the undef value if either the given key or given index does not exists.

   $len = $db->llen;
   $len = $db->llen( $key );
   $len = $db->llen( $key, 0 );
lpairs ( key, [ index [, index, ... ] ] )

Returns key-value pairs stored in the first level hash (H)oA when no arguments are given. Otherwise, returns index-value pairs for the given indices in the list stored at key. Indices that do not exist will have the undef value. In scalar context, returns the size of the object, either the list store at key or the first level hash.

   @pairs = $db->lpairs;                 # ( key => aref, ... )
   @pairs = $db->lpairs( "some_key" );   # ( index => value, ... )
   @pairs = $db->lpairs( "some_key", 0, 1 );
   $len   = $db->lpairs( "some_key" );
   $len   = $db->lpairs;
lpairs ( key, "query string" )

Returns only index-value pairs stored at key 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 = $db->lpairs( "some_key", "val eq some_value" );
   @pairs = $db->lpairs( "some_key", "key >= 50 :AND val =~ /sun|moon/" );
   @pairs = $db->lpairs( "some_key", "val eq sun :OR val eq moon" );
   $len   = $db->lpairs( "some_key", "key =~ /$pattern/" );
lpairs ( "query string" )

For the one argument form, the search is applied to keys stored in the primary hash only (H)oA. Therefore, the key modifier is the only thing possible if wanting any result.

   @keys = $db->lpairs( "key =~ /$pattern/" );
   $len  = $db->lpairs( "key =~ /$pattern/" );
lpop ( key )

Removes and returns the first value of the list stored at key. If there are no elements in the list, returns the undefined value.

   $val = $db->lpop( $key );
lpush ( key, value [, value, ... ] )

Prepends one or multiple values to the head of the list stored at key and returns the new length.

   $len = $db->lpush( "some_key", "val1", "val2" );
lrange ( key, start, stop )

Returns the specified elements of the list stored at key. The offsets start and stop 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 = $db->lrange( "some_key", 20, 29 );
   @list = $db->lrange( "some_key", -4, -1 );
lset ( key, index, value [, index, value, ... ] )

Sets the value of an element in a list by its index and returns its new value. Multiple index_value pairs may be set all at once. In that case, the length of the list is returned.

   $val = $db->lset( "some_key", 2, "value" );
   $len = $db->lset( "some_key", 0 => "val1", 1 => "val2" );
lshift

Removes and returns the first key-value pair or value in scalar context from the first-level hash (H)oA. If the HASH is empty, returns the undefined value. See lpop to shift the first value of the list stored at key.

   ( $key, $aref ) = $db->lshift;

   $aref = $db->lshift;
lsort ( "BY key [ ASC | DESC ] [ ALPHA ]" )
lsort ( "BY index [ ASC | DESC ] [ ALPHA ]" )

Returns sorted keys from the first level hash (H)oA, leaving the elements intact. In void context, sorts the first level hash in-place. Sorting is numeric by default.

   @keys = $db->lsort( "BY key" );
   @keys = $db->lsort( "BY some_index" );

   $db->lsort( "BY key" );
   $db->lsort( "BY some_index" );

If the keys or field values given by index contain string values and you want to sort them lexicographically, specify the ALPHA modifier.

   @keys = $db->lsort( "BY key ALPHA" );
   @keys = $db->lsort( "BY some_index ALPHA" );

   $db->lsort( "BY key ALPHA" );
   $db->lsort( "BY some_index ALPHA" );

The default is ASC for sorting the elements from small to large. In order to sort from large to small, specify the DESC modifier.

   @keys = $db->lsort( "BY key DESC ALPHA" );
   @keys = $db->lsort( "BY some_index DESC ALPHA" );

   $db->lsort( "BY key DESC ALPHA" );
   $db->lsort( "BY some_index DESC ALPHA" );
lsort ( key, "BY key [ ASC | DESC ] [ ALPHA ]" )
lsort ( key, "BY val [ ASC | DESC ] [ ALPHA ]" )

The two argument form has similar functionality. Here, sorting is applied to the list stored at key. For example, the following reverses the list stored at the given key. The BY key modifier refers to the indices in the list and not the values.

   $db->lsort( "some_key", "BY key DESC" );
lsplice ( key, offset [, length [, list ] ] )

Removes the elements designated by offset and length from the array stored at key, and replaces them with the elements of list, if any. The behavior is similar to the Perl splice function.

   @items = $db->lsplice( "some_key", 20, 2, @list );
   @items = $db->lsplice( "some_key", 20, 2 );
   @items = $db->lsplice( "some_key", 20 );
lvals ( key, [ index [, index, ... ] ] )

Returns values stored in the first level hash (H)oA when no arguments are given. Otherwise, returns values for the given indices in the list stored at key. Indices that do not exist will have the undef value. In scalar context, returns the size of the object, either the list store at key or the first level hash.

   @arefs = $db->lvals;
   @vals  = $db->lvals( "some_key" );
   @vals  = $db->lvals( "some_key", 0, 1 );
   $len   = $db->lvals( "some_key" );
   $len   = $db->lvals;
lvals ( key, "query string" )

Returns only values stored at key 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 = $db->lvals( "some_key", "val eq some_value" );
   @keys = $db->lvals( "some_key", "key >= 50 :AND val =~ /sun|moon/" );
   @keys = $db->lvals( "some_key", "val eq sun :OR val eq moon" );
   $len  = $db->lvals( "some_key", "key =~ /$pattern/" );
lvals ( "query string" )

For the one argument form, the search is applied to keys stored in the primary hash only (H)oA. Therefore, the key modifier is the only thing possible if wanting any result.

   @keys = $db->lvals( "key =~ /$pattern/" );
   $len  = $db->lvals( "key =~ /$pattern/" );
rpop ( key )

Removes and returns the last value of the list stored at key. If there are no elements in the list, returns the undefined value.

   $val = $db->rpop( $key );
rpush ( key, value [, value, ... ] )

Appends one or multiple values to the tail of the list stored at key and returns the new length.

   $len = $db->rpush( "some_key", "val1", "val2" );

SUGAR METHODS - LISTS ( HoA )

lappend ( key, index, string )

Appends a value to key-index and returns its new length.

   $len = $db->lappend( $key, 0, "foo" );
ldecr ( key, index )

Decrements the value of key-index by one and returns its new value.

   $num = $db->ldecr( $key, 0 );
ldecrby ( key, index, number )

Decrements the value of key-index by the given number and returns its new value.

   $num = $db->ldecrby( $key, 0, 2 );
lgetdecr ( key, index )

Decrements the value of key-index by one and returns its old value.

   $old = $db->lgetdecr( $key, 0 );
lgetincr ( key, index )

Increments the value of key-index by one and returns its old value.

   $old = $db->lgetincr( $key, 0 );
lgetset ( key, index, value )

Sets the value of key-index and return its old value.

   $old = $db->lgetset( $key, 0, "baz" );
lincr ( key, index )

Increments the value of key-index by one and returns its new value.

   $num = $db->lincr( $key, 0 );
lincrby ( key, index, number )

Increments the value of key-index by the given number and returns its new value.

   $num = $db->lincrby( $key, 0, 2 );

CREDITS

The implementation is inspired by various Redis Hash/List primitives at http://redis.io/commands.

INDEX

MCE, MCE::Hobo, MCE::Shared

AUTHOR

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