Class: DBM

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
dbm.c

Constant Summary collapse

READER =

Indicates that dbm_open() should open the database in read-only mode

INT2FIX(O_RDONLY|RUBY_DBM_RW_BIT)
WRITER =

Indicates that dbm_open() should open the database in read/write mode

INT2FIX(O_RDWR|RUBY_DBM_RW_BIT)
WRCREAT =

Indicates that dbm_open() should open the database in read/write mode, and create it if it does not already exist

INT2FIX(O_RDWR|O_CREAT|RUBY_DBM_RW_BIT)
NEWDB =

Indicates that dbm_open() should open the database in read/write mode, create it if it does not already exist, and delete all contents if it does already exist.

INT2FIX(O_RDWR|O_CREAT|O_TRUNC|RUBY_DBM_RW_BIT)
VERSION =
  • “ndbm (4.3BSD)”

  • “Berkeley DB 4.8.30: (April 9, 2010)”

  • “Berkeley DB (unknown)” (4.4BSD, maybe)

  • “GDBM version 1.8.3. 10/15/2002 (built Jul 1 2011 12:32:45)”

  • “QDBM 1.8.78”

Identifies ndbm library version.

Examples

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#new(filename[, mode[, flags]]) ⇒ Object

Open a dbm database with the specified name, which can include a directory path. Any file extensions needed will be supplied automatically by the dbm library. For example, Berkeley DB appends ‘.db’, and GNU gdbm uses two physical files with extensions ‘.dir’ and ‘.pag’.

The mode should be an integer, as for Unix chmod.

Flags should be one of READER, WRITER, WRCREAT or NEWDB.



145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
# File 'dbm.c', line 145

static VALUE
fdbm_initialize(int argc, VALUE *argv, VALUE obj)
{
    volatile VALUE file;
    VALUE vmode, vflags;
    DBM *dbm;
    struct dbmdata *dbmp;
    int mode, flags = 0;

    if (rb_scan_args(argc, argv, "12", &file, &vmode, &vflags) == 1) {
  mode = 0666;   /* default value */
    }
    else if (NIL_P(vmode)) {
  mode = -1;   /* return nil if DB not exist */
    }
    else {
  mode = NUM2INT(vmode);
    }

    if (!NIL_P(vflags))
        flags = NUM2INT(vflags);

    FilePathValue(file);

    /*
     * Note:
     * gdbm 1.10 works with O_CLOEXEC.  gdbm 1.9.1 silently ignore it.
     */
#ifndef O_CLOEXEC
#   define O_CLOEXEC 0
#endif

    if (flags & RUBY_DBM_RW_BIT) {
        flags &= ~RUBY_DBM_RW_BIT;
        dbm = dbm_open(RSTRING_PTR(file), flags|O_CLOEXEC, mode);
    }
    else {
        dbm = 0;
        if (mode >= 0) {
            dbm = dbm_open(RSTRING_PTR(file), O_RDWR|O_CREAT|O_CLOEXEC, mode);
        }
        if (!dbm) {
            dbm = dbm_open(RSTRING_PTR(file), O_RDWR|O_CLOEXEC, 0);
        }
        if (!dbm) {
            dbm = dbm_open(RSTRING_PTR(file), O_RDONLY|O_CLOEXEC, 0);
        }
    }

    if (dbm) {
    /*
     * History of dbm_pagfno() and dbm_dirfno() in ndbm and its compatibles.
     * (dbm_pagfno() and dbm_dirfno() is not standardized.)
     *
     * 1986: 4.3BSD provides ndbm.
     *       It provides dbm_pagfno() and dbm_dirfno() as macros.
     * 1991: gdbm-1.5 provides them as functions.
     *       They returns a same descriptor.
     *       (Earlier releases may have the functions too.)
     * 1991: Net/2 provides Berkeley DB.
     *       It doesn't provide dbm_pagfno() and dbm_dirfno().
     * 1992: 4.4BSD Alpha provides Berkeley DB with dbm_dirfno() as a function.
     *       dbm_pagfno() is a macro as DBM_PAGFNO_NOT_AVAILABLE.
     * 1997: Berkeley DB 2.0 is released by Sleepycat Software, Inc.
     *       It defines dbm_pagfno() and dbm_dirfno() as macros.
     * 2011: gdbm-1.9 creates a separate dir file.
     *       dbm_pagfno() and dbm_dirfno() returns different descriptors.
     */
#if defined(HAVE_DBM_PAGFNO)
        rb_fd_fix_cloexec(dbm_pagfno(dbm));
#endif
#if defined(HAVE_DBM_DIRFNO)
        rb_fd_fix_cloexec(dbm_dirfno(dbm));
#endif

#if defined(RUBYDBM_DB_HEADER) && defined(HAVE_TYPE_DBC)
    /* Disable Berkeley DB error messages such as:
     * DB->put: attempt to modify a read-only database */
        ((DBC*)dbm)->dbp->set_errfile(((DBC*)dbm)->dbp, NULL);
#endif
    }

    if (!dbm) {
  if (mode == -1) return Qnil;
  rb_sys_fail_str(file);
    }

    dbmp = ALLOC(struct dbmdata);
    DATA_PTR(obj) = dbmp;
    dbmp->di_dbm = dbm;
    dbmp->di_size = -1;

    return obj;
}

