Class: GDBM

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

Overview

Summary

Ruby extension for GNU dbm (gdbm) -- a simple database engine for storing key-value pairs on disk.

Description

GNU dbm is a library for simple databases. A database is a file that stores key-value pairs. Gdbm allows the user to store, retrieve, and delete data by key. It furthermore allows a non-sorted traversal of all key-value pairs. A gdbm database thus provides the same functionality as a hash. As with objects of the Hash class, elements can be accessed with []. Furthermore, GDBM mixes in the Enumerable module, thus providing convenient methods such as #find, #collect, #map, etc.

A process is allowed to open several different databases at the same time. A process can open a database as a "reader" or a "writer". Whereas a reader has only read-access to the database, a writer has read- and write-access. A database can be accessed either by any number of readers or by exactly one writer at the same time.

Examples

  1. Opening/creating a database, and filling it with some entries:

    require 'gdbm'

gdbm = GDBM.new("fruitstore.db")
gdbm["ananas"]    = "3"
gdbm["banana"]    = "8"
gdbm["cranberry"] = "4909"
gdbm.close

  2. Reading out a database:

    require 'gdbm'

gdbm = GDBM.new("fruitstore.db")
gdbm.each_pair do |key, value|
print "#{key}: #{value}\n"
end
gdbm.close

    produces

    banana: 8
ananas: 3
cranberry: 4909

Constant Summary collapse

READER =

open database as a reader

flag for #new and #open
WRITER =

open database as a writer

flag for #new and #open
WRCREAT =

open database as a writer; if the database does not exist, create a new one

flag for #new and #open
NEWDB =

open database as a writer; overwrite any existing databases

flag for #new and #open
FAST =

flag for #new and #open. this flag is obsolete for gdbm >= 1.8

INT2FIX(GDBM_FAST)
SYNC =

flag for #new and #open. only for gdbm >= 1.8

INT2FIX(GDBM_SYNC)
NOLOCK =

flag for #new and #open

INT2FIX(GDBM_NOLOCK)
VERSION =

version of the gdbm library

rb_str_new2(gdbm_version)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#new(filename, mode = 0666, flags = nil) ⇒ Object

Creates a new GDBM instance by opening a gdbm file named filename. If the file does not exist, a new file with file mode mode will be created. flags may be one of the following:

  • READER - open as a reader
  • WRITER - open as a writer
  • WRCREAT - open as a writer; if the database does not exist, create a new one
  • NEWDB - open as a writer; overwrite any existing databases

The values WRITER, WRCREAT and NEWDB may be combined with the following values by bitwise or:

  • SYNC - cause all database operations to be synchronized to the disk
  • NOLOCK - do not lock the database file

If no flags are specified, the GDBM object will try to open the database file as a writer and will create it if it does not already exist (cf. flag WRCREAT). If this fails (for instance, if another process has already opened the database as a reader), it will try to open the database file as a reader (cf. flag READER).



192
193
194
 
# File 'gdbm.c', line 192

static VALUE
fgdbm_initialize(argc, argv, obj)
int argc;

Class Method Details

.open(filename, mode = 0666, flags = nil) ⇒ Object .open(filename, mode = 0666, flags = nil) {|gdbm| ... } ⇒ Object

If called without a block, this is synonymous to GDBM::new. If a block is given, the new GDBM instance will be passed to the block as a parameter, and the corresponding database file will be closed after the execution of the block code has been finished.

Example for an open call with a block:

require 'gdbm'
GDBM.open("fruitstore.db") do |gdbm|
gdbm.each_pair do |key, value|
  print "#{key}: #{value}\n"
end
end

Overloads:

  • .open(filename, mode = 0666, flags = nil) {|gdbm| ... } ⇒ Object

    Yields:

    • (gdbm) 


275
276
277
 
# File 'gdbm.c', line 275

static VALUE
fgdbm_s_open(argc, argv, klass)
int argc;

Instance Method Details

#[](key) ⇒ Object

Retrieves the value corresponding to key.



407
408
409
 
# File 'gdbm.c', line 407

