Class: GDBM
Relationships & Source Files | |
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
self,
Enumerable
|
|
Inherits: | Object |
Defined in: | ext/gdbm/gdbm.c, ext/gdbm/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
-
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
-
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
Constant Summary
-
FAST =
flag for
#new
and#open
. this flag is obsolete for gdbm >= 1.8INT2FIX(GDBM_FAST)
-
NEWDB =
open database as a writer; overwrite any existing databases
flag for #new and #open
-
NOLOCK =
flag for
#new
and#open
INT2FIX(GDBM_NOLOCK)
-
READER =
open database as a reader
flag for #new and #open
-
SYNC =
flag for
#new
and#open
. only for gdbm >= 1.8INT2FIX(GDBM_SYNC)
-
VERSION =
version of the gdbm library
rb_str_new2(gdbm_version)
-
WRCREAT =
open database as a writer; if the database does not exist, create a new one
flag for #new and #open
-
WRITER =
open database as a writer
flag for #new and #open
Class Method Summary
-
.new(filename, mode = 0666, flags = nil)
constructor
Creates a new
GDBM
instance by opening a gdbm file named filename. -
.open(filename, mode = 0666, flags = nil)
If called without a block, this is synonymous to .new.
Instance Attribute Summary
-
#closed? ⇒ Boolean
readonly
Returns true if the associated database file has been closed.
-
#empty? ⇒ Boolean
readonly
Returns true if the database is empty.
-
#cachesize=(size) ⇒ size
writeonly
Sets the size of the internal bucket cache to size.
-
#fastmode=(boolean) ⇒ Boolean
writeonly
Turns the database's fast mode on or off.
-
#syncmode=(boolean) ⇒ Boolean
writeonly
Turns the database's synchronization mode on or off.
Instance Method Summary
-
#[](key) ⇒ value
Retrieves the value corresponding to key.
-
#[]=(key, value) ⇒ value
(also: #store)
Associates the value value with the specified key.
-
#clear ⇒ GDBM
Removes all the key-value pairs within gdbm.
- #close
-
#delete(key) ⇒ value?
Removes the key-value-pair with the specified key from this database and returns the corresponding value.
-
#delete_if {|key, value| ... } ⇒ GDBM
Alias for #reject!.
-
#each_pair {|key, value| ... } ⇒ GDBM
(also: #each_pair)
Executes block for each key in the database, passing the key and the corresponding value as a parameter.
-
#each_key {|key| ... } ⇒ GDBM
Executes block for each key in the database, passing the key as a parameter.
-
#each_pair {|key, value| ... } ⇒ GDBM
Alias for #each.
-
#each_value {|value| ... } ⇒ GDBM
Executes block for each key in the database, passing the corresponding value as a parameter.
-
#fetch(key [, default]) ⇒ value
Retrieves the value corresponding to key.
-
#has_key?(k) ⇒ Boolean
Alias for #key?.
-
#has_value?(v) ⇒ Boolean
Alias for #value?.
-
#include?(k) ⇒ Boolean
Alias for #key?.
-
#invert ⇒ Hash
Returns a hash created by using gdbm's values as keys, and the keys as values.
-
#key(value) ⇒ key
Returns the key for a given value.
-
#key?(k) ⇒ Boolean
(also: #include?, #has_key?, #member?)
Returns true if the given key k exists within the database.
-
#keys ⇒ Array
Returns an array of all keys of this database.
-
#length ⇒ Fixnum
(also: #size)
Returns the number of key-value pairs in this database.
-
#member?(k) ⇒ Boolean
Alias for #key?.
-
#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.
-
#reject! {|key, value| ... } ⇒ GDBM
(also: #delete_if)
Deletes every key-value pair from gdbm for which block evaluates to true.
-
#reorganize ⇒ GDBM
Reorganizes the database file.
-
#replace(other) ⇒ GDBM
Replaces the content of gdbm with the key-value pairs of other.
-
#select {|key, value| ... } ⇒ Array
Returns a new array of all key-value pairs of the database for which block evaluates to true.
-
#shift ⇒ (key, value)?
Removes a key-value-pair from this database and returns it as a two-item array [ key, value ].
-
#size ⇒ Fixnum
Alias for #length.
-
#store(key, value) ⇒ value
Alias for #[]=.
-
#sync ⇒ GDBM
Unless the gdbm object has been opened with the SYNC flag, it is not guaranteed that database modification operations are immediately applied to the database file.
-
#to_a ⇒ Array
Returns an array of all key-value pairs contained in the database.
-
#to_hash ⇒ Hash
Returns a hash of all key-value pairs contained in the database.
-
#update(other) ⇒ GDBM
Adds the key-value pairs of other to gdbm, overwriting entries with duplicate keys with those from other.
-
#value?(v) ⇒ Boolean
(also: #has_value?)
Returns true if the given value v exists within the database.
-
#values ⇒ Array
Returns an array of all values of this database.
-
#values_at(key, ...) ⇒ Array
Returns an array of the values associated with each specified key.
Constructor Details
.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).
Class Method Details
.open(filename, mode = 0666, flags = nil)
.open(filename, mode = 0666, flags = nil) {|gdbm| ... }
If called without a block, this is synonymous to .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
Instance Attribute Details
#cachesize=(size) ⇒ size (writeonly)
Sets the size of the internal bucket cache to size.
#closed? ⇒ Boolean
(readonly)
Returns true if the associated database file has been closed.
#empty? ⇒ Boolean
(readonly)
Returns true if the database is empty.
#fastmode=(boolean) ⇒ Boolean
(writeonly)
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=
#syncmode=(boolean) ⇒ Boolean
(writeonly)
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=
Instance Method Details
#[](key) ⇒ value
Retrieves the value corresponding to key.
#[]=(key, value) ⇒ value
#store(key, value) ⇒ value
Also known as: #store
value
#store(key, value) ⇒ value
Associates the value value with the specified key.
#clear ⇒ GDBM
Removes all the key-value pairs within gdbm.
#close
#delete(key) ⇒ value
?
Removes the key-value-pair with the specified key from this database and returns the corresponding value. Returns nil if the database is empty.
#delete_if {|key, value| ... } ⇒ GDBM
#reject! {|key, value| ... } ⇒ GDBM
GDBM
#reject! {|key, value| ... } ⇒ GDBM
Alias for #reject!.
#each_pair {|key, value| ... } ⇒ GDBM
Also known as: #each_pair
Executes block for each key in the database, passing the key and the corresponding value as a parameter.
#each_key {|key| ... } ⇒ GDBM
Executes block for each key in the database, passing the key as a parameter.
#each_pair {|key, value| ... } ⇒ GDBM
#each_pair {|key, value| ... } ⇒ GDBM
GDBM
#each_pair {|key, value| ... } ⇒ GDBM
Alias for #each.
#each_value {|value| ... } ⇒ GDBM
Executes block for each key in the database, passing the corresponding value as a parameter.
#fetch(key [, default]) ⇒ value
Retrieves the value corresponding to key. If there is no value associated with key, default will be returned instead.
#include?(k) ⇒ Boolean
#has_key?(k) ⇒ Boolean
#member?(k) ⇒ Boolean
#key?(k) ⇒ Boolean
Boolean
#has_key?(k) ⇒ Boolean
#member?(k) ⇒ Boolean
#key?(k) ⇒ Boolean
Alias for #key?.
#has_value?(v) ⇒ Boolean
#value?(v) ⇒ Boolean
Boolean
#value?(v) ⇒ Boolean
Alias for #value?.
#include?(k) ⇒ Boolean
#has_key?(k) ⇒ Boolean
#member?(k) ⇒ Boolean
#key?(k) ⇒ Boolean
Boolean
#has_key?(k) ⇒ Boolean
#member?(k) ⇒ Boolean
#key?(k) ⇒ Boolean
Alias for #key?.
#invert ⇒ Hash
Returns a hash created by using gdbm's values as keys, and the keys as values.
#key(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.
#include?(k) ⇒ Boolean
#has_key?(k) ⇒ Boolean
#member?(k) ⇒ Boolean
#key?(k) ⇒ Boolean
Also known as: #include?, #has_key?, #member?
Boolean
#has_key?(k) ⇒ Boolean
#member?(k) ⇒ Boolean
#key?(k) ⇒ Boolean
Returns true if the given key k exists within the database. Returns false otherwise.
#keys ⇒ Array
Returns an array of all keys of this database.
#length ⇒ Fixnum
#size ⇒ Fixnum
Also known as: #size
Fixnum
#size ⇒ Fixnum
Returns the number of key-value pairs in this database.
#include?(k) ⇒ Boolean
#has_key?(k) ⇒ Boolean
#member?(k) ⇒ Boolean
#key?(k) ⇒ Boolean
Boolean
#has_key?(k) ⇒ Boolean
#member?(k) ⇒ Boolean
#key?(k) ⇒ Boolean
Alias for #key?.
#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
#delete_if {|key, value| ... } ⇒ GDBM
#reject! {|key, value| ... } ⇒ GDBM
Also known as: #delete_if
GDBM
#reject! {|key, value| ... } ⇒ GDBM
Deletes every key-value pair from gdbm for which block evaluates to true.
#reorganize ⇒ GDBM
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.
#replace(other) ⇒ GDBM
Replaces the content of gdbm with the key-value pairs of other. other must have an each_pair method.
#select {|key, value| ... } ⇒ Array
Returns a new array of all key-value pairs of the database for which block evaluates to true.
#shift ⇒ (key, value
)?
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.
#length ⇒ Fixnum
#size ⇒ Fixnum
Fixnum
#size ⇒ Fixnum
Alias for #length.
#[]=(key, value) ⇒ value
#store(key, value) ⇒ value
value
#store(key, value) ⇒ value
Alias for #[]=.
#sync ⇒ GDBM
Unless the gdbm object has been opened with the SYNC flag, it is not guaranteed 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.
#to_a ⇒ Array
Returns an array of all key-value pairs contained in the database.
#to_hash ⇒ Hash
Returns a hash of all key-value pairs contained in the database.
#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.
#has_value?(v) ⇒ Boolean
#value?(v) ⇒ Boolean
Also known as: #has_value?
Boolean
#value?(v) ⇒ Boolean
Returns true if the given value v exists within the database. Returns false otherwise.
#values ⇒ Array
Returns an array of all values of this database.
#values_at(key, ...) ⇒ Array
Returns an array of the values associated with each specified key.