Class Method Details

.open(filename[, mode[, flags]]) ⇒ Object .open(filename[, mode[, flags]]) {|dbm| ... } ⇒ Object

Open a dbm database and yields it if a block is given. See also DBM.new.

Overloads:

  • .open(filename[, mode[, flags]]) {|dbm| ... } ⇒ Object

    Yields:

    • (dbm)


248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
# File 'dbm.c', line 248

static VALUE
fdbm_s_open(int argc, VALUE *argv, VALUE klass)
{
    VALUE obj = fdbm_alloc(klass);

    if (NIL_P(fdbm_initialize(argc, argv, obj))) {
  return Qnil;
    }

    if (rb_block_given_p()) {
        return rb_ensure(rb_yield, obj, fdbm_close, obj);
    }

    return obj;
}

Instance Method Details

#[](key) ⇒ nil

Return a value from the database by locating the key string provided. If the key is not found, returns nil.

Returns:

  • (nil)


299
300
301
302
303
# File 'dbm.c', line 299

static VALUE
fdbm_aref(VALUE obj, VALUE keystr)
{
    return fdbm_fetch(obj, keystr, Qnil);
}

#store(key, value) ⇒ Object #[]=(key) ⇒ Object

Stores the specified string value in the database, indexed via the string key provided.



651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
# File 'dbm.c', line 651

static VALUE
fdbm_store(VALUE obj, VALUE keystr, VALUE valstr)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;

    fdbm_modify(obj);
    keystr = rb_obj_as_string(keystr);
    valstr = rb_obj_as_string(valstr);

    key.dptr = RSTRING_PTR(keystr);
    key.dsize = RSTRING_DSIZE(keystr);

    val.dptr = RSTRING_PTR(valstr);
    val.dsize = RSTRING_DSIZE(valstr);

    GetDBM2(obj, dbmp, dbm);
    dbmp->di_size = -1;
    if (dbm_store(dbm, key, val, DBM_REPLACE)) {
  dbm_clearerr(dbm);
  if (errno == EPERM) rb_sys_fail(0);
  rb_raise(rb_eDBMError, "dbm_store failed");
    }

    return valstr;
}

#clearObject

Deletes all data from the database.



551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
# File 'dbm.c', line 551

static VALUE
fdbm_clear(VALUE obj)
{
    datum key;
    struct dbmdata *dbmp;
    DBM *dbm;

    fdbm_modify(obj);
    GetDBM2(obj, dbmp, dbm);
    dbmp->di_size = -1;
    while (key = dbm_firstkey(dbm), key.dptr) {
  if (dbm_delete(dbm, key)) {
      rb_raise(rb_eDBMError, "dbm_delete failed");
  }
    }
    dbmp->di_size = 0;

    return obj;
}

#closeObject

Closes the database.



94
95
96
97
98
99
100
101
102
103
104
# File 'dbm.c', line 94

static VALUE
fdbm_close(VALUE obj)
{
    struct dbmdata *dbmp;

    GetDBM(obj, dbmp);
    dbm_close(dbmp->di_dbm);
    dbmp->di_dbm = 0;

    return Qnil;
}

#closed?Boolean