static VALUE
fgdbm_aref(obj, keystr)
VALUE obj, keystr;

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

Associates the value value with the specified key.



805
806
807
 
# File 'gdbm.c', line 805

static VALUE
fgdbm_store(obj, keystr, valstr)
VALUE obj, keystr, valstr;

#cachesize=(size) ⇒ Object

Sets the size of the internal bucket cache to size.



1154
1155
1156
 
# File 'gdbm.c', line 1154

static VALUE
fgdbm_set_cachesize(obj, val)
VALUE obj, val;

#clear ⇒ Object

Removes all the key-value pairs within gdbm.



679
680
681
 
# File 'gdbm.c', line 679

static VALUE
fgdbm_clear(obj)
VALUE obj;

#close ⇒ nil

Closes the associated database file.

Returns:

  • (nil) 


126
127
128
 
# File 'gdbm.c', line 126

static VALUE
fgdbm_close(obj)
VALUE obj;

#closed? ⇒ Boolean

Returns true if the associated database file has been closed.

Returns:

  • (Boolean) 


145
146
147
 
# File 'gdbm.c', line 145

static VALUE
fgdbm_closed(obj)
VALUE obj;

#delete(key) ⇒ nil

Removes the key-value-pair with the specified key from this database and returns the corresponding value. Returns nil if the database is empty.

Returns:

  • (nil) 


597
598
599
 
# File 'gdbm.c', line 597

static VALUE
fgdbm_delete(obj, keystr)
VALUE obj, keystr;

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

Deletes every key-value pair from gdbm for which block evaluates to true.

Overloads:

  • #delete_if {|key, value| ... } ⇒ Object

    Yields:

    • (key, value)
  • #reject! {|key, value| ... } ⇒ Object

    Yields:

    • (key, value) 


640
641
642
 
# File 'gdbm.c', line 640

static VALUE
fgdbm_delete_if(obj)
VALUE obj;

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

Executes block for each key in the database, passing the key and the correspoding value as a parameter.

Yields:

  • (key, value) 


949
950
951
 
# File 'gdbm.c', line 949

static VALUE
fgdbm_each_pair(obj)
VALUE obj;

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

Executes block for each key in the database, passing the key as a parameter.

Yields:

  • (key) 


924
925
926
 
# File 'gdbm.c', line 924

static VALUE
fgdbm_each_key(obj)
VALUE obj;

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

Executes block for each key in the database, passing the key and the correspoding value as a parameter.

Yields:

  • (key, value) 


949
950
951
 
# File 'gdbm.c', line 949

static VALUE
fgdbm_each_pair(obj)
VALUE obj;

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

Executes block for each key in the database, passing the corresponding value as a parameter.

Yields:

  • (value) 


899
900
901
 
# File 'gdbm.c', line 899

static VALUE
fgdbm_each_value(obj)
VALUE obj;

#empty? ⇒ Boolean

Returns true if the database is empty.

Returns:

  • (Boolean) 


868
869
870
 
# File 'gdbm.c', line 868

static VALUE
fgdbm_empty_p(obj)
VALUE obj;

#fastmode=(boolean) ⇒ Boolean

Turns the database's fast mode on or off. If fast mode is turned on, gdbm does not wait for writes to be flushed to the disk before continuing.

This option is obsolete for gdbm >= 1.8 since fast mode is turned on by default. See also: #syncmode=

Returns:

  • (Boolean) 


1180
1181
1182
 
# File 'gdbm.c', line 1180

static VALUE
fgdbm_set_fastmode(obj, val)
VALUE obj, val;

#fetch(key[, default]) ⇒ Object

Retrieves the value corresponding to key. If there is no value associated with key, default will be returned instead.



421
422
423
 
# File 'gdbm.c', line 421

static VALUE
fgdbm_fetch_m(argc, argv, obj)
int argc;

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

Returns true if the given key k exists within the database. Returns false otherwise.

Overloads:

  • #has_key?(k) ⇒ Boolean

    Returns:

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

    Returns:

    • (Boolean) 


