1MCE::Shared::Minidb(3)User Contributed Perl DocumentationMCE::Shared::Minidb(3)
2
3
4

NAME

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

VERSION

9       This document describes MCE::Shared::Minidb version 1.886
10

DESCRIPTION

12       A tiny in-memory NoSQL-like database for use as a standalone or managed
13       by MCE::Shared.
14
15       This module was created mainly for having an efficient manner in which
16       to manipulate hashes-of-hashes (HoH) and hashes-of-lists (HoA)
17       structures with MCE::Shared. An application may choose to use both
18       structures or one or the other. Internally, both structures reside in
19       memory simultaneously.
20
21        sub new {
22           # Dual top-level hashes: [ HoH, HoA ]
23           bless [
24              MCE::Shared::Ordhash->new(),  # Stores Hash-of-Hashes (HoH)
25              MCE::Shared::Ordhash->new(),  # Stores Hash-of-Lists  (HoA)
26           ], shift;
27        }
28
29        # each Ho(H) key => MCE::Shared::Hash->new()
30        # each Ho(A) key => MCE::Shared::Array->new()
31
32       Several methods described below may resemble the "Redis" API. It is not
33       the intent for this module to become 100% compatible.
34

SYNOPSIS

36        # non-shared or local construction for use by a single process
37
38        use MCE::Shared::Minidb;
39
40        my $db = MCE::Shared::Minidb->new();
41
42        # construction for sharing with other threads and processes
43
44        use MCE::Shared;
45
46        my $db = MCE::Shared->minidb();
47
48        # Hash of Hashes (HoH)
49        # Update the hash stored at key1/key2
50
51        $db->hset( "key1", "f1", "foo" );
52        $db->hset( "key2", "f1", "bar", "f2", "baz" );
53
54        $val = $db->hget( "key2", "f2" );  # "baz"
55
56        # Hash of Lists (HoA)
57        # Update the list stored at key1/key2
58
59        $db->lset( "key1", 0, "foo" );
60        $db->lset( "key2", 0, "bar", 1, "baz" );
61
62        $val = $db->lget( "key2", 1 );     # "baz"
63
64        # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+
65
66        $db->pipeline(
67           [ "lset", "key1", 0, "foo" ],
68           [ "hset", "key1", "field1", "foo" ],
69           [ "lset", "key2", 0, "bar", 1, "baz" ],
70           [ "hset", "key2", "field1", "bar", "field2", "baz" ]
71        );
72

SYNTAX for QUERY STRING

74       Several methods take a query string for an argument. The format of the
75       string is described below. In the context of sharing, the query
76       mechanism is beneficial for the shared-manager process. It is able to
77       perform the query where the data resides versus the client-process grep
78       locally involving lots of IPC.
79
80        o Basic demonstration
81
82          # query the hash stored at "some key"
83          @keys = $db->hkeys( "some key", "query string given here" );
84          @keys = $db->hkeys( "some key", "val =~ /pattern/" );
85
86          # query the top-level hash (H)oH
87          @keys = $db->hkeys( "query string given here" );
88          @keys = $db->hkeys( "key =~ /pattern/" );
89
90        o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
91        o Multiple expressions delimited by :AND or :OR, mixed case allowed
92
93          "key eq 'some key' :or (field > 5 :and field < 9)"
94          "key eq some key :or (field > 5 :and field < 9)"
95          "key =~ /pattern/i :And field =~ /pattern/i"   # HoH
96          "key =~ /pattern/i :And index =~ /pattern/i"   # HoA
97          "index eq foo baz :OR key !~ /pattern/i"       # e.g. 9 eq "foo baz"
98
99          * key   matches on primary keys in the hash (H)oH or (H)oA
100          * field matches on HoH->{key}{field} e.g. address
101          * index matches on HoA->{key}[index] e.g. 9
102
103        o Quoting is optional inside the string
104        o Primary keys (H)oH may have spaces, but not so for field_names
105
106          "key =~ /pattern/i :AND field eq 'foo bar'"    # address eq "foo bar"
107          "key =~ /pattern/i :AND field eq foo bar"      # address eq "foo bar"
108
109          "key =~ 'some key' :AND 'some_field' eq 'foo bar'"  # ok: some_field
110          "key =~ some key :AND some_field eq foo bar"
111
112          "key =~ 'some key' :AND 'some field' eq 'foo bar'"  # fail: some field
113          "key =~ some key :AND some field eq foo bar"
114
115       Examples.
116
117        # search capability key/val: =~ !~ eq ne lt le gt ge == != < <= > >=
118        # key/val means to match against actual key/val respectively
119
120        # a query made to a hash stored at "some key"
121        # note that "fieldNames" must not have spaces
122
123          @keys  = $db->hkeys(
124             "some key", "key eq some_field :or (val > 5 :and val < 9)"
125          );
126
127        # queries made to a list stored at "some key"
128
129          @pairs = $db->lpairs( "some key", "key >= 50 :AND val =~ /sun|moon/" );
130          @pairs = $db->lpairs( "some key", "val eq sun :OR val eq moon" );
131
132        # the key modifier is the only thing possible for top-level queries
133        # reason: value equals a hash or list reference containing 2nd-level data
134
135          @keys  = $db->hkeys( "key eq 'some key'" );
136          @keys  = $db->hkeys( "key eq some key" );
137
138          @keys  = $db->hkeys( "key =~ /$pattern/i" );
139          @keys  = $db->hkeys( "key !~ /$pattern/i" );
140
141          %pairs = $db->hpairs( "key == $number" );
142          %pairs = $db->hpairs( "key != $number" );
143          %pairs = $db->hpairs( "key <  $number :or key > $number" );
144          %pairs = $db->hpairs( "key <= $number" );
145          %pairs = $db->hpairs( "key >  $number" );
146          %pairs = $db->hpairs( "key >= $number" );
147
148          @vals  = $db->hvals( "key eq $string" );
149          @vals  = $db->hvals( "key ne $string with space" );
150          @vals  = $db->hvals( "key lt $string :or key =~ /$pat1|$pat2/" );
151          @vals  = $db->hvals( "key le $string :or key eq 'foo bar'" );
152          @vals  = $db->hvals( "key le $string :or key eq foo bar" );
153          @vals  = $db->hvals( "key gt $string" );
154          @vals  = $db->hvals( "key ge $string" );
155
156        # see select_aref and select_href below for db-like queries against
157        # the underlying Ho(A) and Ho(H) structures respectively
158