Returns true if the database is closed, false otherwise.

Returns:

  • (Boolean)

Returns:

  • (Boolean)


112
113
114
115
116
117
118
119
120
121
122
123
124
# File 'dbm.c', line 112

static VALUE
fdbm_closed(VALUE obj)
{
    struct dbmdata *dbmp;

    TypedData_Get_Struct(obj, struct dbmdata, &dbm_type, dbmp);
    if (dbmp == 0)
  return Qtrue;
    if (dbmp->di_dbm == 0)
  return Qtrue;

    return Qfalse;
}

#delete(key) ⇒ Object

Deletes an entry from the database.



427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
# File 'dbm.c', line 427

static VALUE
fdbm_delete(VALUE obj, VALUE keystr)
{
    datum key, value;
    struct dbmdata *dbmp;
    DBM *dbm;
    VALUE valstr;
    long len;

    fdbm_modify(obj);
    ExportStringValue(keystr);
    len = RSTRING_LEN(keystr);
    if (TOO_LONG(len)) goto not_found;
    key.dptr = RSTRING_PTR(keystr);
    key.dsize = (DSIZE_TYPE)len;

    GetDBM2(obj, dbmp, dbm);

    value = dbm_fetch(dbm, key);
    if (value.dptr == 0) {
      not_found:
  if (rb_block_given_p()) return rb_yield(keystr);
  return Qnil;
    }

    /* need to save value before dbm_delete() */
    valstr = rb_tainted_str_new(value.dptr, value.dsize);

    if (dbm_delete(dbm, key)) {
  dbmp->di_size = -1;
  rb_raise(rb_eDBMError, "dbm_delete failed");
    }
    else if (dbmp->di_size >= 0) {
  dbmp->di_size--;
    }
    return valstr;
}

#reject! {|key, value| ... } ⇒ self #delete_if {|key, value| ... } ⇒ self

Deletes all entries for which the code block returns true. Returns self.

Overloads:

  • #reject! {|key, value| ... } ⇒ self

    Yields:

    Returns:

    • (self)
  • #delete_if {|key, value| ... } ⇒ self

    Yields:

    Returns:

    • (self)


503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
# File 'dbm.c', line 503

static VALUE
fdbm_delete_if(VALUE obj)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    VALUE keystr, valstr;
    VALUE ret, ary = rb_ary_tmp_new(0);
    int status = 0;
    long i, n;

    fdbm_modify(obj);
    GetDBM2(obj, dbmp, dbm);
    n = dbmp->di_size;
    dbmp->di_size = -1;

    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  val = dbm_fetch(dbm, key);
  keystr = rb_tainted_str_new(key.dptr, key.dsize);
  OBJ_FREEZE(keystr);
  valstr = rb_tainted_str_new(val.dptr, val.dsize);
        ret = rb_protect(rb_yield, rb_assoc_new(rb_str_dup(keystr), valstr), &status);
        if (status != 0) break;
  if (RTEST(ret)) rb_ary_push(ary, keystr);
  GetDBM2(obj, dbmp, dbm);
    }

    for (i = 0; i < RARRAY_LEN(ary); i++) {
  keystr = RARRAY_AREF(ary, i);
  key.dptr = RSTRING_PTR(keystr);
  key.dsize = (DSIZE_TYPE)RSTRING_LEN(keystr);
  if (dbm_delete(dbm, key)) {
      rb_raise(rb_eDBMError, "dbm_delete failed");
  }
    }
    if (status) rb_jump_tag(status);
    if (n > 0) dbmp->di_size = n - RARRAY_LEN(ary);
    rb_ary_clear(ary);

    return obj;
}

#each_pair {|key, value| ... } ⇒ self

Calls the block once for each [key, value] pair in the database. Returns self.

Yields:

Returns:

  • (self)


787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
# File 'dbm.c', line 787

static VALUE
fdbm_each_pair(VALUE obj)
{
    datum key, val;
    DBM *dbm;
    struct dbmdata *dbmp;
    VALUE keystr, valstr;

    RETURN_ENUMERATOR(obj, 0, 0);

    GetDBM2(obj, dbmp, dbm);

    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  val = dbm_fetch(dbm, key);
  keystr = rb_tainted_str_new(key.dptr, key.dsize);
  valstr = rb_tainted_str_new(val.dptr, val.dsize);
  rb_yield(rb_assoc_new(keystr, valstr));
  GetDBM2(obj, dbmp, dbm);
    }

    return obj;
}