1028
1029
1030
 
# File 'gdbm.c', line 1028

static VALUE
fgdbm_has_key(obj, keystr)
VALUE obj, keystr;

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

Returns true if the given value v exists within the database. Returns false otherwise.

Overloads:

  • #has_value?(v) ⇒ Boolean

    Returns:

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

    Returns:

    • (Boolean) 


1054
1055
1056
 
# File 'gdbm.c', line 1054

static VALUE
fgdbm_has_value(obj, valstr)
VALUE obj, valstr;

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

Returns true if the given key k exists within the database. Returns false otherwise.

Overloads:

  • #has_key?(k) ⇒ Boolean

    Returns:

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

    Returns:

    • (Boolean) 


1028
1029
1030
 
# File 'gdbm.c', line 1028

static VALUE
fgdbm_has_key(obj, keystr)
VALUE obj, keystr;

#index(value) ⇒ Object

Returns the key for a given value. If several keys may map to the same value, the key that is found first will be returned.



444
445
446
 
# File 'gdbm.c', line 444

static VALUE
fgdbm_index(obj, valstr)
VALUE obj, valstr;

#indexes ⇒ Object 



468
469
470
 
# File 'gdbm.c', line 468

static VALUE
fgdbm_indexes(argc, argv, obj)
int argc;

#indices ⇒ Object 



468
469
470
 
# File 'gdbm.c', line 468

static VALUE
fgdbm_indexes(argc, argv, obj)
int argc;

#invert ⇒ Hash

Returns a hash created by using gdbm's values as keys, and the keys as values.

Returns:

  • (Hash) 


724
725
726
 
# File 'gdbm.c', line 724

static VALUE
fgdbm_invert(obj)
VALUE obj;

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

Returns true if the given key k exists within the database. Returns false otherwise.

Overloads:

  • #has_key?(k) ⇒ Boolean

    Returns:

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

    Returns:

    • (Boolean) 


1028
1029
1030
 
# File 'gdbm.c', line 1028

static VALUE
fgdbm_has_key(obj, keystr)
VALUE obj, keystr;

#keys ⇒ Array

Returns an array of all keys of this database.

Returns:

  • (Array) 


974
975
976
 
# File 'gdbm.c', line 974

static VALUE
fgdbm_keys(obj)
VALUE obj;

#length ⇒ Fixnum #size ⇒ Fixnum

Returns the number of key-value pairs in this database.

Overloads:

  • #length ⇒ Fixnum

    Returns:

    • (Fixnum)
  • #size ⇒ Fixnum

    Returns:

    • (Fixnum) 


840
841
842
 
# File 'gdbm.c', line 840

static VALUE
fgdbm_length(obj)
VALUE obj;

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

Returns true if the given key k exists within the database. Returns false otherwise.

Overloads:

  • #has_key?(k) ⇒ Boolean

    Returns:

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

    Returns:

    • (Boolean) 


1028
1029
1030
 
# File 'gdbm.c', line 1028

static VALUE
fgdbm_has_key(obj, keystr)
VALUE obj, keystr;

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

Returns a hash copy of gdbm where all key-value pairs from gdbm for which block evaluates to true are removed. See also: #delete_if

Yields:

  • (key, value)

Returns:

  • (Hash) 


1268
1269
1270
 
# File 'gdbm.c', line 1268

static VALUE
fgdbm_reject(obj)
VALUE obj;

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

Deletes every key-value pair from gdbm for which block evaluates to true.

Overloads:

  • #delete_if {|key, value| ... } ⇒ Object

    Yields:

    • (key, value)
  • #reject! {|key, value| ... } ⇒ Object

    Yields:

    • (key, value) 


640
641
642
 
# File 'gdbm.c', line 640

static VALUE
fgdbm_delete_if(obj)
VALUE obj;

#reorganize ⇒ Object

Reorganizes the database file. This operation removes reserved space of elements that have already been deleted. It is only useful after a lot of deletions in the database.



1112
1113
1114
 
# File 'gdbm.c', line 1112

static VALUE
fgdbm_reorganize(obj)
VALUE obj;

