Class: KyotoCabinet::DB

### Home Classes Methods

### In Files

- kyotocabinet.rb

### Parent

Object

### Methods

- ::new
- ::process
- #[]
- #[]=
- #accept
- #accept_bulk
- #add
- #append
- #begin_transaction
- #cas
- #check
- #clear
- #close
- #copy
- #count
- #cursor
- #cursor_process
- #delete
- #dump_snapshot
- #each
- #each_key
- #each_value
- #end_transaction
- #error
- #fetch
- #get
- #get_bulk
- #increment
- #increment_double
- #inspect
- #iterate
- #length
- #load_snapshot
- #match_prefix
- #match_regex
- #match_similar
- #merge
- #occupy
- #open
- #path
- #remove
- #remove_bulk
- #replace
- #seize
- #set
- #set_bulk
- #shift
- #size
- #status
- #store
- #synchronize
- #to_s
- #transaction
- #tune_encoding
- #tune_exception_rule

### Class/Module Index

Quicksearch

- KyotoCabinet
- KyotoCabinet::Cursor
- KyotoCabinet::DB
- KyotoCabinet::Error
- KyotoCabinet::FileProcessor
- KyotoCabinet::Visitor

No matching classes.

# KyotoCabinet::DB

Interface of database abstraction.

### Constants

GCONCURRENT

  generic mode: concurrent mode

GEXCEPTIONAL

  generic mode: exceptional mode

MADD

  merge mode: keep the existing value

MAPPEND

  merge mode: append the new value

MREPLACE

  merge mode: modify the existing record only

MSET

  merge mode: overwrite the existing value

OAUTOSYNC

  open mode: auto synchronization

OAUTOTRAN

  open mode: auto transaction

OCREATE

  open mode: writer creating

ONOLOCK

  open mode: open without locking

ONOREPAIR

  open mode: open without auto repair

OREADER

  open mode: open as a reader

OTRUNCATE

  open mode: writer truncating

OTRYLOCK

  open mode: lock without blocking

OWRITER

  open mode: open as a writer

### Public Class Methods

new(opts = 0) click to toggle source

Create a database object.

- @param opts the optional features by bitwise-or: DB::GEXCEPTIONAL for the exceptional mode, DB::GCONCURRENT for the concurrent mode.

- @return the database object.

- @note The exceptional mode means that fatal errors caused by methods are reported by exceptions raised. The concurrent mode means that database operations by multiple threads are performed concurrently without the giant VM lock. However, it has a side effect that such methods with call back of Ruby code as DB#accept, DB#accept_bulk, DB#iterate, DB#each, DB#each_key, DB#each_value, Cursor#accept are disabled.

    # File kyotocabinet.rb, line 321
    def initialize(opts = 0)
      # (native code)
    end

process(path = "*", mode = DB::OWRITER | DB::OCREATE, opts = 0) click to toggle source

Process a database by the block parameter.

- @param path the same to the one of the open method.

- @param mode the same to the one of the open method.

- @param opts the optional features by bitwise-or: DB::GCONCURRENT for the concurrent mode.

- @block a block including operations for the database. The block receives the database object. The database is opened with the given parameters before the block and is closed implicitly after the block.

- @return nil on success, or an error object on failure.

    # File kyotocabinet.rb, line 670
    def DB.process(path = "*", mode = DB::OWRITER | DB::OCREATE, opts = 0)
      # (native code)
    end

### Public Instance Methods

[](key) click to toggle source

An alias of DB#get.

    # File kyotocabinet.rb, line 618
    def [](key)
      # (native code)
    end

[]=(key, value) click to toggle source

An alias of DB#store.

    # File kyotocabinet.rb, line 622
    def []=(key, value)
      # (native code)
    end

accept(key, visitor = nil, writable = true) click to toggle source

Accept a visitor to a record.

- @param key the key.

- @param visitor a visitor object which implements the Visitor interface. If it is omitted, the block parameter is evaluated.

- @param writable true for writable operation, or false for read-only operation.

- @block If it is specified, the block is called as the visitor.

- @return true on success, or false on failure.

- @note The operation for each record is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

    # File kyotocabinet.rb, line 349
    def accept(key, visitor = nil, writable = true)
      # (native code)
    end

accept_bulk(keys, visitor = nil, writable = true) click to toggle source

Accept a visitor to multiple records at once.

