class DBM

Introduction

The DBM class provides a wrapper to a Unix-style dbm or Database Manager library.

Dbm databases do not have tables or columns; they are simple key-value data stores, like a Ruby Hash except not resident in RAM. Keys and values must be strings.

The exact library used depends on how Ruby was compiled. It could be any of the following:

The original ndbm library is released in 4.3BSD. It is based on dbm library in Unix Version 7 but has different API to support multiple databases in a process.
Berkeley DB versions 1 thru 6, also known as BDB and Sleepycat DB, now owned by Oracle Corporation.
Berkeley DB 1.x, still found in 4.4BSD derivatives (FreeBSD, OpenBSD, etc).
gdbm, the GNU implementation of dbm.
qdbm, another open source reimplementation of dbm.

All of these dbm implementations have their own Ruby interfaces available, which provide richer (but varying) APIs.

Cautions

Before you decide to use DBM, there are some issues you should consider:

Each implementation of dbm has its own file format. Generally, dbm libraries will not read each other's files. This makes dbm files a bad choice for data exchange.
Even running the same OS and the same dbm implementation, the database file format may depend on the CPU architecture. For example, files may not be portable between PowerPC and 386, or between 32 and 64 bit Linux.
Different versions of Berkeley DB use different file formats. A change to the OS may therefore break DBM access to existing files.
Data size limits vary between implementations. Original Berkeley DB was limited to 2GB of data. Dbm libraries also sometimes limit the total size of a key/value pair, and the total size of all the keys that hash to the same value. These limits can be as little as 512 bytes. That said, gdbm and recent versions of Berkeley DB do away with these limits.

Given the above cautions, DBM is not a good choice for long term storage of important data. It is probably best used as a fast and easy alternative to a Hash for processing large amounts of data.

Example

require 'dbm'
db = DBM.open('rfcs', 0666, DBM::WRCREAT)
db['822'] = 'Standard for the Format of ARPA Internet Text Messages'
db['1123'] = 'Requirements for Internet Hosts - Application and Support'
db['3068'] = 'An Anycast Prefix for 6to4 Relay Routers'
puts db['822']

Public Class Methods

new

(String filename, ?Integer mode, ?Integer flags) → void

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 384
def initialize: (String filename, ?Integer mode, ?Integer flags) -> void

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.

open

(String filename, ?Integer mode, ?Integer flags) → DBM
[T] (String filename, ?Integer mode, ?Integer flags) { (DBM) → T } → T

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 74
def self.open: (String filename, ?Integer mode, ?Integer flags) -> DBM
               | [T] (String filename, ?Integer mode, ?Integer flags) { (DBM) -> T } -> T

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

Public Instance Methods

[]

(String) → String?

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 84
def []: (String) -> String?

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

[]=

(String, String) → String

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 94
def []=: (String, String) -> String

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

clear

() → self

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 102
def clear: () -> self

Deletes all data from the database.

() → void

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 110
def close: () -> void

Closes the database.

closed?

() → bool

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 118
def closed?: () -> bool

Returns true if the database is closed, false otherwise.

delete

(String) → void

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 126
def delete: (String) -> void

Deletes an entry from the database.

delete_if

() { (String) → boolish } → self

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 135
def delete_if: () { (String) -> boolish } -> self

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

each

() { ([ String, String ]) → void } → self
() → Enumerator[[ String, String ], self]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 143
def each: () { ([ String, String ]) -> void } -> self
          | () -> Enumerator[[ String, String ], self]

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

each_key

() { (String) → void } → self
() → Enumerator[String, self]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 152
def each_key: () { (String) -> void } -> self
              | () -> Enumerator[String, self]

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

each_pair

() { ([ String, String ]) → void } → self
() → Enumerator[[ String, String ], self]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 158
def each_pair: () { ([ String, String ]) -> void } -> self
               | () -> Enumerator[[ String, String ], self]

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

each_value

() { (String) → void } → self
() → Enumerator[String, self]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 167
def each_value: () { (String) -> void } -> self
                | () -> Enumerator[String, self]

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

empty?

() → bool

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 176
def empty?: () -> bool

Returns true if the database is empty, false otherwise.

fetch

(String key, ?String ifnone) → String

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 186
def fetch: (String key, ?String ifnone) -> String

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.

has_key?

(String) → bool

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 191
def has_key?: (String) -> bool

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

has_value?

() → bool

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 201
def has_value?: () -> bool

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

include?

(String) → bool

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 212
def include?: (String) -> bool

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

invert

() → Hash[String, String]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 221
def invert: () -> Hash[String, String]

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.

key

(String) → String?

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 229
def key: (String) -> String?

Returns the key for the specified value.

key?

(String) → bool

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 234
def key?: (String) -> bool

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

keys

() → Array[String]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 242
def keys: () -> Array[String]

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

length

() → Integer

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 251
def length: () -> Integer

Returns the number of entries in the database.

member?

(String) → bool

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 256
def member?: (String) -> bool

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

reject

() { (String, String) → boolish } → Hash[String, String]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 265
def reject: () { (String, String) -> boolish } -> Hash[String, String]

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

reject!

() { (String, String) → boolish } → self

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 270
def reject!: () { (String, String) -> boolish } -> self

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

replace

(_ReplaceSource) → ::DBM

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 280
def replace: (_ReplaceSource) -> ::DBM

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.

select

() { ([ String, String ]) → boolish } → Array[[ String, String ]]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 293
def select: () { ([ String, String ]) -> boolish } -> Array[[ String, String ]]

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

shift

() → [ String, String ]?

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 303
def shift: () -> [ String, String ]?

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.

size

() → Integer

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 308
def size: () -> Integer

Returns the number of entries in the database.

store

(String, String) → String

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 314
def store: (String, String) -> String

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

to_a

() → Array[[ String, String ]]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 323
def to_a: () -> Array[[ String, String ]]

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

to_hash

() → Hash[String, String]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 332
def to_hash: () -> Hash[String, String]

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

update

(_UpdateSource) → ::DBM

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 341
def update: (_UpdateSource) -> ::DBM

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

value?

(String) → bool

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 351
def value?: (String) -> bool

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

values

() → Array[String]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 359
def values: () -> Array[String]

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

values_at

(*String) → Array[String]

Source

# File vendor/bundle/ruby/4.0.0/gems/rbs-4.0.3/stdlib/dbm/0/dbm.rbs, line 367
def values_at: (*String) -> Array[String]

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