API DOCUMENTATION - DB

160   MCE::Shared::Minidb->new ()
161   MCE::Shared->minidb ()
162       Constructs an empty in-memory "HoH" and "HoA" key-store database
163       structure.
164
165        # non-shared or local construction for use by a single process
166
167        use MCE::Shared::Minidb;
168
169        $db = MCE::Shared::Minidb->new();
170
171        # construction for sharing with other threads and processes
172
173        use MCE::Shared;
174
175        $db = MCE::Shared->minidb();
176
177   dump ( "file.dat" )
178       Dumps the in-memory content to a file.
179
180        $db->dump( "content.dat" );
181
182   pipeline ( [ func1, @args ], [ func2, @args ], ... )
183       Combines multiple commands for the object to be processed serially. For
184       shared objects, the call is made atomically due to single IPC to the
185       shared-manager process. The "pipeline" method is fully
186       "wantarray"-aware and receives a list of commands and their arguments.
187       In scalar or list context, it returns data from the last command in the
188       pipeline.
189
190        @vals = $db->pipeline(                     # ( "bar", "baz" )
191           [ "hset", "some_key", "f1", "bar", "f2", "baz" ],
192           [ "hget", "some_key", "f1", "f2" ]
193        );
194
195        $len = $db->pipeline(                      # 2, same as $db->hlen("key2)
196           [ "hset", "some_key", "f1", "bar", "f2", "baz" ],
197           [ "hlen", "some_key" ]
198        );
199
200        $db->pipeline(
201           [ "lset", "key1", 0, "foo" ],
202           [ "hset", "key1", "field1", "foo" ],
203           [ "lset", "key2", 0, "bar", 1, "baz" ],
204           [ "hset", "key2", "field1", "bar", "field2", "baz" ]
205        );
206
207       Current API available since 1.809.
208
209   pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )
210       Same as "pipeline", but returns data for every command in the pipeline.
211
212        @vals = $db->pipeline_ex(                  # ( "bar", "baz" )
213           [ "hset", "key3", "field1", "bar" ],
214           [ "hset", "key3", "field2", "baz" ]
215        );
216
217        $chunk_size = 3;
218
219        $db->hset("some_key", chunk_id => 0);
220        $db->lassign("some_key", @ARGV);
221
222        while (1) {
223           ($chunk_id, @next) = $db->pipeline_ex(
224              [ "hincr",   "some_key", "chunk_id"     ],
225              [ "lsplice", "some_key", 0, $chunk_size ]
226           );
227
228           last unless @next;
229
230           ...
231        }
232
233       Current API available since 1.809.
234
235   restore ( "file.dat" )
236       Restores the in-memory content from a file.
237
238        $db->restore( "content.dat" );
239
240   select_aref ( ":hashes", "select string" )
241   select_href ( ":hashes", "select string" )
242       Returns a list containing "[ key, aref ]" pairs or "[ key, href ]"
243       pairs from the hash of hashes (HoH).
244
245       The "select_aref" and "select_href" methods take a select string
246       supporting field names and optionally sort modifiers. The syntax for
247       the query string, between ":WHERE" and ":ORDER BY", is the same as
248       described above.
249
250       The modifiers ":WHERE", ":AND", ":OR", "ORDER BY", "ASC", "DESC", and
251       "ALPHA" may be mixed case. e.g. ":Where"
252
253       HoH select string:
254
255        "f1 f2 f3 :WHERE f4 > 20 :AND key =~ /foo/ :ORDER BY f5 DESC ALPHA"
256        "f5 f1 f2 :WHERE fN > 40 :AND key =~ /bar/ :ORDER BY key ALPHA"
257        "f5 f1 f2 :WHERE fN > 40 :AND key =~ /bar/"
258        "f5 f1 f2"
259
260        * key matches on keys stored in the primary level hash (H)oH
261
262       HoH select synopsis:
263
264        @rows = $db->select_aref( ":hashes", "some_field :ORDER BY some_field" );
265        @rows = $db->select_aref( ":hashes", "f2 f6 f5 :ORDER BY f4" );
266
267        # $rows[0] = [ "key1", [ "f2_val", "f6_val", "f5_val" ] ]
268        # $rows[1] = [ "key2", [ "f2_val", "f6_val", "f5_val" ] ]
269        # $rows[2] = [ "key3", [ "f2_val", "f6_val", "f5_val" ] ]
270        # ...
271        # $rows[N] = [ "keyN", [ "f2_val", "f6_val", "f5_val" ] ]
272
273        @rows = $db->select_href( ":hashes", "some_field :ORDER BY some_field" );
274        @rows = $db->select_href( ":hashes", "f2 f6 f5 :ORDER BY f4" );
275
276        # $rows[0] = [ "key1", { f2 => "val", f6 => "val", f5 => "val" } ]
277        # $rows[1] = [ "key2", { f2 => "val", f6 => "val", f5 => "val" } ]
278        # $rows[2] = [ "key3", { f2 => "val", f6 => "val", f5 => "val" } ]
279        # ...
280        # $rows[N] = [ "keyN", { f2 => "val", f6 => "val", f5 => "val" } ]
281
282   select_aref ( ":lists", "select string" )
283   select_href ( ":lists", "select string" )
284       Returns a list containing "[ key, aref ]" pairs or "[ key, href ]"
285       pairs from the hash of lists (HoA).
286
287       The "select_aref" and "select_href" methods take a select string
288       supporting field indices and optionally sort modifiers. The syntax for
289       the query string, between ":WHERE" and ":ORDER BY", is the same as
290       described above.
291
292       The modifiers ":WHERE", ":AND", ":OR", "ORDER BY", "ASC", "DESC", and
293       "ALPHA" may be mixed case. e.g. ":Where"
294
295       HoA select string:
296
297        "17 15 11 :WHERE 12 > 20 :AND key =~ /foo/ :ORDER BY 10 DESC ALPHA"
298        "17 15 11 :WHERE 12 > 40 :AND key =~ /bar/ :ORDER BY key ALPHA"
299        "17 15 11 :WHERE 12 > 40 :AND key =~ /bar/"
300        "17 15 11"
301
302        * key matches on keys stored in the primary level hash (H)oA
303        * above, list indices are given as 17, 15, 11, 12, and 10
304        * the shorter form is allowed e.g. "4 > 20 :AND key =~ /baz/"
305
306       HoA select synopsis:
307
308        @rows = $db->select_aref( ":lists", "some_index :ORDER BY some_index" );
309        @rows = $db->select_aref( ":lists", "2 6 5 :ORDER BY 4" );
310
311        # $rows[0] = [ "key1", [ "2_val", "6_val", "5_val" ] ]
312        # $rows[1] = [ "key2", [ "2_val", "6_val", "5_val" ] ]
313        # $rows[2] = [ "key3", [ "2_val", "6_val", "5_val" ] ]
314        # ...
315        # $rows[N] = [ "keyN", [ "2_val", "6_val", "5_val" ] ]
316
317        @rows = $db->select_href( ":lists", "some_index :ORDER BY some_index" );
318        @rows = $db->select_href( ":lists", "2 6 5 :ORDER BY 4" );
319
320        # $rows[0] = [ "key1", { 2 => "val", 6 => "val", 5 => "val" } ]
321        # $rows[1] = [ "key2", { 2 => "val", 6 => "val", 5 => "val" } ]
322        # $rows[2] = [ "key3", { 2 => "val", 6 => "val", 5 => "val" } ]
323        # ...
324        # $rows[N] = [ "keyN", { 2 => "val", 6 => "val", 5 => "val" } ]
325