- @param keys specifies an array of the keys.

- @param visitor a visitor object which implements the Visitor interface, or a function object which receives the key and the value.

- @param writable true for writable operation, or false for read-only operation.

- @return true on success, or false on failure.

- @note The operations for specified records are performed atomically and other threads accessing the same records are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

    # File kyotocabinet.rb, line 358
    def accept_bulk(keys, visitor = nil, writable = true)
      # (native code)
    end

add(key, value) click to toggle source

Add a record.

- @param key the key.

- @param value the value.

- @return true on success, or false on failure.

- @note If no record corresponds to the key, a new record is created. If the corresponding record exists, the record is not modified and false is returned.

    # File kyotocabinet.rb, line 383
    def add(key, value)
      # (native code)
    end

append(key, value) click to toggle source

Append the value of a record.

- @param key the key.

- @param value the value.

- @return true on success, or false on failure.

- @note If no record corresponds to the key, a new record is created. If the corresponding record exists, the given value is appended at the end of the existing value.

    # File kyotocabinet.rb, line 399
    def append(key, value)
      # (native code)
    end

begin_transaction(hard = false) click to toggle source

Begin transaction.

- @param hard true for physical synchronization with the device, or false for logical synchronization with the file system.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 505
    def begin_transaction(hard = false)
      # (native code)
    end

cas(key, oval, nval) click to toggle source

Perform compare-and-swap.

- @param key the key.

- @param oval the old value. nil means that no record corresponds.

- @param nval the new value. nil means that the record is removed.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 425
    def cas(key, oval, nval)
      # (native code)
    end

check(key) click to toggle source

Check the existence of a record.

- @param key the key.

- @return the size of the value, or -1 on failure.

    # File kyotocabinet.rb, line 444
    def check(key)
      # (native code)
    end

clear() click to toggle source

Remove all records.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 476
    def clear()
      # (native code)
    end

close() click to toggle source

Close the database file.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 339
    def close()
      # (native code)
    end

copy(dest) click to toggle source

Create a copy of the database file.

- @param dest the path of the destination file.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 499
    def copy(dest)
      # (native code)
    end

count() click to toggle source

Get the number of records.

- @return the number of records, or -1 on failure.

    # File kyotocabinet.rb, line 535
    def count()
      # (native code)
    end

cursor() click to toggle source

Create a cursor object.

- @return the return value is the created cursor object. Each cursor should be disabled with the Cursor#disable method when it is no longer in use.

    # File kyotocabinet.rb, line 585
    def cursor()
      # (native code)
    end

cursor_process() click to toggle source

Process a cursor by the block parameter.

- @block a block including operations for the cursor. The cursor is disabled implicitly after the block.

- @return always nil.

    # File kyotocabinet.rb, line 591
    def cursor_process()
      # (native code)
    end

delete(key, value) click to toggle source

An alias of DB#remove.

    # File kyotocabinet.rb, line 630
    def delete(key, value)
      # (native code)
    end

dump_snapshot(dest) click to toggle source

Dump records into a snapshot file.

- @param dest the name of the destination file.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 524
    def dump_snapshot(dest)
      # (native code)
    end

each() click to toggle source

Process each records with a iterator block.

- @block the iterator to receive the key and the value of each record.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 649
    def each()
      # (native code)
    end

each_key() click to toggle source

Process the key of each record with a iterator block.

- @block the iterator to receive the key of each record.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 655
    def each_key()
      # (native code)
    end

each_value() click to toggle source

Process the value of each record with a iterator block.

- @block the iterator to receive the value of each record.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 661
    def each_value()
      # (native code)
    end

end_transaction(commit = true) click to toggle source

End transaction.

- @param commit true to commit the transaction, or false to abort the transaction.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 511
    def end_transaction(commit = true)
      # (native code)
    end

error() click to toggle source

Get the last happened error.

- @return the last happened error.

    # File kyotocabinet.rb, line 326
    def error()
      # (native code)
    end

fetch(key, value) click to toggle source

An alias of DB#get.

    # File kyotocabinet.rb, line 634
    def fetch(key, value)
      # (native code)
    end

get(key) click to toggle source

Retrieve the value of a record.

- @param key the key.

- @return the value of the corresponding record, or nil on failure.

    # File kyotocabinet.rb, line 438
    def get(key)
      # (native code)
    end

get_bulk(keys, atomic = true) click to toggle source