#each_key {|key| ... } ⇒ self

Calls the block once for each key string in the database. Returns self.

Yields:

Returns:

  • (self)


763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
# File 'dbm.c', line 763

static VALUE
fdbm_each_key(VALUE obj)
{
    datum key;
    struct dbmdata *dbmp;
    DBM *dbm;

    RETURN_ENUMERATOR(obj, 0, 0);

    GetDBM2(obj, dbmp, dbm);
    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  rb_yield(rb_tainted_str_new(key.dptr, key.dsize));
  GetDBM2(obj, dbmp, dbm);
    }
    return obj;
}

#each_pair {|key, value| ... } ⇒ self

Calls the block once for each [key, value] pair in the database. Returns self.

Yields:

Returns:

  • (self)


787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
# File 'dbm.c', line 787

static VALUE
fdbm_each_pair(VALUE obj)
{
    datum key, val;
    DBM *dbm;
    struct dbmdata *dbmp;
    VALUE keystr, valstr;

    RETURN_ENUMERATOR(obj, 0, 0);

    GetDBM2(obj, dbmp, dbm);

    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  val = dbm_fetch(dbm, key);
  keystr = rb_tainted_str_new(key.dptr, key.dsize);
  valstr = rb_tainted_str_new(val.dptr, val.dsize);
  rb_yield(rb_assoc_new(keystr, valstr));
  GetDBM2(obj, dbmp, dbm);
    }

    return obj;
}

#each_value {|value| ... } ⇒ self

Calls the block once for each value string in the database. Returns self.

Yields:

  • (value)

Returns:

  • (self)


739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
# File 'dbm.c', line 739

static VALUE
fdbm_each_value(VALUE obj)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;

    RETURN_ENUMERATOR(obj, 0, 0);

    GetDBM2(obj, dbmp, dbm);
    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  val = dbm_fetch(dbm, key);
  rb_yield(rb_tainted_str_new(val.dptr, val.dsize));
  GetDBM2(obj, dbmp, dbm);
    }
    return obj;
}

#empty?Boolean

Returns true if the database is empty, false otherwise.

Returns:

  • (Boolean)


711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
# File 'dbm.c', line 711

static VALUE
fdbm_empty_p(VALUE obj)
{
    datum key;
    struct dbmdata *dbmp;
    DBM *dbm;

    GetDBM2(obj, dbmp, dbm);
    if (dbmp->di_size < 0) {
  dbm = dbmp->di_dbm;

  for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
      return Qfalse;
  }
    }
    else {
  if (dbmp->di_size)
      return Qfalse;
    }
    return Qtrue;
}

#fetch(key[, ifnone]) ⇒ Object

Return a value from the database by locating the key string provided. If the key is not found, returns ifnone. If ifnone is not given, raises IndexError.



313
314
315
316
317
318
319
320
321
322
323
324
# File 'dbm.c', line 313

static VALUE
fdbm_fetch_m(int argc, VALUE *argv, VALUE obj)
{
    VALUE keystr, valstr, ifnone;

    rb_scan_args(argc, argv, "11", &keystr, &ifnone);
    valstr = fdbm_fetch(obj, keystr, ifnone);
    if (argc == 1 && !rb_block_given_p() && NIL_P(valstr))
  rb_raise(rb_eIndexError, "key not found");

    return valstr;
}

#include?(key) ⇒ Boolean #has_key?(key) ⇒ Boolean #member?(key) ⇒ Boolean #key?(key) ⇒ Boolean

Returns true if the database contains the specified key, false otherwise.

Overloads:

  • #include?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #has_key?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #key?(key) ⇒ Boolean

    Returns:

    • (Boolean)

Returns:

  • (Boolean)


867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
# File 'dbm.c', line 867

static VALUE
fdbm_has_key(VALUE obj, VALUE keystr)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    long len;

    ExportStringValue(keystr);
    len = RSTRING_LEN(keystr);
    if (TOO_LONG(len)) return Qfalse;
    key.dptr = RSTRING_PTR(keystr);
    key.dsize = (DSIZE_TYPE)len;

    GetDBM2(obj, dbmp, dbm);
    val = dbm_fetch(dbm, key);
    if (val.dptr) return Qtrue;
    return Qfalse;
}

