Project

General

Profile

Download (11 KB)

Bug #3968 ยป dbm-docs.diff

Output of svn diff - meta (mathew murphy), 10/20/2010 08:33 AM

View differences:

dbm.c (working copy)
DBM *di_dbm;
};
/* call-seq: closed?
*
* Returns true if the database is closed, false otherwise.
*/
static void
closed_dbm(void)
{
......
}
}
/* Closes the database. */
static VALUE
fdbm_close(VALUE obj)
{
......
return Data_Wrap_Struct(klass, 0, free_dbm, 0);
}
/* call-seq: new(filename, mode, flags) -> DBM
*
* 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.
*/
static VALUE
fdbm_initialize(int argc, VALUE *argv, VALUE obj)
{
......
return obj;
}
/*
* Alias for new()
*/
static VALUE
fdbm_s_open(int argc, VALUE *argv, VALUE klass)
{
......
return rb_tainted_str_new(value.dptr, value.dsize);
}
/* call-seq: hash[key] -> value
*
* Alias for fetch()
*/
static VALUE
fdbm_aref(VALUE obj, VALUE keystr)
{
return fdbm_fetch(obj, keystr, Qnil);
}
/* call-seq: fetch(key) -> string value or nil
*
* Return a value from the database by locating the key string provided.
* If the key is not found, returns nil.
*/
static VALUE
fdbm_fetch_m(int argc, VALUE *argv, VALUE obj)
{
......
return valstr;
}
/* call-seq: key(value) -> string
*
* Returns the key for the specified value.
*/
static VALUE
fdbm_key(VALUE obj, VALUE valstr)
{
......
return fdbm_key(hash, value);
}
/* call-seq: select {|key, value| block} -> array
*
* Returns a new array consisting of the [key, value] pairs for which the code
* block returns true.
*/
static VALUE
fdbm_select(VALUE obj)
{
......
return new;
}
/* call-seq:
* values_at(key, ...) -> Array
*
* Returns an array containing the values associated with the given keys.
*/
static VALUE
fdbm_values_at(int argc, VALUE *argv, VALUE obj)
{
......
if (OBJ_FROZEN(obj)) rb_error_frozen("DBM");
}
/* call-seq: delete(key)
*
* Deletes an entry from the database.
*/
static VALUE
fdbm_delete(VALUE obj, VALUE keystr)
{
......
return valstr;
}
/* call-seq: shift() -> [key, value]
*
* 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.
*/
static VALUE
fdbm_shift(VALUE obj)
{
......
return rb_assoc_new(keystr, valstr);
}
/*
* call-seq:
* hash.reject! {|key, value| block} -> self
* hash.delete_if {|key, value| block} -> self
*
* Deletes all entries for which the code block returns true.
* Returns self.
*/
static VALUE
fdbm_delete_if(VALUE obj)
{
......
return obj;
}
/* Deletes all data from the database. */
static VALUE
fdbm_clear(VALUE obj)
{
......
return obj;
}
/* 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.
*/
static VALUE
fdbm_invert(VALUE obj)
{
......
return hash;
}
/* call-seq: hash[key] = value
*
* Alias for store()
*/
static VALUE fdbm_store(VALUE,VALUE,VALUE);
static VALUE
......
return Qnil;
}
/* call-seq: update(obj)
*
* Updates the database with multiple values from the specified object.
* Takes any object which implements the each_pair method, including
* Hash and DBM objects.
*/
static VALUE
fdbm_update(VALUE obj, VALUE other)
{
......
return obj;
}
/* call-seq: replace(obj)
*
* 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.
*/
static VALUE
fdbm_replace(VALUE obj, VALUE other)
{
......
return obj;
}
/* call-seq: store(key, value)
*
* Stores the specified string value in the database, indexed via the
* string key provided.
*/
static VALUE
fdbm_store(VALUE obj, VALUE keystr, VALUE valstr)
{
......
return valstr;
}
/* Returns the number of entries in the database. */
static VALUE
fdbm_length(VALUE obj)
{
......
return INT2FIX(i);
}
/* call-seq: empty?
*
* Returns true if the database is empty, false otherwise.
*/
static VALUE
fdbm_empty_p(VALUE obj)
{
......
return Qfalse;
}
/* call-seq: each_value {|value| block} -> self
*
* Calls the block once for each value string in the database. Returns self.
*/
static VALUE
fdbm_each_value(VALUE obj)
{
......
return obj;
}
/* call-seq: each_key {|key| block} -> self
*
* Calls the block once for each key string in the database. Returns self.
*/
static VALUE
fdbm_each_key(VALUE obj)
{
......
return obj;
}
/* call-seq: each_pair {|key,value| block} -> self
*
* Calls the block once for each [key, value] pair in the database.
* Returns self.
*/
static VALUE
fdbm_each_pair(VALUE obj)
{
......
return obj;
}
/* Returns an array of all the string keys in the database. */
static VALUE
fdbm_keys(VALUE obj)
{
......
return ary;
}
/* Returns an array of all the string values in the database. */
static VALUE
fdbm_values(VALUE obj)
{
......
return ary;
}
/* call-seq: has_key?(key) -> boolean
*
* Returns true if the database contains the specified key, false otherwise.
*/
static VALUE
fdbm_has_key(VALUE obj, VALUE keystr)
{
......
return Qfalse;
}
/* call-seq: has_value?(value) -> boolean
*
* Returns true if the database contains the specified string value, false
* otherwise.
*/
static VALUE
fdbm_has_value(VALUE obj, VALUE valstr)
{
......
return Qfalse;
}
/* Converts the contents of the database to an array of [key, value] arrays,
* and returns it.
*/
static VALUE
fdbm_to_a(VALUE obj)
{
......
return ary;
}
/* Converts the contents of the database to an in-memory Hash object, and
* returns it.
*/
static VALUE
fdbm_to_hash(VALUE obj)
{
......
return hash;
}
/* call-seq: reject {|key,value| block} -> Hash
*
* Converts the contents of the database to an in-memory Hash, then calls
* Hash#reject with the specified code block, returning a new Hash.
*/
static VALUE
fdbm_reject(VALUE obj)
{
return rb_hash_delete_if(fdbm_to_hash(obj));
}
/* Written by nobu.
* Copyright (C) 1995-2001 Yukihiro Matsumoto.
* Documented by mathew meta@pobox.com.
*
* = Introduction
*
* The DBM class provides a wrapper to a Unix-style
* {dbm}[http://en.wikipedia.org/wiki/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:
*
* - {Berkeley DB}[http://en.wikipedia.org/wiki/Berkeley_DB] versions
* 1 thru 5, also known as BDB and Sleepycat DB, now owned by Oracle
* Corporation.
* - ndbm, aka Berkeley DB 1.x, still found in FreeBSD and OpenBSD.
* - {gdbm}[http://www.gnu.org/software/gdbm/], the GNU implementation of dbm.
* - {qdbm}[http://fallabs.com/qdbm/index.html], 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', 666, DBM::CREATRW)
* 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']
*/
void
Init_dbm(void)
{
rb_cDBM = rb_define_class("DBM", rb_cObject);
/* Document-class: DBMError
* Exception class used to return errors from the dbm library.
*/
rb_eDBMError = rb_define_class("DBMError", rb_eStandardError);
rb_include_module(rb_cDBM, rb_mEnumerable);
......
rb_define_method(rb_cDBM, "to_a", fdbm_to_a, 0);
rb_define_method(rb_cDBM, "to_hash", fdbm_to_hash, 0);
/* flags for dbm_open() */
/* Indicates that dbm_open() should open the database in read-only mode */
rb_define_const(rb_cDBM, "READER", INT2FIX(O_RDONLY|RUBY_DBM_RW_BIT));
/* Indicates that dbm_open() should open the database in read/write mode */
rb_define_const(rb_cDBM, "WRITER", INT2FIX(O_RDWR|RUBY_DBM_RW_BIT));
/* Indicates that dbm_open() should open the database in read/write mode,
* and create it if it does not already exist
*/
rb_define_const(rb_cDBM, "WRCREAT", INT2FIX(O_RDWR|O_CREAT|RUBY_DBM_RW_BIT));
/* Indicates that dbm_open() should open the database in read/write mode,
* create it if it does not already exist, and delete all contents if it
* does already exist.
*/
rb_define_const(rb_cDBM, "NEWDB", INT2FIX(O_RDWR|O_CREAT|O_TRUNC|RUBY_DBM_RW_BIT));
#ifdef DB_VERSION_STRING
/* The version of the dbm library, if using Berkeley DB */
rb_define_const(rb_cDBM, "VERSION", rb_str_new2(DB_VERSION_STRING));
#else
rb_define_const(rb_cDBM, "VERSION", rb_str_new2("unknown"));
    (1-1/1)