#replace(other) ⇒ Object

Replaces the content of gdbm with the key-value pairs of other. other must have an each_pair method.



789
790
791
 
# File 'gdbm.c', line 789

static VALUE
fgdbm_replace(obj, other)
VALUE obj, other;

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

Returns a new array of all values of the database for which block evaluates to true.

Yields:

  • (value)

Returns:

  • (Array) 


492
493
494
 
# File 'gdbm.c', line 492

static VALUE
fgdbm_select(argc, argv, obj)
int argc;

#shift ⇒ nil

Removes a key-value-pair from this database and returns it as a two-item array [ key, value ]. Returns nil if the database is empty.

Returns:

  • (nil) 


615
616
617
 
# File 'gdbm.c', line 615

static VALUE
fgdbm_shift(obj)
VALUE obj;

#length ⇒ Fixnum #size ⇒ Fixnum

Returns the number of key-value pairs in this database.

Overloads:

  • #length ⇒ Fixnum

    Returns:

    • (Fixnum)
  • #size ⇒ Fixnum

    Returns:

    • (Fixnum) 


840
841
842
 
# File 'gdbm.c', line 840

static VALUE
fgdbm_length(obj)
VALUE obj;

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

Associates the value value with the specified key.



805
806
807
 
# File 'gdbm.c', line 805

static VALUE
fgdbm_store(obj, keystr, valstr)
VALUE obj, keystr, valstr;

#sync ⇒ Object

Unless the gdbm object has been opened with the SYNC flag, it is not guarenteed that database modification operations are immediately applied to the database file. This method ensures that all recent modifications to the database are written to the file. Blocks until all writing operations to the disk have been finished.



1135
1136
1137
 
# File 'gdbm.c', line 1135

static VALUE
fgdbm_sync(obj)
VALUE obj;

#syncmode=(boolean) ⇒ Boolean

Turns the database's synchronization mode on or off. If the synchronization mode is turned on, the database's in-memory state will be synchronized to disk after every database modification operation. If the synchronization mode is turned off, GDBM does not wait for writes to be flushed to the disk before continuing.

This option is only available for gdbm >= 1.8 where syncmode is turned off by default. See also: #fastmode=

Returns:

  • (Boolean) 


1212
1213
1214
 
# File 'gdbm.c', line 1212

static VALUE
fgdbm_set_syncmode(obj, val)
VALUE obj, val;

#to_a ⇒ Array

Returns an array of all key-value pairs contained in the database.

Returns:

  • (Array) 


1085
1086
1087
 
# File 'gdbm.c', line 1085

static VALUE
fgdbm_to_a(obj)
VALUE obj;

#to_hash ⇒ Hash

Returns a hash of all key-value pairs contained in the database.

Returns:

  • (Hash) 


1242
1243
1244
 
# File 'gdbm.c', line 1242

static VALUE
fgdbm_to_hash(obj)
VALUE obj;

#update(other) ⇒ Object

Adds the key-value pairs of other to gdbm, overwriting entries with duplicate keys with those from other. other must have an each_pair method.



774
775
776
 
# File 'gdbm.c', line 774

static VALUE
fgdbm_update(obj, other)
VALUE obj, other;

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

Returns true if the given value v exists within the database. Returns false otherwise.

Overloads:

  • #has_value?(v) ⇒ Boolean

    Returns:

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

    Returns:

    • (Boolean) 


1054
1055
1056
 
# File 'gdbm.c', line 1054

static VALUE
fgdbm_has_value(obj, valstr)
VALUE obj, valstr;

#values ⇒ Array

Returns an array of all values of this database.

Returns:

  • (Array) 


999
1000
1001
 
# File 'gdbm.c', line 999

static VALUE
fgdbm_values(obj)
VALUE obj;

#values_at(key, ...) ⇒ Array

Returns an array of the values associated with each specified key.

Returns:

  • (Array) 


538
539
540
 
# File 'gdbm.c', line 538

static VALUE
fgdbm_values_at(argc, argv, obj)
int argc;