#has_value?(value) ⇒ Boolean #value?(value) ⇒ Boolean

Returns true if the database contains the specified string value, false otherwise.

Overloads:

  • #has_value?(value) ⇒ Boolean

    Returns:

    • (Boolean)
  • #value?(value) ⇒ Boolean

    Returns:

    • (Boolean)

Returns:

  • (Boolean)


895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
# File 'dbm.c', line 895

static VALUE
fdbm_has_value(VALUE obj, VALUE valstr)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    long len;

    ExportStringValue(valstr);
    len = RSTRING_LEN(valstr);
    if (TOO_LONG(len)) return Qfalse;
    val.dptr = RSTRING_PTR(valstr);
    val.dsize = (DSIZE_TYPE)len;

    GetDBM2(obj, dbmp, dbm);
    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  val = dbm_fetch(dbm, key);
  if ((DSIZE_TYPE)val.dsize == (DSIZE_TYPE)RSTRING_LEN(valstr) &&
      memcmp(val.dptr, RSTRING_PTR(valstr), val.dsize) == 0)
      return Qtrue;
    }
    return Qfalse;
}

#include?(key) ⇒ Boolean #has_key?(key) ⇒ Boolean #member?(key) ⇒ Boolean #key?(key) ⇒ Boolean

Returns true if the database contains the specified key, false otherwise.

Overloads:

  • #include?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #has_key?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #key?(key) ⇒ Boolean

    Returns:

    • (Boolean)

Returns:

  • (Boolean)


867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
# File 'dbm.c', line 867

static VALUE
fdbm_has_key(VALUE obj, VALUE keystr)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    long len;

    ExportStringValue(keystr);
    len = RSTRING_LEN(keystr);
    if (TOO_LONG(len)) return Qfalse;
    key.dptr = RSTRING_PTR(keystr);
    key.dsize = (DSIZE_TYPE)len;

    GetDBM2(obj, dbmp, dbm);
    val = dbm_fetch(dbm, key);
    if (val.dptr) return Qtrue;
    return Qfalse;
}

#index(value) ⇒ Object

:nodoc:



358
359
360
361
362
363
# File 'dbm.c', line 358

static VALUE
fdbm_index(VALUE hash, VALUE value)
{
    rb_warn("DBM#index is deprecated; use DBM#key");
    return fdbm_key(hash, value);
}

#invertHash

Returns a Hash (not a DBM database) created by using each value in the database as a key, with the corresponding key as its value.

Returns:

  • (Hash)


578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
# File 'dbm.c', line 578

static VALUE
fdbm_invert(VALUE obj)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    VALUE keystr, valstr;
    VALUE hash = rb_hash_new();

    GetDBM2(obj, dbmp, dbm);
    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  val = dbm_fetch(dbm, key);
  keystr = rb_tainted_str_new(key.dptr, key.dsize);
  valstr = rb_tainted_str_new(val.dptr, val.dsize);
  rb_hash_aset(hash, valstr, keystr);
    }
    return hash;
}

#key(value) ⇒ String

Returns the key for the specified value.

Returns:

  • (String)


332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
# File 'dbm.c', line 332

static VALUE
fdbm_key(VALUE obj, VALUE valstr)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    long len;

    ExportStringValue(valstr);
    len = RSTRING_LEN(valstr);
    if (TOO_LONG(len)) return Qnil;
    val.dptr = RSTRING_PTR(valstr);
    val.dsize = (DSIZE_TYPE)len;

    GetDBM2(obj, dbmp, dbm);
    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  val = dbm_fetch(dbm, key);
  if ((long)val.dsize == RSTRING_LEN(valstr) &&
      memcmp(val.dptr, RSTRING_PTR(valstr), val.dsize) == 0) {
      return rb_tainted_str_new(key.dptr, key.dsize);
  }
    }
    return Qnil;
}

#include?(key) ⇒ Boolean #has_key?(key) ⇒ Boolean #member?(key) ⇒ Boolean #key?(key) ⇒ Boolean

Returns true if the database contains the specified key, false otherwise.

