123456789_123456789_123456789_123456789_123456789_

Class: SDBM

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, Enumerable
Inherits: Object
Defined in: ext/sdbm/init.c,
ext/sdbm/init.c

Overview

SDBM provides a simple file-based key-value store, which can only store String keys and values.

Note that Ruby comes with the source code for SDBM, while the DBM and GDBM standard libraries rely on external libraries and headers.

Examples

Insert values:

require 'sdbm'

SDBM.open 'my_database' do |db|
  db['apple'] = 'fruit'
  db['pear'] = 'fruit'
  db['carrot'] = 'vegetable'
  db['tomato'] = 'vegetable'
end

Bulk update:

require 'sdbm'

SDBM.open 'my_database' do |db|
  db.update('peach' => 'fruit', 'tomato' => 'fruit')
end

Retrieve values:

require 'sdbm'

SDBM.open 'my_database' do |db|
  db.each do |key, value|
    puts "Key: #{key}, Value: #{value}"
  end
end

Outputs:

Key: apple, Value: fruit
Key: pear, Value: fruit
Key: carrot, Value: vegetable
Key: peach, Value: fruit
Key: tomato, Value: fruit

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(filename, mode = 0666)

Creates a new database handle by opening the given filename. SDBM actually uses two physical files, with extensions '.dir' and '.pag'. These extensions will automatically be appended to the filename.

If the file does not exist, a new file will be created using the given mode, unless mode is explicitly set to nil. In the latter case, no database will be created.

If the file exists, it will be opened in read/write mode. If this fails, it will be opened in read-only mode.

Class Method Details

.open(filename, mode = 0666) .open(filename, mode = 0666) {|sdbm| ... }

If called without a block, this is the same as .new.

If a block is given, the new database will be passed to the block and will be safely closed after the block has executed.

Example:

require 'sdbm'

SDBM.open('my_database') do |db|
  db['hello'] = 'world'
end

Instance Attribute Details

#closed? ⇒ Boolean (readonly)

Returns true if the database is closed.

#empty? ⇒ Boolean (readonly)

Returns true if the database is empty.

Instance Method Details

#[](key) ⇒ value?

Returns the value in the database associated with the given #key string.

If no value is found, returns nil.

#[]=(key, value) ⇒ value #store(key, value) ⇒ value
Also known as: #store

Stores a new value in the database with the given #key as an index.

If the #key already exists, this will update the value associated with the #key.

Returns the given value.

#clear ⇒ self

Deletes all data from the database.

#close

#delete(key) ⇒ value? #delete(key) {|key, value| ... }

Deletes the key-value pair corresponding to the given #key. If the #key exists, the deleted value will be returned, otherwise nil.

If a block is provided, the deleted #key and value will be passed to the block as arguments. If the #key does not exist in the database, the value will be nil.

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

Alias for #reject!.

#each #each {|key, value| ... } #each_pair #each_pair {|key, value| ... }
Also known as: #each_pair

Iterates over each key-value pair in the database.

If no block is given, returns an Enumerator.

#each_key #each_key {|key| ... }

Iterates over each #key in the database.

If no block is given, returns an Enumerator.

#each #each {|key, value| ... } #each_pair #each_pair {|key, value| ... }

Alias for #each.

#each_value #each_value {|value| ... }

Iterates over each value in the database.

If no block is given, returns an Enumerator.

#fetch(key) ⇒ value? #fetch(key) {|key| ... }

Returns the value in the database associated with the given #key string.

If a block is provided, the block will be called when there is no value associated with the given #key. The #key will be passed in as an argument to the block.

If no block is provided and no value is associated with the given #key, then an IndexError will be raised.

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

Alias for #key?.

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

Alias for #value?.

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

Alias for #key?.

#invert ⇒ Hash

Returns a Hash in which the key-value pairs have been inverted.

Example:

require 'sdbm'

SDBM.open 'my_database' do |db|
  db.update('apple' => 'fruit', 'spinach' => 'vegetable')

  db.invert  #=> {"fruit" => "apple", "vegetable" => "spinach"}
end

#key(value) ⇒ key

Returns the key associated with the given value. If more than one key corresponds to the given value, then the first key to be found will be returned. If no keys are found, nil will be returned.

#include?(key) ⇒ Boolean #key?(key) ⇒ Boolean #member?(key) ⇒ Boolean #has_key?(key) ⇒ Boolean
Also known as: #has_key?, #include?, #member?

Returns true if the database contains the given #key.

#keys ⇒ Array

Returns a new Array containing the keys in the database.

#length ⇒ Integer #size ⇒ Integer
Also known as: #size

Returns the number of keys in the database.

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

Alias for #key?.

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

Creates a new Hash using the key-value pairs from the database, then calls Hash#reject with the given block, which returns a Hash with only the key-value pairs for which the block returns false.

#delete_if {|key, value| ... } ⇒ self #reject! {|key, value| ... } ⇒ self
Also known as: #delete_if

Iterates over the key-value pairs in the database, deleting those for which the block returns true.

#replace(pairs) ⇒ self

Empties the database, then inserts the given key-value pairs.

This method will work with any object which implements an each_pair method, such as a Hash.

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

Returns a new Array of key-value pairs for which the block returns true.

Example:

require 'sdbm'

SDBM.open 'my_database' do |db|
  db['apple'] = 'fruit'
  db['pear'] = 'fruit'
  db['spinach'] = 'vegetable'

  veggies = db.select do |key, value|
    value == 'vegetable'
  end #=> [["apple", "fruit"], ["pear", "fruit"]]
end

#shift ⇒ Array?

Removes a key-value pair from the database and returns them as an Array. If the database is empty, returns nil.

#length ⇒ Integer #size ⇒ Integer

Alias for #length.

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

Alias for #[]=.

#to_a ⇒ Array

Returns a new Array containing each key-value pair in the database.

Example:

require 'sdbm'

SDBM.open 'my_database' do |db|
  db.update('apple' => 'fruit', 'spinach' => 'vegetable')

  db.to_a  #=> [["apple", "fruit"], ["spinach", "vegetable"]]
end

#to_hash ⇒ Hash

Returns a new Hash containing each key-value pair in the database.

#update(pairs) ⇒ self

Insert or update key-value pairs.

This method will work with any object which implements an each_pair method, such as a Hash.

#value?(key) ⇒ Boolean #has_value?(key) ⇒ Boolean
Also known as: #has_value?

Returns true if the database contains the given value.

#values ⇒ Array

Returns a new Array containing the values in the database.

#values_at(key, ...) ⇒ Array

Returns an Array of values corresponding to the given keys.