Class: GDBM http://ruby-doc.org/stdlib/libdoc/gdbm/rdoc/classes/GDBM.

html

Class GDBM
In: gdbm/gdbm.c
Parent: Object

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

Links
www.gnu.org/software/gdbm/

Methods

1 of 7 2010-09-02 5:18 PM
Class: GDBM http://ruby-doc.org/stdlib/libdoc/gdbm/rdoc/classes/GDBM.html

[] []= cachesize= clear close closed? delete delete_if each each_key each_pair
each_value empty? fastmode= fetch has_key? has_value? include? index invert key?
keys length member? new open reject reject! reorganize replace select shift size
store sync syncmode= to_a to_hash update value? values values_at

Included Modules

Enumerable

Constants

READER = flag for #new and #open open database as a reader

WRITER = flag for #new and #open open database as a writer
open database as a writer; if the database does not
WRCREAT = flag for #new and #open
exist, create a new one
open database as a writer; overwrite any existing
NEWDB = flag for #new and #open
databases
flag for new and open. this flag is obsolete for gdbm
FAST = INT2FIX(GDBM_FAST)
>= 1.8
SYNC = INT2FIX(GDBM_SYNC) flag for new and open. only for gdbm >= 1.8
NOLOCK = INT2FIX(GDBM_NOLOCK) flag for new and open
VERSION = rb_str_new2(gdbm_version) version of the gdbm library

Public Class methods

GDBM.new(filename, mode = 0666, flags = nil)

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

[Source]

GDBM.open(filename, mode = 0666, flags = nil)

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

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:

2 of 7 2010-09-02 5:18 PM
Class: GDBM http://ruby-doc.org/stdlib/libdoc/gdbm/rdoc/classes/GDBM.html

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

[Source]

Public Instance methods

gdbm[key] ? value

Retrieves the value corresponding to key.

[Source]

gdbm[key]= value ? value

gdbm.store(key, value) ? value

Associates the value value with the specified key.

[Source]

gdbm.cachesize = size ? size

Sets the size of the internal bucket cache to size.

[Source]

gdbm.clear ? gdbm

Removes all the key-value pairs within gdbm.

[Source]

gdbm.close ? nil

Closes the associated database file.

[Source]

gdbm.closed? ? true or false

Returns true if the associated database file has been closed.

[Source]

gdbm.delete(key) ? value or 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.

[Source]

gdbm.delete_if { |key, value| block } ? gdbm

gdbm.reject! { |key, value| block } ? gdbm

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

[Source]

3 of 7 2010-09-02 5:18 PM
Class: GDBM http://ruby-doc.org/stdlib/libdoc/gdbm/rdoc/classes/GDBM.html

gdbm.each_pair { |key, value| block } ? gdbm

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

[Source]

gdbm.each_key { |key| block } ? gdbm

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

[Source]

gdbm.each_pair { |key, value| block } ? gdbm

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

[Source]

gdbm.each_value { |value| block } ? gdbm

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

[Source]

gdbm.empty? ? true or false

Returns true if the database is empty.

[Source]

gdbm.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=

[Source]

gdbm.fetch(key [, default]) ? value

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

[Source]

gdbm.has_key?(k) ? true or false

gdbm.key?(k) ? true or false

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

[Source]

gdbm.has_value?(v) ? true or false

gdbm.value?(v) ? true or false

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

[Source]

4 of 7 2010-09-02 5:18 PM
Class: GDBM http://ruby-doc.org/stdlib/libdoc/gdbm/rdoc/classes/GDBM.html

gdbm.has_key?(k) ? true or false

gdbm.key?(k) ? true or false

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

[Source]

gdbm.index(value) ? key

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.

[Source]

gdbm.invert ? hash

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

[Source]

gdbm.has_key?(k) ? true or false

gdbm.key?(k) ? true or false

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

[Source]

gdbm.keys ? array

Returns an array of all keys of this database.

[Source]

gdbm.length ? fixnum
gdbm.size ? fixnum

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

[Source]

gdbm.has_key?(k) ? true or false

gdbm.key?(k) ? true or false

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

[Source]

gdbm.reject { |key, value| block } ? 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

[Source]

gdbm.delete_if { |key, value| block } ? gdbm

gdbm.reject! { |key, value| block } ? gdbm

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

[Source]

gdbm.reorganize ? gdbm

5 of 7 2010-09-02 5:18 PM
Class: GDBM http://ruby-doc.org/stdlib/libdoc/gdbm/rdoc/classes/GDBM.html

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.

[Source]

gdbm.replace(other) ? gdbm

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

[Source]

gdbm.select { |value| block } ? array

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

[Source]

gdbm.shift ? (key, value) or 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.

[Source]

gdbm.length ? fixnum
gdbm.size ? fixnum

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

[Source]

gdbm[key]= value ? value

gdbm.store(key, value) ? value

Associates the value value with the specified key.

[Source]

gdbm.sync ? gdbm

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.

[Source]

gdbm.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=

[Source]

gdbm.to_a ? array

6 of 7 2010-09-02 5:18 PM
Class: GDBM http://ruby-doc.org/stdlib/libdoc/gdbm/rdoc/classes/GDBM.html

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

[Source]

gdbm.to_hash ? hash

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

[Source]

gdbm.update(other) ? gdbm

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.

[Source]

gdbm.has_value?(v) ? true or false

gdbm.value?(v) ? true or false

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

[Source]

gdbm.values ? array

Returns an array of all values of this database.

[Source]

gdbm.values_at(key, ...) ? array

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

[Source]

[Validate]

7 of 7 2010-09-02 5:18 PM