Retrieve records at once.

- @param keys an array of the keys of the records to retrieve.

- @param atomic true to perform all operations atomically, or false for non-atomic operations.

- @return a hash of retrieved records, or nil on failure.

    # File kyotocabinet.rb, line 471
    def get_bulk(keys, atomic = true)
      # (native code)
    end

increment(key, num = 0, orig = 0) click to toggle source

Add a number to the numeric integer value of a record.

- @param key the key.

- @param num the additional number.

- @param orig the origin number if no record corresponds to the key. If it is negative infinity and no record corresponds, this method fails. If it is positive infinity, the value is set as the additional number regardless of the current value.

- @return the result value, or nil on failure.

- @note The value is serialized as an 8-byte binary integer in big-endian order, not a decimal string. If existing value is not 8-byte, this method fails.

    # File kyotocabinet.rb, line 408
    def increment(key, num = 0, orig = 0)
      # (native code)
    end

increment_double(key, num = 0, orig = 0) click to toggle source

Add a number to the numeric double value of a record.

- @param key the key.

- @param num the additional number.

- @param orig the origin number if no record corresponds to the key. If it is negative infinity and no record corresponds, this method fails. If it is positive infinity, the value is set as the additional number regardless of the current value.

- @return the result value, or nil on failure.

- @note The value is serialized as an 16-byte binary fixed-point number in big-endian order, not a decimal string. If existing value is not 16-byte, this method fails.

    # File kyotocabinet.rb, line 417
    def increment_double(key, num = 0, orig = 0)
      # (native code)
    end

inspect() click to toggle source

Get the inspection string.

- @return the inspection string.

    # File kyotocabinet.rb, line 614
    def inspect()
      # (native code)
    end

iterate(visitor, writable = true) click to toggle source

Iterate to accept a visitor for each record.

- @param visitor a visitor object which implements the Visitor interface. If it is omitted, the block parameter is evaluated.

- @param writable true for writable operation, or false for read-only operation.

- @block If it is specified, the block is called as the visitor.

- @return true on success, or false on failure.

- @note The whole iteration is performed atomically and other threads are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

    # File kyotocabinet.rb, line 367
    def iterate(visitor, writable = true)
      # (native code)
    end

length() click to toggle source

An alias of DB#count.

    # File kyotocabinet.rb, line 643
    def length()
      # (native code)
    end

load_snapshot(src) click to toggle source

Load records from a snapshot file.

- @param src the name of the source file.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 530
    def load_snapshot(src)
      # (native code)
    end

match_prefix(prefix, max = -1) click to toggle source

Get keys matching a prefix string.

- @param prefix the prefix string.

- @param max the maximum number to retrieve. If it is negative, no limit is specified.

- @return an array of matching keys, or nil on failure.

    # File kyotocabinet.rb, line 557
    def match_prefix(prefix, max = -1)
      # (native code)
    end

match_regex(regex, max = -1) click to toggle source

Get keys matching a regular expression string.

- @param regex the regular expression string.

- @param max the maximum number to retrieve. If it is negative, no limit is specified.

- @return an array of matching keys, or nil on failure.

    # File kyotocabinet.rb, line 564
    def match_regex(regex, max = -1)
      # (native code)
    end

match_similar(origin, range = 1, utf = false, max = -1) click to toggle source

Get keys similar to a string in terms of the levenshtein distance.

- @param origin the origin string.

- @param range the maximum distance of keys to adopt.

- @param utf flag to treat keys as UTF-8 strings.

- @param max the maximum number to retrieve. If it is negative, no limit is specified.

- @return an array of matching keys, or nil on failure.

    # File kyotocabinet.rb, line 573
    def match_similar(origin, range = 1, utf = false, max = -1)
      # (native code)
    end

merge(srcary, mode = DB::MSET) click to toggle source

Merge records from other databases.

- @param srcary an array of the source detabase objects.

- @param mode the merge mode. DB::MSET to overwrite the existing value, DB::MADD to keep the existing value, DB::MAPPEND to append the new value.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 580
    def merge(srcary, mode = DB::MSET)
      # (native code)
    end

occupy(writable = false, proc = nil) click to toggle source

Occupy database by locking and do something meanwhile.

- @param writable true to use writer lock, or false to use reader lock.

- @param proc a processor object which implements the FileProcessor interface. If it is nil, no processing is performed.