Overloads:

  • #include?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #has_key?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #key?(key) ⇒ Boolean

    Returns:

    • (Boolean)

Returns:

  • (Boolean)


867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
# File 'dbm.c', line 867

static VALUE
fdbm_has_key(VALUE obj, VALUE keystr)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    long len;

    ExportStringValue(keystr);
    len = RSTRING_LEN(keystr);
    if (TOO_LONG(len)) return Qfalse;
    key.dptr = RSTRING_PTR(keystr);
    key.dsize = (DSIZE_TYPE)len;

    GetDBM2(obj, dbmp, dbm);
    val = dbm_fetch(dbm, key);
    if (val.dptr) return Qtrue;
    return Qfalse;
}

#keysArray

Returns an array of all the string keys in the database.

Returns:

  • (Array)


816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
# File 'dbm.c', line 816

static VALUE
fdbm_keys(VALUE obj)
{
    datum key;
    struct dbmdata *dbmp;
    DBM *dbm;
    VALUE ary;

    GetDBM2(obj, dbmp, dbm);

    ary = rb_ary_new();
    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  rb_ary_push(ary, rb_tainted_str_new(key.dptr, key.dsize));
    }

    return ary;
}

#lengthInteger #sizeInteger

Returns the number of entries in the database.

Overloads:

  • #lengthInteger

    Returns:

    • (Integer)
  • #sizeInteger

    Returns:

    • (Integer)


686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
# File 'dbm.c', line 686

static VALUE
fdbm_length(VALUE obj)
{
    datum key;
    struct dbmdata *dbmp;
    DBM *dbm;
    int i = 0;

    GetDBM2(obj, dbmp, dbm);
    if (dbmp->di_size > 0) return INT2FIX(dbmp->di_size);

    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  i++;
    }
    dbmp->di_size = i;

    return INT2FIX(i);
}

#include?(key) ⇒ Boolean #has_key?(key) ⇒ Boolean #member?(key) ⇒ Boolean #key?(key) ⇒ Boolean

Returns true if the database contains the specified key, false otherwise.

Overloads:

  • #include?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #has_key?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #member?(key) ⇒ Boolean

    Returns:

    • (Boolean)
  • #key?(key) ⇒ Boolean

    Returns:

    • (Boolean)

Returns:

  • (Boolean)


867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
# File 'dbm.c', line 867

static VALUE
fdbm_has_key(VALUE obj, VALUE keystr)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    long len;

    ExportStringValue(keystr);
    len = RSTRING_LEN(keystr);
    if (TOO_LONG(len)) return Qfalse;
    key.dptr = RSTRING_PTR(keystr);
    key.dsize = (DSIZE_TYPE)len;

    GetDBM2(obj, dbmp, dbm);
    val = dbm_fetch(dbm, key);
    if (val.dptr) return Qtrue;
    return Qfalse;
}

#reject {|key, value| ... } ⇒ Hash

Converts the contents of the database to an in-memory Hash, then calls Hash#reject with the specified code block, returning a new Hash.

Yields:

Returns:

  • (Hash)


978
979
980
981
982
# File 'dbm.c', line 978

static VALUE
fdbm_reject(VALUE obj)
{
    return rb_hash_delete_if(fdbm_to_hash(obj));
}

#reject! {|key, value| ... } ⇒ self #delete_if {|key, value| ... } ⇒ self

Deletes all entries for which the code block returns true. Returns self.

Overloads:

  • #reject! {|key, value| ... } ⇒ self

    Yields:

    Returns:

    • (self)
  • #delete_if {|key, value| ... } ⇒ self

    Yields:

    Returns:

    • (self)


503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
# File 'dbm.c', line 503

