1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

* ext/gdbm/gdbm.c: add RDoc documentation. a patch from Peter

Browse Source 
Adolphs <futzilogik at users dot sourceforge dot net>.
  [ruby-doc:1223]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@10965 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
matz 2006-09-20 00:30:38 +00:00
parent eede22f0bb
commit d3f545235a
2 changed files with 413 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
ChangeLog
View File

@ -1,3 +1,9 @@
Wed Sep 20 09:25:39 2006 Yukihiro Matsumoto <matz@ruby-lang.org>
* ext/gdbm/gdbm.c: add RDoc documentation. a patch from Peter
Adolphs <futzilogik at users dot sourceforge dot net>.
[ruby-doc:1223]
Tue Sep 19 00:42:15 2006 Nobuyoshi Nakada <nobu@ruby-lang.org> Tue Sep 19 00:42:15 2006 Nobuyoshi Nakada <nobu@ruby-lang.org>
* object.c (rb_obj_ivar_defined, rb_mod_cvar_defined): new methods, * object.c (rb_obj_ivar_defined, rb_mod_cvar_defined): new methods,

340
ext/gdbm/gdbm.c
View File

@ -6,6 +6,8 @@
$Date$ $Date$
modified at: Mon Jan 24 15:59:52 JST 1994 modified at: Mon Jan 24 15:59:52 JST 1994
Documentation by Peter Adolphs < futzilogik at users dot sourceforge dot net >
************************************************/ ************************************************/
#include "ruby.h" #include "ruby.h"
@ -14,6 +16,62 @@
#include <fcntl.h> #include <fcntl.h>
#include <errno.h> #include <errno.h>
/*
* Document-class: GDBM
*
* == 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 <tt>[]</tt>.
* 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
*
* 1. 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
*
* 2. 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
*
* * http://www.gnu.org/software/gdbm/
*/
static VALUE rb_cGDBM, rb_eGDBMError, rb_eGDBMFatalError; static VALUE rb_cGDBM, rb_eGDBMError, rb_eGDBMFatalError;
#define RUBY_GDBM_RW_BIT 0x20000000 #define RUBY_GDBM_RW_BIT 0x20000000
@ -57,6 +115,12 @@ free_dbm(struct dbmdata *dbmp)
} }
} }
/*
* call-seq:
* gdbm.close -> nil
*
* Closes the associated database file.
*/
static VALUE static VALUE
fgdbm_close(VALUE obj) fgdbm_close(VALUE obj)
{ {
@ -69,6 +133,12 @@ fgdbm_close(VALUE obj)
return Qnil; return Qnil;
} }
/*
* call-seq:
* gdbm.closed? -> true or false
*
* Returns true if the associated database file has been closed.
*/
static VALUE static VALUE
fgdbm_closed(VALUE obj) fgdbm_closed(VALUE obj)
{ {
@ -89,6 +159,29 @@ fgdbm_s_alloc(VALUE klass)
return Data_Wrap_Struct(klass, 0, free_dbm, 0); return Data_Wrap_Struct(klass, 0, free_dbm, 0);
} }
/*
* call-seq:
* GDBM.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 <tt>WRCREAT</tt>). 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 <tt>READER</tt>).
*/
static VALUE static VALUE
fgdbm_initialize(int argc, VALUE *argv, VALUE obj) fgdbm_initialize(int argc, VALUE *argv, VALUE obj)
{ {
@ -101,7 +194,7 @@ fgdbm_initialize(int argc, VALUE *argv, VALUE obj)
mode = 0666; /* default value */ mode = 0666; /* default value */
} }
else if (NIL_P(vmode)) { else if (NIL_P(vmode)) {
mode = -1; /* return nil if DB not exist */ mode = -1; /* return nil if DB does not exist */
} }
else { else {
mode = NUM2INT(vmode); mode = NUM2INT(vmode);
@ -150,6 +243,25 @@ fgdbm_initialize(int argc, VALUE *argv, VALUE obj)
return obj; return obj;
} }
/*
* call-seq:
* GDBM.open(filename, mode = 0666, flags = nil)
* GDBM.open(filename, mode = 0666, flags = nil) { |gdbm| ... }
*
* If called without a block, this is synonymous to GDBM::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
*/
static VALUE static VALUE
fgdbm_s_open(int argc, VALUE *argv, VALUE klass) fgdbm_s_open(int argc, VALUE *argv, VALUE klass)
{ {
@ -251,12 +363,25 @@ fgdbm_fetch(VALUE obj, VALUE keystr, VALUE ifnone)
return valstr; return valstr;
} }
/*
* call-seq:
* gdbm[key] -> value
*
* Retrieves the _value_ corresponding to _key_.
*/
static VALUE static VALUE
fgdbm_aref(VALUE obj, VALUE keystr) fgdbm_aref(VALUE obj, VALUE keystr)
{ {
return rb_gdbm_fetch3(obj, keystr); return rb_gdbm_fetch3(obj, keystr);
} }
/*
* call-seq:
* gdbm.fetch(key [, default]) -> value
*
* Retrieves the _value_ corresponding to _key_. If there is no value
* associated with _key_, _default_ will be returned instead.
*/
static VALUE static VALUE
fgdbm_fetch_m(int argc, VALUE *argv, VALUE obj) fgdbm_fetch_m(int argc, VALUE *argv, VALUE obj)
{ {
@ -270,6 +395,13 @@ fgdbm_fetch_m(int argc, VALUE *argv, VALUE obj)
return valstr; return valstr;
} }
/*
* call-seq:
* gdbm.index(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.
*/
static VALUE static VALUE
fgdbm_index(VALUE obj, VALUE valstr) fgdbm_index(VALUE obj, VALUE valstr)
{ {
@ -293,6 +425,13 @@ fgdbm_index(VALUE obj, VALUE valstr)
return Qnil; return Qnil;
} }
/*
* call-seq:
* gdbm.select { |value| block } -> array
*
* Returns a new array of all values of the database for which _block_
* evaluates to true.
*/
static VALUE static VALUE
fgdbm_select(VALUE obj) fgdbm_select(VALUE obj)
{ {
@ -316,6 +455,12 @@ fgdbm_select(VALUE obj)
return new; return new;
} }
/*
* call-seq:
* gdbm.values_at(key, ...) -> array
*
* Returns an array of the values associated with each specified _key_.
*/
static VALUE static VALUE
fgdbm_values_at(int argc, VALUE *argv, VALUE obj) fgdbm_values_at(int argc, VALUE *argv, VALUE obj)
{ {
@ -363,6 +508,13 @@ rb_gdbm_delete(VALUE obj, VALUE keystr)
return obj; return obj;
} }
/*
* call-seq:
* gdbm.delete(key) -> value or nil
*
* Removes the key-value-pair with the specified _key_ from this database and
* returns the corresponding _value_. Returns nil if the database is empty.
*/
static VALUE static VALUE
fgdbm_delete(VALUE obj, VALUE keystr) fgdbm_delete(VALUE obj, VALUE keystr)
{ {
@ -373,6 +525,13 @@ fgdbm_delete(VALUE obj, VALUE keystr)
return valstr; return valstr;
} }
/*
* call-seq:
* gdbm.shift -> (key, value) or nil
*
* 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.
*/
static VALUE static VALUE
fgdbm_shift(VALUE obj) fgdbm_shift(VALUE obj)
{ {
@ -390,6 +549,13 @@ fgdbm_shift(VALUE obj)
return rb_assoc_new(keystr, valstr); return rb_assoc_new(keystr, valstr);
} }
/*
* call-seq:
* gdbm.delete_if { |key, value| block } -> gdbm
* gdbm.reject! { |key, value| block } -> gdbm
*
* Deletes every key-value pair from _gdbm_ for which _block_ evaluates to true.
*/
static VALUE static VALUE
fgdbm_delete_if(VALUE obj) fgdbm_delete_if(VALUE obj)
{ {
@ -422,6 +588,12 @@ fgdbm_delete_if(VALUE obj)
return obj; return obj;
} }
/*
* call-seq:
* gdbm.clear -> gdbm
*
* Removes all the key-value pairs within _gdbm_.
*/
static VALUE static VALUE
fgdbm_clear(VALUE obj) fgdbm_clear(VALUE obj)
{ {
@ -459,6 +631,13 @@ fgdbm_clear(VALUE obj)
return obj; return obj;
} }
/*
* call-seq:
* gdbm.invert -> hash
*
* Returns a hash created by using _gdbm_'s values as keys, and the keys
* as values.
*/
static VALUE static VALUE
fgdbm_invert(VALUE obj) fgdbm_invert(VALUE obj)
{ {
@ -477,6 +656,13 @@ fgdbm_invert(VALUE obj)
return hash; return hash;
} }
/*
* call-seq:
* gdbm[key]= value -> value
* gdbm.store(key, value) -> value
*
* Associates the value _value_ with the specified _key_.
*/
static VALUE static VALUE
fgdbm_store(VALUE obj, VALUE keystr, VALUE valstr) fgdbm_store(VALUE obj, VALUE keystr, VALUE valstr)
{ {
@ -515,6 +701,14 @@ update_i(VALUE pair, VALUE dbm)
return Qnil; return Qnil;
} }
/*
* call-seq:
* gdbm.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.
*/
static VALUE static VALUE
fgdbm_update(VALUE obj, VALUE other) fgdbm_update(VALUE obj, VALUE other)
{ {
@ -522,6 +716,13 @@ fgdbm_update(VALUE obj, VALUE other)
return obj; return obj;
} }
/*
* call-seq:
* gdbm.replace(other) -> gdbm
*
* Replaces the content of _gdbm_ with the key-value pairs of _other_.
* _other_ must have an each_pair method.
*/
static VALUE static VALUE
fgdbm_replace(VALUE obj, VALUE other) fgdbm_replace(VALUE obj, VALUE other)
{ {
@ -530,6 +731,13 @@ fgdbm_replace(VALUE obj, VALUE other)
return obj; return obj;
} }
/*
* call-seq:
* gdbm.length -> fixnum
* gdbm.size -> fixnum
*
* Returns the number of key-value pairs in this database.
*/
static VALUE static VALUE
fgdbm_length(VALUE obj) fgdbm_length(VALUE obj)
{ {
@ -551,6 +759,12 @@ fgdbm_length(VALUE obj)
return INT2FIX(i); return INT2FIX(i);
} }
/*
* call-seq:
* gdbm.empty? -> true or false
*
* Returns true if the database is empty.
*/
static VALUE static VALUE
fgdbm_empty_p(VALUE obj) fgdbm_empty_p(VALUE obj)
{ {
@ -574,6 +788,13 @@ fgdbm_empty_p(VALUE obj)
return Qfalse; return Qfalse;
} }
/*
* call-seq:
* gdbm.each_value { |value| block } -> gdbm
*
* Executes _block_ for each key in the database, passing the corresponding
* _value_ as a parameter.
*/
static VALUE static VALUE
fgdbm_each_value(VALUE obj) fgdbm_each_value(VALUE obj)
{ {
@ -591,6 +812,13 @@ fgdbm_each_value(VALUE obj)
return obj; return obj;
} }
/*
* call-seq:
* gdbm.each_key { |key| block } -> gdbm
*
* Executes _block_ for each key in the database, passing the
* _key_ as a parameter.
*/
static VALUE static VALUE
fgdbm_each_key(VALUE obj) fgdbm_each_key(VALUE obj)
{ {
@ -608,6 +836,13 @@ fgdbm_each_key(VALUE obj)
return obj; return obj;
} }
/*
* call-seq:
* gdbm.each_pair { |key, value| block } -> gdbm
*
* Executes _block_ for each key in the database, passing the _key_ and the
* correspoding _value_ as a parameter.
*/
static VALUE static VALUE
fgdbm_each_pair(VALUE obj) fgdbm_each_pair(VALUE obj)
{ {
@ -626,6 +861,12 @@ fgdbm_each_pair(VALUE obj)
return obj; return obj;
} }
/*
* call-seq:
* gdbm.keys -> array
*
* Returns an array of all keys of this database.
*/
static VALUE static VALUE
fgdbm_keys(VALUE obj) fgdbm_keys(VALUE obj)
{ {
@ -644,6 +885,12 @@ fgdbm_keys(VALUE obj)
return ary; return ary;
} }
/*
* call-seq:
* gdbm.values -> array
*
* Returns an array of all values of this database.
*/
static VALUE static VALUE
fgdbm_values(VALUE obj) fgdbm_values(VALUE obj)
{ {
@ -664,6 +911,14 @@ fgdbm_values(VALUE obj)
return ary; return ary;
} }
/*
* call-seq:
* gdbm.has_key?(k) -> true or false
* gdbm.key?(k) -> true or false
*
* Returns true if the given key _k_ exists within the database.
* Returns false otherwise.
*/
static VALUE static VALUE
fgdbm_has_key(VALUE obj, VALUE keystr) fgdbm_has_key(VALUE obj, VALUE keystr)
{ {
@ -681,6 +936,14 @@ fgdbm_has_key(VALUE obj, VALUE keystr)
return Qfalse; return Qfalse;
} }
/*
* call-seq:
* gdbm.has_value?(v) -> true or false
* gdbm.value?(v) -> true or false
*
* Returns true if the given value _v_ exists within the database.
* Returns false otherwise.
*/
static VALUE static VALUE
fgdbm_has_value(VALUE obj, VALUE valstr) fgdbm_has_value(VALUE obj, VALUE valstr)
{ {
@ -705,6 +968,12 @@ fgdbm_has_value(VALUE obj, VALUE valstr)
return Qfalse; return Qfalse;
} }
/*
* call-seq:
* gdbm.to_a -> array
*
* Returns an array of all key-value pairs contained in the database.
*/
static VALUE static VALUE
fgdbm_to_a(VALUE obj) fgdbm_to_a(VALUE obj)
{ {
@ -723,6 +992,14 @@ fgdbm_to_a(VALUE obj)
return ary; return ary;
} }
/*
* call-seq:
* gdbm.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.
*/
static VALUE static VALUE
fgdbm_reorganize(VALUE obj) fgdbm_reorganize(VALUE obj)
{ {
@ -735,6 +1012,16 @@ fgdbm_reorganize(VALUE obj)
return obj; return obj;
} }
/*
* call-seq:
* gdbm.sync -> gdbm
*
* Unless the _gdbm_ object has been opened with the *SYNC* flag, it is not
* guarenteed 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.
*/
static VALUE static VALUE
fgdbm_sync(VALUE obj) fgdbm_sync(VALUE obj)
{ {
@ -747,6 +1034,12 @@ fgdbm_sync(VALUE obj)
return obj; return obj;
} }
/*
* call-seq:
* gdbm.cachesize = size -> size
*
* Sets the size of the internal bucket cache to _size_.
*/
static VALUE static VALUE
fgdbm_set_cachesize(VALUE obj, VALUE val) fgdbm_set_cachesize(VALUE obj, VALUE val)
{ {
@ -762,6 +1055,16 @@ fgdbm_set_cachesize(VALUE obj, VALUE val)
return val; return val;
} }
/*
* call-seq:
* gdbm.fastmode = boolean -> boolean
*
* 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=
*/
static VALUE static VALUE
fgdbm_set_fastmode(VALUE obj, VALUE val) fgdbm_set_fastmode(VALUE obj, VALUE val)
{ {
@ -780,6 +1083,19 @@ fgdbm_set_fastmode(VALUE obj, VALUE val)
return val; return val;
} }
/*
* call-seq:
* gdbm.syncmode = boolean -> boolean
*
* 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=
*/
static VALUE static VALUE
fgdbm_set_syncmode(VALUE obj, VALUE val) fgdbm_set_syncmode(VALUE obj, VALUE val)
{ {
@ -803,6 +1119,12 @@ fgdbm_set_syncmode(VALUE obj, VALUE val)
#endif #endif
} }
/*
* call-seq:
* gdbm.to_hash -> hash
*
* Returns a hash of all key-value pairs contained in the database.
*/
static VALUE static VALUE
fgdbm_to_hash(VALUE obj) fgdbm_to_hash(VALUE obj)
{ {
@ -821,6 +1143,13 @@ fgdbm_to_hash(VALUE obj)
return hash; return hash;
} }
/*
* call-seq:
* gdbm.reject { |key, value| block } -> 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
*/
static VALUE static VALUE
fgdbm_reject(VALUE obj) fgdbm_reject(VALUE obj)
{ {
@ -883,22 +1212,29 @@ Init_gdbm(void)
rb_define_method(rb_cGDBM, "to_a", fgdbm_to_a, 0); rb_define_method(rb_cGDBM, "to_a", fgdbm_to_a, 0);
rb_define_method(rb_cGDBM, "to_hash", fgdbm_to_hash, 0); rb_define_method(rb_cGDBM, "to_hash", fgdbm_to_hash, 0);
/* flags for gdbm_open() */ /* flag for #new and #open: open database as a reader */
rb_define_const(rb_cGDBM, "READER", INT2FIX(GDBM_READER|RUBY_GDBM_RW_BIT)); rb_define_const(rb_cGDBM, "READER", INT2FIX(GDBM_READER|RUBY_GDBM_RW_BIT));
/* flag for #new and #open: open database as a writer */
rb_define_const(rb_cGDBM, "WRITER", INT2FIX(GDBM_WRITER|RUBY_GDBM_RW_BIT)); rb_define_const(rb_cGDBM, "WRITER", INT2FIX(GDBM_WRITER|RUBY_GDBM_RW_BIT));
/* flag for #new and #open: open database as a writer; if the database does not exist, create a new one */
rb_define_const(rb_cGDBM, "WRCREAT", INT2FIX(GDBM_WRCREAT|RUBY_GDBM_RW_BIT)); rb_define_const(rb_cGDBM, "WRCREAT", INT2FIX(GDBM_WRCREAT|RUBY_GDBM_RW_BIT));
/* flag for #new and #open: open database as a writer; overwrite any existing databases */
rb_define_const(rb_cGDBM, "NEWDB", INT2FIX(GDBM_NEWDB|RUBY_GDBM_RW_BIT)); rb_define_const(rb_cGDBM, "NEWDB", INT2FIX(GDBM_NEWDB|RUBY_GDBM_RW_BIT));
/* flag for #new and #open. this flag is obsolete for gdbm >= 1.8 */
rb_define_const(rb_cGDBM, "FAST", INT2FIX(GDBM_FAST)); rb_define_const(rb_cGDBM, "FAST", INT2FIX(GDBM_FAST));
/* this flag is obsolete in gdbm 1.8. /* this flag is obsolete in gdbm 1.8.
On gdbm 1.8, fast mode is default behavior. */ On gdbm 1.8, fast mode is default behavior. */
/* gdbm version 1.8 specific */ /* gdbm version 1.8 specific */
#if defined(GDBM_SYNC) #if defined(GDBM_SYNC)
/* flag for #new and #open. only for gdbm >= 1.8 */
rb_define_const(rb_cGDBM, "SYNC", INT2FIX(GDBM_SYNC)); rb_define_const(rb_cGDBM, "SYNC", INT2FIX(GDBM_SYNC));
#endif #endif
#if defined(GDBM_NOLOCK) #if defined(GDBM_NOLOCK)
/* flag for #new and #open */
rb_define_const(rb_cGDBM, "NOLOCK", INT2FIX(GDBM_NOLOCK)); rb_define_const(rb_cGDBM, "NOLOCK", INT2FIX(GDBM_NOLOCK));
#endif #endif
/* version of the gdbm library*/
rb_define_const(rb_cGDBM, "VERSION", rb_str_new2(gdbm_version)); rb_define_const(rb_cGDBM, "VERSION", rb_str_new2(gdbm_version));
} }