- @return true on success, or false on failure.

- @note The operation of the processor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

    # File kyotocabinet.rb, line 493
    def occupy(writable = false, proc = nil)
      # (native code)
    end

open(path = ":", mode = DB::OWRITER | DB::OCREATE) click to toggle source

Open a database file.

- @param path the path of a database file. If it is "-", the database will be a prototype hash database. If it is "+", the database will be a prototype tree database. If it is ":", the database will be a stash database. If it is "*", the database will be a cache hash database. If it is "%", the database will be a cache tree database. If its suffix is ".kch", the database will be a file hash database. If its suffix is ".kct", the database will be a file tree database. If its suffix is ".kcd", the database will be a directory hash database. If its suffix is ".kcf", the database will be a directory tree database. If its suffix is ".kcx", the database will be a plain text database. Otherwise, this function fails. Tuning parameters can trail the name, separated by "#". Each parameter is composed of the name and the value, separated by "=". If the "type" parameter is specified, the database type is determined by the value in "-", "+", ":", "*", "%", "kch", "kct", "kcd", kcf", and "kcx". All database types support the logging parameters of "log", "logkinds", and "logpx". The prototype hash database and the prototype tree database do not support any other tuning parameter. The stash database supports "bnum". The cache hash database supports "opts", "bnum", "zcomp", "capcnt", "capsiz", and "zkey". The cache tree database supports all parameters of the cache hash database except for capacity limitation, and supports "psiz", "rcomp", "pccap" in addition. The file hash database supports "apow", "fpow", "opts", "bnum", "msiz", "dfunit", "zcomp", and "zkey". The file tree database supports all parameters of the file hash database and "psiz", "rcomp", "pccap" in addition. The directory hash database supports "opts", "zcomp", and "zkey". The directory tree database supports all parameters of the directory hash database and "psiz", "rcomp", "pccap" in addition. The plain text database does not support any other tuning parameter.

- @param mode the connection mode. DB::OWRITER as a writer, DB::OREADER as a reader. The following may be added to the writer mode by bitwise-or: DB::OCREATE, which means it creates a new database if the file does not exist, DB::OTRUNCATE, which means it creates a new database regardless if the file exists, DB::OAUTOTRAN, which means each updating operation is performed in implicit transaction, DB::OAUTOSYNC, which means each updating operation is followed by implicit synchronization with the file system. The following may be added to both of the reader mode and the writer mode by bitwise-or: DB::ONOLOCK, which means it opens the database file without file locking, DB::OTRYLOCK, which means locking is performed without blocking, DB::ONOREPAIR, which means the database file is not repaired implicitly even if file destruction is detected.

- @return true on success, or false on failure.

- @note The tuning parameter "log" is for the original "tune_logger" and the value specifies the path of the log file, or "-" for the standard output, or "+" for the standard error. "logkinds" specifies kinds of logged messages and the value can be "debug", "info", "warn", or "error". "logpx" specifies the prefix of each log message. "opts" is for "tune_options" and the value can contain "s" for the small option, "l" for the linear option, and "c" for the compress option. "bnum" corresponds to "tune_bucket". "zcomp" is for "tune_compressor" and the value can be "zlib" for the ZLIB raw compressor, "def" for the ZLIB deflate compressor, "gz" for the ZLIB gzip compressor, "lzo" for the LZO compressor, "lzma" for the LZMA compressor, or "arc" for the Arcfour cipher. "zkey" specifies the cipher key of the compressor. "capcnt" is for "cap_count". "capsiz" is for "cap_size". "psiz" is for "tune_page". "rcomp" is for "tune_comparator" and the value can be "lex" for the lexical comparator, "dec" for the decimal comparator, "lexdesc" for the lexical descending comparator, or "decdesc" for the decimal descending comparator. "pccap" is for "tune_page_cache". "apow" is for "tune_alignment". "fpow" is for "tune_fbp". "msiz" is for "tune_map". "dfunit" is for "tune_defrag". Every opened database must be closed by the PolyDB::close method when it is no longer in use. It is not allowed for two or more database objects in the same process to keep their connections to the same database file at the same time.

    # File kyotocabinet.rb, line 334
    def open(path = ":", mode = DB::OWRITER | DB::OCREATE)
      # (native code)
    end

path() click to toggle source

Get the path of the database file.