static VALUE
fdbm_delete_if(VALUE obj)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    VALUE keystr, valstr;
    VALUE ret, ary = rb_ary_tmp_new(0);
    int status = 0;
    long i, n;

    fdbm_modify(obj);
    GetDBM2(obj, dbmp, dbm);
    n = dbmp->di_size;
    dbmp->di_size = -1;

    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  val = dbm_fetch(dbm, key);
  keystr = rb_tainted_str_new(key.dptr, key.dsize);
  OBJ_FREEZE(keystr);
  valstr = rb_tainted_str_new(val.dptr, val.dsize);
        ret = rb_protect(rb_yield, rb_assoc_new(rb_str_dup(keystr), valstr), &status);
        if (status != 0) break;
  if (RTEST(ret)) rb_ary_push(ary, keystr);
  GetDBM2(obj, dbmp, dbm);
    }

    for (i = 0; i < RARRAY_LEN(ary); i++) {
  keystr = RARRAY_AREF(ary, i);
  key.dptr = RSTRING_PTR(keystr);
  key.dsize = (DSIZE_TYPE)RSTRING_LEN(keystr);
  if (dbm_delete(dbm, key)) {
      rb_raise(rb_eDBMError, "dbm_delete failed");
  }
    }
    if (status) rb_jump_tag(status);
    if (n > 0) dbmp->di_size = n - RARRAY_LEN(ary);
    rb_ary_clear(ary);

    return obj;
}

#replace(obj) ⇒ Object

Replaces the contents of the database with the contents of the specified object. Takes any object which implements the each_pair method, including Hash and DBM objects.



635
636
637
638
639
640
641
# File 'dbm.c', line 635

static VALUE
fdbm_replace(VALUE obj, VALUE other)
{
    fdbm_clear(obj);
    rb_block_call(other, rb_intern("each_pair"), 0, 0, update_i, obj);
    return obj;
}

#select {|key, value| ... } ⇒ Array

Returns a new array consisting of the [key, value] pairs for which the code block returns true.

Yields:

Returns:

  • (Array)


372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
# File 'dbm.c', line 372

static VALUE
fdbm_select(VALUE obj)
{
    VALUE new = rb_ary_new();
    datum key, val;
    DBM *dbm;
    struct dbmdata *dbmp;

    GetDBM2(obj, dbmp, dbm);
    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  VALUE assoc, v;
  val = dbm_fetch(dbm, key);
  assoc = rb_assoc_new(rb_tainted_str_new(key.dptr, key.dsize),
           rb_tainted_str_new(val.dptr, val.dsize));
  v = rb_yield(assoc);
  if (RTEST(v)) {
      rb_ary_push(new, assoc);
  }
  GetDBM2(obj, dbmp, dbm);
    }

    return new;
}

#shiftArray

Removes a [key, value] pair from the database, and returns it. If the database is empty, returns nil. The order in which values are removed/returned is not guaranteed.

Returns:

  • (Array)


473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
# File 'dbm.c', line 473

static VALUE
fdbm_shift(VALUE obj)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    VALUE keystr, valstr;

    fdbm_modify(obj);
    GetDBM2(obj, dbmp, dbm);
    dbmp->di_size = -1;

    key = dbm_firstkey(dbm);
    if (!key.dptr) return Qnil;
    val = dbm_fetch(dbm, key);
    keystr = rb_tainted_str_new(key.dptr, key.dsize);
    valstr = rb_tainted_str_new(val.dptr, val.dsize);
    dbm_delete(dbm, key);

    return rb_assoc_new(keystr, valstr);
}

#lengthInteger #sizeInteger

Returns the number of entries in the database.

Overloads:

  • #lengthInteger

    Returns:

    • (Integer)
  • #sizeInteger

    Returns:

    • (Integer)


686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
# File 'dbm.c', line 686

static VALUE
fdbm_length(VALUE obj)
{
    datum key;
    struct dbmdata *dbmp;
    DBM *dbm;
    int i = 0;

    GetDBM2(obj, dbmp, dbm);
    if (dbmp->di_size > 0) return INT2FIX(dbmp->di_size);

    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  i++;
    }
    dbmp->di_size = i;

    return INT2FIX(i);
}

#store(key, value) ⇒ Object #[]=(key) ⇒ Object

Stores the specified string value in the database, indexed via the string key provided.



651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
# File 'dbm.c', line 651

static VALUE
fdbm_store(VALUE obj, VALUE keystr, VALUE valstr)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;

    fdbm_modify(obj);
    keystr = rb_obj_as_string(keystr);
    valstr = rb_obj_as_string(valstr);

    key.dptr = RSTRING_PTR(keystr);
    key.dsize = RSTRING_DSIZE(keystr);

    val.dptr = RSTRING_PTR(valstr);
    val.dsize = RSTRING_DSIZE(valstr);

    GetDBM2(obj, dbmp, dbm);
    dbmp->di_size = -1;
    if (dbm_store(dbm, key, val, DBM_REPLACE)) {
  dbm_clearerr(dbm);
  if (errno == EPERM) rb_sys_fail(0);
  rb_raise(rb_eDBMError, "dbm_store failed");
    }

    return valstr;
}

