Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MCE::Shared::Minidb(3)User Contributed Perl DocumentatioMCE::Shared::Minidb(3)

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

VERSION
       This document describes MCE::Shared::Minidb version 1.873

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

   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 returns 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, <marioeroyA ATA gmailA DOTA com>

perl v5.32.1			  2020-08-01		MCE::Shared::Minidb(3)

NAME | VERSION | DESCRIPTION | SYNOPSIS | SYNTAX for QUERY STRING | API DOCUMENTATION - DB | API DOCUMENTATION - HASHES ( HoH ) | SUGAR METHODS - HASHES ( HoH ) | API DOCUMENTATION - LISTS ( HoA ) | SUGAR METHODS - LISTS ( HoA ) | CREDITS | INDEX | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MCE::Shared::Minidb&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help