- @return the path of the database file, or nil on failure.

    # File kyotocabinet.rb, line 545
    def path()
      # (native code)
    end

remove(key) click to toggle source

Remove a record.

- @param key the key.

- @return true on success, or false on failure.

- @note If no record corresponds to the key, false is returned.

    # File kyotocabinet.rb, line 432
    def remove(key)
      # (native code)
    end

remove_bulk(keys, atomic = true) click to toggle source

Remove records at once.

- @param keys an array of the keys of the records to remove.

- @param atomic true to perform all operations atomically, or false for non-atomic operations.

- @return the number of removed records, or -1 on failure.

    # File kyotocabinet.rb, line 464
    def remove_bulk(keys, atomic = true)
      # (native code)
    end

replace(key, value) click to toggle source

Replace the value of a record.

- @param key the key.

- @param value the value.

- @return true on success, or false on failure.

- @note If no record corresponds to the key, no new record is created and false is returned. If the corresponding record exists, the value is modified.

    # File kyotocabinet.rb, line 391
    def replace(key, value)
      # (native code)
    end

seize(key) click to toggle source

Retrieve the value of a record and remove it atomically.

- @param key the key.

- @return the value of the corresponding record, or nil on failure.

    # File kyotocabinet.rb, line 450
    def seize(key)
      # (native code)
    end

set(key, value) click to toggle source

Set the value of a record.

- @param key the key.

- @param value the value.

- @return true on success, or false on failure.

- @note If no record corresponds to the key, a new record is created. If the corresponding record exists, the value is overwritten.

    # File kyotocabinet.rb, line 375
    def set(key, value)
      # (native code)
    end

set_bulk(recs, atomic = true) click to toggle source

Store records at once.

- @param recs a hash of the records to store.

- @param atomic true to perform all operations atomically, or false for non-atomic operations.

- @return the number of stored records, or -1 on failure.

    # File kyotocabinet.rb, line 457
    def set_bulk(recs, atomic = true)
      # (native code)
    end

shift() click to toggle source

Remove the first record.

- @return a pair of the key and the value of the removed record, or nil on failure.

    # File kyotocabinet.rb, line 639
    def shift()
      # (native code)
    end

size() click to toggle source

Get the size of the database file.

- @return the size of the database file in bytes, or -1 on failure.

    # File kyotocabinet.rb, line 540
    def size()
      # (native code)
    end

status() click to toggle source

Get the miscellaneous status information.

- @return a hash of the status information, or nil on failure.

    # File kyotocabinet.rb, line 550
    def status()
      # (native code)
    end

store(key, value) click to toggle source

An alias of DB#store.

    # File kyotocabinet.rb, line 626
    def store(key, value)
      # (native code)
    end

synchronize(hard = false, proc = nil) click to toggle source

Synchronize updated contents with the file and the device.

- @param hard true for physical synchronization with the device, or false for logical synchronization with the file system.

- @param proc a postprocessor object which implements the FileProcessor interface. If it is nil, no postprocessing is performed.

- @block If it is specified, the block is called for postprocessing.

- @return true on success, or false on failure.

- @note The operation of the processor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this method.

    # File kyotocabinet.rb, line 485
    def synchronize(hard = false, proc = nil)
      # (native code)
    end

to_s() click to toggle source

Get the string expression.

- @return the string expression.

    # File kyotocabinet.rb, line 609
    def to_s()
      # (native code)
    end

transaction(hard = false) click to toggle source

Perform entire transaction by the block parameter.

- @param hard true for physical synchronization with the device, or false for logical synchronization with the file system.

- @block a block including operations during transaction. If the block returns true, the transaction is committed. If the block returns false or an exception is thrown, the transaction is aborted.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 518
    def transaction(hard = false)
      # (native code)
    end

tune_encoding(enc) click to toggle source

Set the encoding of external strings.

- @param enc the name of the encoding or its encoding object.

- @note The default encoding of external strings is Encoding::ASCII_8BIT.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 604
    def tune_encoding(enc)
      # (native code)
    end

tune_exception_rule(codes) click to toggle source

Set the rule about throwing exception.

- @param codes an array of error codes. If each method occurs an error corresponding to one of the specified codes, the error is thrown as an exception.

- @return true on success, or false on failure.

    # File kyotocabinet.rb, line 597
    def tune_exception_rule(codes)
      # (native code)
    end

Generated with the Darkfish Rdoc Generator 2.