API DOCUMENTATION - HASHES ( HoH )

327   hassign ( key, field, value [, field, value, ... ] )
328       Clears the hash stored at key, then sets the value of a hash field and
329       returns its new value. Multiple field_value pairs may be set at once.
330       In that case, the number of fields is returned. This is equivalent to
331       "hclear", "hset".
332
333        $val = $db->hassign( "some_key", "field", "value" );
334        $len = $db->hassign( "some_key", "f1" => "val1", "f2" => "val2" );
335
336       API available since 1.007.
337
338   hclear ( key )
339       Removes all key-value pairs from the first level hash (H)oH when no
340       arguments are given. Otherwise, removes all field-value pairs stored at
341       key.
342
343        $db->hclear;
344        $db->hclear( "some_key" );
345
346   hdel ( key, field [, field, ... ] )
347       Deletes one or more hash fields. It returns the value associated with
348       the field if a single field is given. Otherwise, it returns the number
349       of fields actually removed from the hash stored at key. A field which
350       does not exist in the hash is not counted.
351
352        $val = $db->hdel( "some_key", "some_field" );
353        $cnt = $db->hdel( "some_key", "field1", "field2" );
354
355   hdel ( key )
356       Deletes and returns the "MCE::Shared::Hash" object stored at key or
357       "undef" if the key does not exists in the first level hash (H)oH.
358
359        $ha_obj = $db->hdel( "some_key" );
360
361   hexists ( key, field [, field, ... ] )
362       Determines if a hash field exists. For multiple fields, a truth value
363       is returned only if all given fields exist in the hash stored at key.
364
365        if ( $db->hexists( "some_key", "some_field" ) ) { ... }
366        if ( $db->hexists( "some_key", "f1", "f5" ) ) { ... }
367
368   hexists ( key )
369       Determines if a key exists in the first level hash (H)oH.
370
371        if ( $db->hexists( "some_key" ) ) { ... }
372
373   hget ( key, field [, field, ... ] )
374       Gets the values of all given hash fields. The "undef" value is returned
375       for fields which do not exists in the hash stored at key. Likewise, the
376       "undef" value is returned if the key does not exists in the first level
377       hash (H)oH.
378
379        $val = $db->hget( "some_key", "field" );
380
381        ( $val1, $val2 ) = $db->hget( "some_key", "field1", "field2" );
382
383   hget ( key )
384       Gets the "MCE::Shared::Hash" object for the hash stored at key or
385       "undef" if the key does not exists in the first level hash (H)oH.
386
387        $ha_obj = $db->hget( "some_key" );
388
389   hkeys ( key, [ field [, field, ... ] ] )
390       Returns keys stored in the first level hash (H)oH when no arguments are
391       given.  Otherwise, returns the given fields in the hash stored at key.
392       Fields that do not exist will have the "undef" value. In scalar
393       context, returns the size of the object, either the hash stored at key
394       or the first level hash.
395
396        @keys   = $db->hkeys;
397        @fields = $db->hkeys( "some_key" );
398        @fields = $db->hkeys( "some_key", "field1", "field2" );
399        $len    = $db->hkeys( "some_key" );
400        $len    = $db->hkeys;
401
402   hkeys ( key, "query string" )
403       Returns only fields stored at key that match the given criteria. It
404       returns an empty list if the search found nothing. The syntax for the
405       "query string" is described above. In scalar context, returns the size
406       of the resulting list.
407
408        @keys = $db->hkeys( "some_key", "val eq some_value" );
409        @keys = $db->hkeys( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
410        @keys = $db->hkeys( "some_key", "val eq sun :OR val eq moon );
411        $len  = $db->hkeys( "some_key", "key =~ /$pattern/" );
412
413   hkeys ( "query string" )
414       For the one argument form, the search is applied to keys stored in the
415       primary hash only (H)oH. Therefore, the "key" modifier is the only
416       thing possible if wanting any result.
417
418        @keys = $db->hkeys( "key =~ /$pattern/" );
419        $len  = $db->hkeys( "key =~ /$pattern/" );
420
421   hlen ( key [, field ] )
422       Returns the size of the first level hash (H)oH when no arguments are
423       given.  For the given key, returns the size of hash stored at key or
424       optionally, the length of the value stored at key-field. It returns the
425       "undef" value if either the given key or given field does not exists.
426
427        $len = $db->hlen;
428        $len = $db->hlen( $key );
429        $len = $db->hlen( $key, $field );
430
431   hpairs ( key, [ field [, field, ... ] ] )
432       Returns key-value pairs stored in the first level hash (H)oH when no
433       arguments are given. Otherwise, returns field-value pairs for the given
434       fields in the hash stored at key. Fields that do not exist will have
435       the "undef" value. In scalar context, returns the size of the object,
436       either the hash stored at key or the first level hash.
437
438        @pairs = $db->hpairs;                 # ( key => href, ... )
439        @pairs = $db->hpairs( "some_key" );   # ( field => value, ... )
440        @pairs = $db->hpairs( "some_key", "field1", "field2" );
441        $len   = $db->hpairs( "some_key" );
442        $len   = $db->hpairs;
443
444   hpairs ( key, "query string" )
445       Returns only field-value pairs stored at key that match the given
446       criteria.  It returns an empty list if the search found nothing. The
447       syntax for the "query string" is described above. In scalar context,
448       returns the size of the resulting list.
449
450        @pairs = $db->hpairs( "some_key", "val eq some_value" );
451        @pairs = $db->hpairs( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
452        @pairs = $db->hpairs( "some_key", "val eq sun :OR val eq moon" );
453        $len   = $db->hpairs( "some_key", "key =~ /$pattern/" );
454
455   hpairs ( "query string" )
456       For the one argument form, the search is applied to keys stored in the
457       primary hash only (H)oH. Therefore, the "key" modifier is the only
458       thing possible if wanting any result.
459
460        @keys = $db->hpairs( "key =~ /$pattern/" );
461        $len  = $db->hpairs( "key =~ /$pattern/" );
462
463   hset ( key, field, value [, field, value, ... ] )
464       Sets the value of a hash field and returns its new value. Multiple
465       field_value pairs may be set at once. In that case, the number of
466       fields stored at key is returned.
467
468        $val = $db->hset( "some_key", "field", "value" );
469        $len = $db->hset( "some_key", "f1" => "val1", "f2" => "val2" );
470
471   hsetnx ( key, field, value )
472       Sets the value of a hash field, only if the field does not exist.
473       Returns a 1 for new field or 0 if the field already exists and no
474       operation was performed.
475
476        $ret = $db->hsetnx( "some_key", "field", "value" );
477
478       Current API available since 1.872.
479
480   hshift
481       Removes and returns the first key-value pair or value in scalar context
482       from the first-level hash (H)oH. If the "HASH" is empty, returns the
483       undefined value.
484
485        ( $key, $href ) = $db->hshift;
486
487        $href = $db->hshift;
488
489   hsort ( "BY key [ ASC | DESC ] [ ALPHA ]" )
490   hsort ( "BY field [ ASC | DESC ] [ ALPHA ]" )
491       Returns sorted keys from the first level hash (H)oH, leaving the
492       elements intact. In void context, sorts the first level hash in-place.
493       Sorting is numeric by default.
494
495        @keys = $db->hsort( "BY key" );
496        @keys = $db->hsort( "BY some_field" );
497
498        $db->hsort( "BY key" );
499        $db->hsort( "BY some_field" );
500
501       If the keys or field values contain string values and you want to sort
502       them lexicographically, specify the "ALPHA" modifier.
503
504        @keys = $db->hsort( "BY key ALPHA" );
505        @keys = $db->hsort( "BY some_field ALPHA" );
506
507        $db->hsort( "BY key ALPHA" );
508        $db->hsort( "BY some_field ALPHA" );
509
510       The default is "ASC" for sorting the elements from small to large. In
511       order to sort from large to small, specify the "DESC" modifier.
512
513        @keys = $db->hsort( "BY key DESC ALPHA" );
514        @keys = $db->hsort( "BY some_field DESC ALPHA" );
515
516        $db->hsort( "BY key DESC ALPHA" );
517        $db->hsort( "BY some_field DESC ALPHA" );
518
519   hvals ( key, [ field [, field, ... ] ] )
520       Returns values stored in the first level hash (H)oH when no arguments
521       are given.  Otherwise, returns values for the given fields in the hash
522       stored at key. Fields that do not exist will have the "undef" value. In
523       scalar context, returns the size of the object, either the hash stored
524       at key or the first level hash.
525
526        @hrefs = $db->hvals;
527        @vals  = $db->hvals( "some_key" );
528        @vals  = $db->hvals( "some_key", "field1", "field2" );
529        $len   = $db->hvals( "some_key" );
530        $len   = $db->hvals;
531
532   hvals ( key, "query string" )
533       Returns only values stored at key that match the given criteria. It
534       returns an empty list if the search found nothing. The syntax for the
535       "query string" is described above. In scalar context, returns the size
536       of the resulting list.
537
538        @vals = $db->hvals( "some_key", "val eq some_value" );
539        @vals = $db->hvals( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
540        @vals = $db->hvals( "some_key", "val eq sun :OR val eq moon" );
541        $len  = $db->hvals( "some_key", "key =~ /$pattern/" );
542
543   hvals ( "query string" )
544       For the one argument form, the search is applied to keys stored in the
545       primary hash only (H)oH. Therefore, the "key" modifier is the only
546       thing possible if wanting any result.
547
548        @keys = $db->hvals( "key =~ /$pattern/" );
549        $len  = $db->hvals( "key =~ /$pattern/" );
550

SUGAR METHODS - HASHES ( HoH )

552       This module is equipped with sugar methods to not have to call "set"
553       and "get" explicitly. In shared context, the benefit is atomicity and
554       reduction in inter-process communication.
555
556   happend ( key, field, string )
557       Appends a value to key-field and returns its new length.
558
559        $len = $db->happend( $key, $field, "foo" );
560
561   hdecr ( key, field )
562       Decrements the value of key-field by one and returns its new value.
563
564        $num = $db->hdecr( $key, $field );
565
566   hdecrby ( key, field, number )
567       Decrements the value of key-field by the given number and returns its
568       new value.
569
570        $num = $db->hdecrby( $key, $field, 2 );
571
572   hgetdecr ( key, field )
573       Decrements the value of key-field by one and returns its old value.
574
575        $old = $db->hgetdecr( $key, $field );
576
577   hgetincr ( key, field )
578       Increments the value of key-field by one and returns its old value.
579
580        $old = $db->hgetincr( $key, $field );
581
582   hgetset ( key, field, value )
583       Sets the value of key-field and returns its old value.
584
585        $old = $db->hgetset( $key, $field, "baz" );
586
587   hincr ( key, field )
588       Increments the value of key-field by one and returns its new value.
589
590        $num = $db->hincr( $key, $field );
591
592   hincrby ( key, field, number )
593       Increments the value of key-field by the given number and returns its
594       new value.
595
596        $num = $db->hincrby( $key, $field, 2 );
597

API DOCUMENTATION - LISTS ( HoA )

599   lassign ( key, value [, value, ... ] )
600       Clears the list stored at key, then prepends one or multiple values and
601       returns the new length. This is equivalent to "lclear", "lpush".
602
603        $len = $db->lassign( "some_key", "val1", "val2" );
604
605       API available since 1.007.
606
607   lclear ( key )
608       Removes all key-value pairs from the first level hash (H)oA when no
609       arguments are given. Otherwise, removes all elements from the list
610       stored at key.
611
612        $db->lclear;
613        $db->lclear( "some_key" );
614
615   ldel ( key, index [, index, ... ] )
616       Deletes one or more elements by their indices. It returns the value
617       associated with the index if a single index is given. Otherwise, it
618       returns the number of elements actually removed from the list stored at
619       key. An index which does not exists in the list is not counted.
620
621        $val = $db->ldel( "some_key", 20 );
622        $cnt = $db->ldel( "some_key", 0, 1 );
623
624   ldel ( key )
625       Deletes and returns the "MCE::Shared::Array" object stored at key or
626       "undef" if the key does not exists in the first level hash (H)oA.
627
628        $ar_obj = $db->ldel( "some_key" );
629
630   lexists ( key, index [, index, ... ] )
631       Determines if elements by their indices exist in the list. For multiple
632       indices, a truth value is returned only if all given indices exist in
633       the list stored at key. The behavior is strongly tied to the use of
634       delete on lists.
635
636        $db->lset( "some_key", 0, "value0" );
637        $db->lset( "some_key", 1, "value1" );
638        $db->lset( "some_key", 2, "value2" );
639        $db->lset( "some_key", 3, "value3" );
640
641        $db->lexists( "some_key", 2 );     # True
642        $db->lexists( "some_key", 2, 3 );  # True
643        $db->ldel   ( "some_key", 2 );     # value2
644
645        $db->lexists( "some_key", 2 );     # False
646        $db->lexists( "some_key", 2, 3 );  # False
647        $db->lexists( "some_key", 3 );     # True
648
649   lexists ( key )
650       Determines if a key exists in the first level hash (H)oA.
651
652        if ( $db->lexists( "some_key" ) ) { ... }
653
654   lget ( key, index [, index, ... ] )
655       Gets the values of all given list indices. The "undef" value is
656       returned for indices which do not exists in the list stored at key.
657       Likewise, the "undef" value is returned if the key does not exists in
658       the first level hash (H)oA.
659
660        $val = $db->lget( "some_key", 20 );
661
662        ( $val1, $val2 ) = $db->lget( "some_key", 0, 1 );
663
664   lget ( key )
665       Gets the "MCE::Shared::Array" object for the list stored at key or
666       "undef" if the key does not exists in the first level hash (H)oA.
667
668        $ar_obj = $db->lget( "some_key" );
669
670   lkeys ( key, [ index [, index, ... ] ] )
671       Returns keys stored in the first level hash (H)oA when no arguments are
672       given.  Otherwise, returns the given indices in the list stored at key.
673       Indices that do not exist will have the "undef" value. In scalar
674       context, returns the size of the object, either the list stored at key
675       or the first level hash.
676
677        @keys    = $db->lkeys;
678        @indices = $db->lkeys( "some_key" );
679        @indices = $db->lkeys( "some_key", 0, 1 );
680        $len     = $db->lkeys( "some_key" );
681        $len     = $db->lkeys;
682
683   lkeys ( key, "query string" )
684       Returns only indices stored at key that match the given criteria. It
685       returns an empty list if the search found nothing. The syntax for the
686       "query string" is described above. In scalar context, returns the size
687       of the resulting list.
688
689        @keys = $db->lkeys( "some_key", "val eq some_value" );
690        @keys = $db->lkeys( "some_key", "key >= 50 :AND val =~ /sun|moon/" );
691        @keys = $db->lkeys( "some_key", "val eq sun :OR val eq moon" );
692        $len  = $db->lkeys( "some_key", "key =~ /$pattern/" );
693
694   lkeys ( "query string" )
695       For the one argument form, the search is applied to keys stored in the
696       primary hash only (H)oA. Therefore, the "key" modifier is the only
697       thing possible if wanting any result.
698
699        @keys = $db->lkeys( "key =~ /$pattern/" );
700        $len  = $db->lkeys( "key =~ /$pattern/" );
701
702   llen ( key [, index ] )
703       Returns the size of the first level hash (H)oA when no arguments are
704       given.  For the given index, returns the size of list stored at key or
705       optionally, the length of the value stored at key-index. It returns the
706       "undef" value if either the given key or given index does not exists.
707
708        $len = $db->llen;
709        $len = $db->llen( $key );
710        $len = $db->llen( $key, 0 );
711
712   lpairs ( key, [ index [, index, ... ] ] )
713       Returns key-value pairs stored in the first level hash (H)oA when no
714       arguments are given. Otherwise, returns index-value pairs for the given
715       indices in the list stored at key. Indices that do not exist will have
716       the "undef" value.  In scalar context, returns the size of the object,
717       either the list stored at key or the first level hash.
718
719        @pairs = $db->lpairs;                 # ( key => aref, ... )
720        @pairs = $db->lpairs( "some_key" );   # ( index => value, ... )
721        @pairs = $db->lpairs( "some_key", 0, 1 );
722        $len   = $db->lpairs( "some_key" );
723        $len   = $db->lpairs;
724
725   lpairs ( key, "query string" )
726       Returns only index-value pairs stored at key that match the given
727       criteria.  It returns an empty list if the search found nothing. The
728       syntax for the "query string" is described above. In scalar context,
729       returns the size of the resulting list.
730
731        @pairs = $db->lpairs( "some_key", "val eq some_value" );
732        @pairs = $db->lpairs( "some_key", "key >= 50 :AND val =~ /sun|moon/" );
733        @pairs = $db->lpairs( "some_key", "val eq sun :OR val eq moon" );
734        $len   = $db->lpairs( "some_key", "key =~ /$pattern/" );
735
736   lpairs ( "query string" )
737       For the one argument form, the search is applied to keys stored in the
738       primary hash only (H)oA. Therefore, the "key" modifier is the only
739       thing possible if wanting any result.
740
741        @keys = $db->lpairs( "key =~ /$pattern/" );
742        $len  = $db->lpairs( "key =~ /$pattern/" );
743
744   lpop ( key )
745       Removes and returns the first value of the list stored at key. If there
746       are no elements in the list, returns the undefined value.
747
748        $val = $db->lpop( $key );
749
750   lpush ( key, value [, value, ... ] )
751       Prepends one or multiple values to the head of the list stored at key
752       and returns the new length.
753
754        $len = $db->lpush( "some_key", "val1", "val2" );
755
756   lrange ( key, start, stop )
757       Returns the specified elements of the list stored at key. The offsets
758       "start" and "stop" can also be negative numbers indicating offsets
759       starting at the end of the list.
760
761       An empty list is returned if "start" is larger than the end of the
762       list.  "stop" is set to the last index of the list if larger than the
763       actual end of the list.
764
765        @list = $db->lrange( "some_key", 20, 29 );
766        @list = $db->lrange( "some_key", -4, -1 );
767
768   lset ( key, index, value [, index, value, ... ] )
769       Sets the value of an element in a list by its index and returns its new
770       value.  Multiple index_value pairs may be set all at once. In that
771       case, the length of the list is returned.
772
773        $val = $db->lset( "some_key", 2, "value" );
774        $len = $db->lset( "some_key", 0 => "val1", 1 => "val2" );
775
776   lshift
777       Removes and returns the first key-value pair or value in scalar context
778       from the first-level hash (H)oA. If the "HASH" is empty, returns the
779       undefined value. See "lpop" to shift the first value of the list stored
780       at key.
781
782        ( $key, $aref ) = $db->lshift;
783
784        $aref = $db->lshift;
785
786   lsort ( "BY key [ ASC | DESC ] [ ALPHA ]" )
787   lsort ( "BY index [ ASC | DESC ] [ ALPHA ]" )
788       Returns sorted keys from the first level hash (H)oA, leaving the
789       elements intact. In void context, sorts the first level hash in-place.
790       Sorting is numeric by default.
791
792        @keys = $db->lsort( "BY key" );
793        @keys = $db->lsort( "BY some_index" );
794
795        $db->lsort( "BY key" );
796        $db->lsort( "BY some_index" );
797
798       If the keys or field values given by index contain string values and
799       you want to sort them lexicographically, specify the "ALPHA" modifier.
800
801        @keys = $db->lsort( "BY key ALPHA" );
802        @keys = $db->lsort( "BY some_index ALPHA" );
803
804        $db->lsort( "BY key ALPHA" );
805        $db->lsort( "BY some_index ALPHA" );
806
807       The default is "ASC" for sorting the elements from small to large. In
808       order to sort from large to small, specify the "DESC" modifier.
809
810        @keys = $db->lsort( "BY key DESC ALPHA" );
811        @keys = $db->lsort( "BY some_index DESC ALPHA" );
812
813        $db->lsort( "BY key DESC ALPHA" );
814        $db->lsort( "BY some_index DESC ALPHA" );
815
816   lsort ( key, "BY key [ ASC | DESC ] [ ALPHA ]" )
817   lsort ( key, "BY val [ ASC | DESC ] [ ALPHA ]" )
818       The two argument form has similar functionality. Here, sorting is
819       applied to the list stored at key. For example, the following reverses
820       the list stored at the given key. The "BY key" modifier refers to the
821       indices in the list and not the values.
822
823        $db->lsort( "some_key", "BY key DESC" );
824
825   lsplice ( key, offset [, length [, list ] ] )
826       Removes the elements designated by "offset" and "length" from the array
827       stored at key, and replaces them with the elements of "list", if any.
828       The behavior is similar to the Perl "splice" function.
829
830        @items = $db->lsplice( "some_key", 20, 2, @list );
831        @items = $db->lsplice( "some_key", 20, 2 );
832        @items = $db->lsplice( "some_key", 20 );
833
834   lvals ( key, [ index [, index, ... ] ] )
835       Returns values stored in the first level hash (H)oA when no arguments
836       are given. Otherwise, returns values for the given indices in the list
837       stored at key. Indices that do not exist will have the "undef" value.
838       In scalar context, returns the size of the object, either the list
839       stored at key or the first level hash.
840
841        @arefs = $db->lvals;
842        @vals  = $db->lvals( "some_key" );
843        @vals  = $db->lvals( "some_key", 0, 1 );
844        $len   = $db->lvals( "some_key" );
845        $len   = $db->lvals;
846
847   lvals ( key, "query string" )
848       Returns only values stored at key that match the given criteria. It
849       returns an empty list if the search found nothing. The syntax for the
850       "query string" is described above. In scalar context, returns the size
851       of the resulting list.
852
853        @keys = $db->lvals( "some_key", "val eq some_value" );
854        @keys = $db->lvals( "some_key", "key >= 50 :AND val =~ /sun|moon/" );
855        @keys = $db->lvals( "some_key", "val eq sun :OR val eq moon" );
856        $len  = $db->lvals( "some_key", "key =~ /$pattern/" );
857
858   lvals ( "query string" )
859       For the one argument form, the search is applied to keys stored in the
860       primary hash only (H)oA. Therefore, the "key" modifier is the only
861       thing possible if wanting any result.
862
863        @keys = $db->lvals( "key =~ /$pattern/" );
864        $len  = $db->lvals( "key =~ /$pattern/" );
865
866   rpop ( key )
867       Removes and returns the last value of the list stored at key. If there
868       are no elements in the list, returns the undefined value.
869
870        $val = $db->rpop( $key );
871
872   rpush ( key, value [, value, ... ] )
873       Appends one or multiple values to the tail of the list stored at key
874       and returns the new length.
875
876        $len = $db->rpush( "some_key", "val1", "val2" );
877

SUGAR METHODS - LISTS ( HoA )

879       This module is equipped with sugar methods to not have to call "set"
880       and "get" explicitly. In shared context, the benefit is atomicity and
881       reduction in inter-process communication.
882
883   lappend ( key, index, string )
884       Appends a value to key-index and returns its new length.
885
886        $len = $db->lappend( $key, 0, "foo" );
887
888   ldecr ( key, index )
889       Decrements the value of key-index by one and returns its new value.
890
891        $num = $db->ldecr( $key, 0 );
892
893   ldecrby ( key, index, number )
894       Decrements the value of key-index by the given number and returns its
895       new value.
896
897        $num = $db->ldecrby( $key, 0, 2 );
898
899   lgetdecr ( key, index )
900       Decrements the value of key-index by one and returns its old value.
901
902        $old = $db->lgetdecr( $key, 0 );
903
904   lgetincr ( key, index )
905       Increments the value of key-index by one and returns its old value.
906
907        $old = $db->lgetincr( $key, 0 );
908
909   lgetset ( key, index, value )
910       Sets the value of key-index and returns its old value.
911
912        $old = $db->lgetset( $key, 0, "baz" );
913
914   lincr ( key, index )
915       Increments the value of key-index by one and returns its new value.
916
917        $num = $db->lincr( $key, 0 );
918
919   lincrby ( key, index, number )
920       Increments the value of key-index by the given number and returns its
921       new value.
922
923        $num = $db->lincrby( $key, 0, 2 );
924

CREDITS

926       The implementation is inspired by various Redis Hash/List primitives at
927       <https://redis.io/commands>.
928

INDEX

930       MCE, MCE::Hobo, MCE::Shared
931

AUTHOR

933       Mario E. Roy, <marioeroy AT gmail DOT com>
934
935
936
937perl v5.38.0                      2023-09-14            MCE::Shared::Minidb(3)
Impressum