#to_aArray

Converts the contents of the database to an array of [key, value] arrays, and returns it.

Returns:

  • (Array)


926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
# File 'dbm.c', line 926

static VALUE
fdbm_to_a(VALUE obj)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    VALUE ary;

    GetDBM2(obj, dbmp, dbm);
    ary = rb_ary_new();
    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  val = dbm_fetch(dbm, key);
  rb_ary_push(ary, rb_assoc_new(rb_tainted_str_new(key.dptr, key.dsize),
              rb_tainted_str_new(val.dptr, val.dsize)));
    }

    return ary;
}

#to_hashHash

Converts the contents of the database to an in-memory Hash object, and returns it.

Returns:

  • (Hash)


952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
# File 'dbm.c', line 952

static VALUE
fdbm_to_hash(VALUE obj)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    VALUE hash;

    GetDBM2(obj, dbmp, dbm);
    hash = rb_hash_new();
    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  val = dbm_fetch(dbm, key);
  rb_hash_aset(hash, rb_tainted_str_new(key.dptr, key.dsize),
               rb_tainted_str_new(val.dptr, val.dsize));
    }

    return hash;
}

#update(obj) ⇒ Object

Updates the database with multiple values from the specified object. Takes any object which implements the each_pair method, including Hash and DBM objects.



620
621
622
623
624
625
# File 'dbm.c', line 620

static VALUE
fdbm_update(VALUE obj, VALUE other)
{
    rb_block_call(other, rb_intern("each_pair"), 0, 0, update_i, obj);
    return obj;
}

#has_value?(value) ⇒ Boolean #value?(value) ⇒ Boolean

Returns true if the database contains the specified string value, false otherwise.

Overloads:

  • #has_value?(value) ⇒ Boolean

    Returns:

    • (Boolean)
  • #value?(value) ⇒ Boolean

    Returns:

    • (Boolean)

Returns:

  • (Boolean)


895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
# File 'dbm.c', line 895

static VALUE
fdbm_has_value(VALUE obj, VALUE valstr)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    long len;

    ExportStringValue(valstr);
    len = RSTRING_LEN(valstr);
    if (TOO_LONG(len)) return Qfalse;
    val.dptr = RSTRING_PTR(valstr);
    val.dsize = (DSIZE_TYPE)len;

    GetDBM2(obj, dbmp, dbm);
    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  val = dbm_fetch(dbm, key);
  if ((DSIZE_TYPE)val.dsize == (DSIZE_TYPE)RSTRING_LEN(valstr) &&
      memcmp(val.dptr, RSTRING_PTR(valstr), val.dsize) == 0)
      return Qtrue;
    }
    return Qfalse;
}

#valuesArray

Returns an array of all the string values in the database.

Returns:

  • (Array)


840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
# File 'dbm.c', line 840

static VALUE
fdbm_values(VALUE obj)
{
    datum key, val;
    struct dbmdata *dbmp;
    DBM *dbm;
    VALUE ary;

    GetDBM2(obj, dbmp, dbm);
    ary = rb_ary_new();
    for (key = dbm_firstkey(dbm); key.dptr; key = dbm_nextkey(dbm)) {
  val = dbm_fetch(dbm, key);
  rb_ary_push(ary, rb_tainted_str_new(val.dptr, val.dsize));
    }

    return ary;
}

#values_at(key, ...) ⇒ Array

Returns an array containing the values associated with the given keys.

Returns:

  • (Array)


402
403
404
405
406
407
408
409
410
411
412
413
# File 'dbm.c', line 402

static VALUE
fdbm_values_at(int argc, VALUE *argv, VALUE obj)
{
    VALUE new = rb_ary_new2(argc);
    int i;

    for (i=0; i<argc; i++) {
        rb_ary_push(new, fdbm_fetch(obj, argv[i], Qnil));
    }

    return new;
}