NAME

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

VERSION

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

DESCRIPTION

A tiny in-memory NoSQL-like database for use as a standalone or managed by MCE::Shared.

This module was created mainly for having an efficient manner in which to manipulate hashes-of-hashes (HoH) and hashes-of-lists (HoA) structures with MCE::Shared. An application may choose to use both structures or one or the other. Internally, both structures reside in memory simultaneously.

 sub new {
    # Dual top-level hashes: [ HoH, HoA ]
    bless [
       MCE::Shared::Ordhash->new(),  # Stores Hash-of-Hashes (HoH)
       MCE::Shared::Ordhash->new(),  # Stores Hash-of-Lists  (HoA)
    ], shift;
 }

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

Several methods described below may resemble the "Redis" API. It is not the intent for this module to become 100% compatible.

SYNOPSIS

 # non-shared or local construction for use by a single process

 use MCE::Shared::Minidb;

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

 # construction for sharing with other threads and processes

 use MCE::Shared;

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

 # Hash of Hashes (HoH)
 # Update the hash stored at key1/key2

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

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

 # Hash of Lists (HoA)
 # Update the list stored at key1/key2

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

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

 # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+

 $db->pipeline(
    [ "lset", "key1", 0, "foo" ],
    [ "hset", "key1", "field1", "foo" ],
    [ "lset", "key2", 0, "bar", 1, "baz" ],
    [ "hset", "key2", "field1", "bar", "field2", "baz" ]
 );

SYNTAX for QUERY STRING

Several methods take a query string for an argument. The format of the string is described below. In the context of sharing, the query mechanism is beneficial for the shared-manager process. It is able to perform the query where the data resides versus the client-process grep locally involving lots of IPC.

 o Basic demonstration

   # query the hash stored at "some key"
   @keys = $db->hkeys( "some key", "query string given here" );
   @keys = $db->hkeys( "some key", "val =~ /pattern/" );

   # query the top-level hash (H)oH
   @keys = $db->hkeys( "query string given here" );
   @keys = $db->hkeys( "key =~ /pattern/" );

 o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
 o Multiple expressions delimited by :AND or :OR, mixed case allowed

   "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"   # HoH
   "key =~ /pattern/i :And index =~ /pattern/i"   # HoA
   "index eq foo baz :OR key !~ /pattern/i"       # e.g. 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

 o Quoting is optional inside the string
 o Primary keys (H)oH may have spaces, but not so for field_names

   "key =~ /pattern/i :AND field eq 'foo bar'"    # address eq "foo bar"
   "key =~ /pattern/i :AND field eq foo bar"      # address eq "foo bar"

   "key =~ 'some key' :AND 'some_field' eq 'foo bar'"  # ok: some_field
   "key =~ some key :AND some_field eq foo bar"

   "key =~ 'some key' :AND 'some field' eq 'foo bar'"  # fail: some field
   "key =~ some key :AND some field eq foo bar"

Examples.

 # search capability key/val: =~ !~ eq ne lt le gt ge == != < <= > >=
 # key/val means to match against actual key/val respectively

 # a query made to a hash stored at "some key"
 # note that "fieldNames" must not have spaces

   @keys  = $db->hkeys(
      "some key", "key eq some_field :or (val > 5 :and val < 9)"
   );

 # queries made to a list stored at "some key"

   @pairs = $db->lpairs( "some key", "key >= 50 :AND val =~ /sun|moon/" );
   @pairs = $db->lpairs( "some key", "val eq sun :OR val eq moon" );

 # the key modifier is the only thing possible for top-level queries
 # reason: value equals a hash or list reference containing 2nd-level data

   @keys  = $db->hkeys( "key eq 'some key'" );
   @keys  = $db->hkeys( "key eq some key" );

   @keys  = $db->hkeys( "key =~ /$pattern/i" );
   @keys  = $db->hkeys( "key !~ /$pattern/i" );

   %pairs = $db->hpairs( "key == $number" );
   %pairs = $db->hpairs( "key != $number" );
   %pairs = $db->hpairs( "key <  $number :or key > $number" );
   %pairs = $db->hpairs( "key <= $number" );
   %pairs = $db->hpairs( "key >  $number" );
   %pairs = $db->hpairs( "key >= $number" );

   @vals  = $db->hvals( "key eq $string" );
   @vals  = $db->hvals( "key ne $string with space" );
   @vals  = $db->hvals( "key lt $string :or key =~ /$pat1|$pat2/" );
   @vals  = $db->hvals( "key le $string :or key eq 'foo bar'" );
   @vals  = $db->hvals( "key le $string :or key eq foo bar" );
   @vals  = $db->hvals( "key gt $string" );
   @vals  = $db->hvals( "key ge $string" );

 # see select_aref and select_href below for db-like queries against
 # the underlying Ho(A) and Ho(H) structures respectively

API DOCUMENTATION - DB

MCE::Shared::Minidb->new ()

MCE::Shared->minidb ()

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

 # non-shared or local construction for use by a single process

 use MCE::Shared::Minidb;

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

 # construction for sharing with other threads and processes

 use MCE::Shared;

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

dump ( "file.dat" )

Dumps the in-memory content to a file.

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

pipeline ( [ func1, @args ], [ func2, @args ], ... )

Combines multiple commands for the object to be processed serially. For shared objects, the call is made atomically due to single IPC to the shared-manager process. The "pipeline" method is fully "wantarray"-aware and receives a list of commands and their arguments. In scalar or list context, it returns data from the last command in the pipeline.

 @vals = $db->pipeline(                     # ( "bar", "baz" )
    [ "hset", "some_key", "f1", "bar", "f2", "baz" ],
    [ "hget", "some_key", "f1", "f2" ]
 );

 $len = $db->pipeline(                      # 2, same as $db->hlen("key2)
    [ "hset", "some_key", "f1", "bar", "f2", "baz" ],
    [ "hlen", "some_key" ]
 );

 $db->pipeline(
    [ "lset", "key1", 0, "foo" ],
    [ "hset", "key1", "field1", "foo" ],
    [ "lset", "key2", 0, "bar", 1, "baz" ],
    [ "hset", "key2", "field1", "bar", "field2", "baz" ]
 );

Current API available since 1.809.

pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )

Same as "pipeline", but returns data for every command in the pipeline.

 @vals = $db->pipeline_ex(                  # ( "bar", "baz" )
    [ "hset", "key3", "field1", "bar" ],
    [ "hset", "key3", "field2", "baz" ]
 );

 $chunk_size = 3;

 $db->hset("some_key", chunk_id => 0);
 $db->lassign("some_key", @ARGV);

 while (1) {
    ($chunk_id, @next) = $db->pipeline_ex(
       [ "hincr",   "some_key", "chunk_id"     ],
       [ "lsplice", "some_key", 0, $chunk_size ]
    );

    last unless @next;

    ...
 }

Current API available since 1.809.

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 stored 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 stored 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" );

hsetnx ( key, field, value )

Sets the value of a hash field, only if the field does not exist. Returns a 1 for new field or 0 if the field already exists and no operation was performed.

 $ret = $db->hsetnx( "some_key", "field", "value" );

Current API available since 1.872.

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

This module is equipped with sugar methods to not have to call "set" and "get" explicitly. In shared context, the benefit is atomicity and reduction in inter-process communication.

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 stored 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 stored 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 stored 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" )

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

This module is equipped with sugar methods to not have to call "set" and "get" explicitly. In shared context, the benefit is atomicity and reduction in inter-process communication.