Project

General

Profile

Bug #6410 ยป 0003-Add-documentation-for-SDBM.patch

revisions from zzak - zzak (Zachary Scott), 05/11/2012 12:36 AM

View differences:

ext/sdbm/init.c
121 121
* call-seq:
122 122
*     sdbm.closed? -> true or false
123 123
*
124
* Returns true if the database is closed.
124
* Returns +true+ if the database is closed.
125 125
*/
126 126
static VALUE
127 127
fsdbm_closed(VALUE obj)
......
146 146
* call-seq:
147 147
*      SDBM.new(filename, mode = 0666)
148 148
*
149
* Creates a new database handle by opening the given _filename_. sdbm actually
149
* Creates a new database handle by opening the given _filename_. SDBM actually
150 150
* uses two physical files, with extensions '.dir' and '.pag'. These extensions
151 151
* will automatically be appended to the _filename_.
152 152
*
153
* 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.
153
* If the file does not exist, a new file will be created using the given
154
* _mode_, unless _mode_ is explicitly set to nil. In the latter case, no
155
* database will be created.
154 156
*
155
* If the file exists, it will be opened in read/write mode. If this fails, it will be opened in read-only mode.
157
* If the file exists, it will be opened in read/write mode. If this fails, it
158
* will be opened in read-only mode.
156 159
*/
157 160
static VALUE
158 161
fsdbm_initialize(int argc, VALUE *argv, VALUE obj)
......
200 203
 *      SDBM.open(filename, mode = 0666)
201 204
 *      SDBM.open(filename, mode = 0666) { |sdbm| ... }
202 205
 *
203
 * If called without a block, this is the same as SDBM.new.
206
 * If called without a _block_, this is the same as SDBM.new.
204 207
 *
205
 * If a block is given, the new database will be passed to the block and
206
 * will be safely closed after the block has executed.
208
 * If a _block_ is given, the new database will be passed to the _block_ and
209
 * will be safely closed after the _block_ has executed.
207 210
 *
208 211
 * Example:
209 212
 *
......
254 257
 * call-seq:
255 258
 *      sdbm[key] -> value or nil
256 259
 *
257
 * Returns the value in the database associated with the given _key_ string.
260
 * Returns the _value_ in the database associated with the given _key_ string.
258 261
 *
259
 * If no value is found, returns nil.
262
 * If no value is found, returns +nil+.
260 263
 */
261 264
static VALUE
262 265
fsdbm_aref(VALUE obj, VALUE keystr)
......
269 272
 *      sdbm.fetch(key) -> value or nil
270 273
 *      sdbm.fetch(key) { |key| ... }
271 274
 *
272
 * Returns the value in the database associated with the given _key_ string.
275
 * Returns the _value_ in the database associated with the given _key_ string.
273 276
 *
274
 * If a block is provided, the block will be called when there is no value
277
 * If a _block_ is provided, the _block_ will be called when there is no _value_
275 278
 * associated with the given _key_. The _key_ will be passed in as an argument to
276
 * the block.
279
 * the _block_.
277 280
 *
278
 * If no block is provided and no value is associated with the given  _key_,
281
 * If no _block_ is provided and no value is associated with the given _key_,
279 282
 * then an IndexError will be raised.
280 283
 */
281 284
static VALUE
......
295 298
 * call-seq:
296 299
 *      sdbm.key(value) -> key
297 300
 *
298
 * Returns the key associated with the given _value_. If more than one
299
 * key corresponds to the given value, then the first key to be found
300
 * will be returned. If no keys are found, nil will be returned.
301
 * Returns the _key_ associated with the given _value_. If more than one
302
 * _key_ corresponds to the given _value_, then the first key to be found
303
 * will be returned. If no keys are found, +nil+ will be returned.
301 304
 */
302 305
static VALUE
303 306
fsdbm_key(VALUE obj, VALUE valstr)
......
321 324
}
322 325

  
323 326
/*
324
 * call-seq:
325
 *      sdbm.index(value) -> key
326
 *
327
 * This method is the same as SDBM#key and has been deprecated.
327
 * :nodoc:
328 328
 */
329 329
static VALUE
330 330
fsdbm_index(VALUE hash, VALUE value)
......
334 334
}
335 335

  
336 336
/* call-seq:
337
 *      sdbm.select { |key, value| block } -> array
337
 *      sdbm.select { |key, value| block } -> Array
338 338
 *
339
 * Returns a new array of key-value pairs for which the _block_ returns
340
 * true.
339
 * Returns a new Array of key-value pairs for which the _block_ returns +true+.
341 340
 *
342 341
 * Example:
343 342
 *
......
350 349
 *
351 350
 *      veggies = db.select do |key, value|
352 351
 *        value == 'vegetable'
353
 *      end                    #=> [["apple", "fruit"], ["pear", "fruit"]]
352
 *      end #=> [["apple", "fruit"], ["pear", "fruit"]]
354 353
 *    end
355 354
 */
356 355
static VALUE
......
378 377
}
379 378

  
380 379
/* call-seq:
381
 *      sdbm.values_at(key, ...) -> array
380
 *      sdbm.values_at(key, ...) -> Array
382 381
 *
383
 * Returns an array of values corresponding to the given keys.
382
 * Returns an Array of values corresponding to the given keys.
384 383
 */
385 384
static VALUE
386 385
fsdbm_values_at(int argc, VALUE *argv, VALUE obj)
......
407 406
 *      sdbm.delete(key) -> value or nil
408 407
 *      sdbm.delete(key) { |key, value| ... }
409 408
 *
410
 * Deletes the kay-value pair corresponding to the given _key_. If the
411
 * key exists, the deleted value will be returned, otherwise nil.
409
 * Deletes the key-value pair corresponding to the given _key_. If the
410
 * _key_ exists, the deleted value will be returned, otherwise +nil+.
412 411
 *
413
 * If a block is provided, the deleted key and value will be passed to the
414
 * block as arguments. If the key does not exist in the database, the
415
 * value will be nil.
412
 * If a _block_ is provided, the deleted _key_ and _value_ will be passed to
413
 * the _block_ as arguments. If the _key_ does not exist in the database, the
414
 * value will be +nil+.
416 415
 */
417 416
static VALUE
418 417
fsdbm_delete(VALUE obj, VALUE keystr)
......
451 450

  
452 451
/*
453 452
 * call-seq:
454
 *      sdbm.shift -> array or nil
453
 *      sdbm.shift -> Array or nil
455 454
 *
456 455
 * Removes a key-value pair from the database and returns them as an
457
 * array. If the database is empty, returns nil.
456
 * Array. If the database is empty, returns +nil+.
458 457
 */
459 458
static VALUE
460 459
fsdbm_shift(VALUE obj)
......
485 484
 *      sdbm.reject! { |key, value| block } -> self
486 485
 *
487 486
 * Iterates over the key-value pairs in the database, deleting those for
488
 * which the _block_ returns true.
487
 * which the _block_ returns +true+.
489 488
 */
490 489
static VALUE
491 490
fsdbm_delete_if(VALUE obj)
......
591 590
 * call-seq:
592 591
 *      sdbm.store(key, value) -> value
593 592
 *
594
 * Stores a new value in the database with the given _key_ as an index.
593
 * Stores a new _value_ in the database with the given _key_ as an index.
595 594
 *
596
 * If the key already exists, this will update the value associated with
597
 * the key.
595
 * If the _key_ already exists, this will update the _value_ associated with
596
 * the _key_.
598 597
 *
599 598
 * Returns the given _value_.
600 599
 */
......
707 706
 * call-seq:
708 707
 *      sdbm.empty? -> true or false
709 708
 *
710
 * Returns true if the database is empty.
709
 * Returns +true+ if the database is empty.
711 710
 */
712 711
static VALUE
713 712
fsdbm_empty_p(VALUE obj)
......
737 736
 *      sdbm.each_value
738 737
 *      sdbm.each_value { |value| ... }
739 738
 *
740
 * Iterates over each value in the database.
739
 * Iterates over each _value_ in the database.
741 740
 *
742
 * If no block is given, returns an Enumerator.
741
 * If no _block_ is given, returns an Enumerator.
743 742
 */
744 743
static VALUE
745 744
fsdbm_each_value(VALUE obj)
......
764 763
 *      sdbm.each_key
765 764
 *      sdbm.each_key { |key| ... }
766 765
 *
767
 * Iterates over each key in the database.
766
 * Iterates over each _key_ in the database.
768 767
 *
769
 * If no block is given, returns an Enumerator.
768
 * If no _block_ is given, returns an Enumerator.
770 769
 */
771 770
static VALUE
772 771
fsdbm_each_key(VALUE obj)
......
792 791
 *
793 792
 * Iterates over each key-value pair in the database.
794 793
 *
795
 * If no block is given, returns an Enumerator.
794
 * If no _block_ is given, returns an Enumerator.
796 795
 */
797 796
static VALUE
798 797
fsdbm_each_pair(VALUE obj)
......
818 817

  
819 818
/*
820 819
 * call-seq:
821
 *      sdbm.keys -> array
820
 *      sdbm.keys -> Array
822 821
 *
823
 * Returns a new array containing the keys in the database.
822
 * Returns a new Array containing the keys in the database.
824 823
 */
825 824
static VALUE
826 825
fsdbm_keys(VALUE obj)
......
841 840

  
842 841
/*
843 842
 * call-seq:
844
 *      sdbm.values -> array
843
 *      sdbm.values -> Array
845 844
 *
846
 * Returns a new array containing the values in the database.
845
 * Returns a new Array containing the values in the database.
847 846
 */
848 847
static VALUE
849 848
fsdbm_values(VALUE obj)
......
867 866
 * call-seq:
868 867
 *      sdbm.has_key?(key) -> true or false
869 868
 *
870
 * Returns true if the database contains the given _key_.
869
 * Returns +true+ if the database contains the given _key_.
871 870
 */
872 871
static VALUE
873 872
fsdbm_has_key(VALUE obj, VALUE keystr)
......
890 889
 * call-seq:
891 890
 *      sdbm.has_value?(key) -> true or false
892 891
 *
893
 * Returns true if the database contains the given _value_.
892
 * Returns +true+ if the database contains the given _value_.
894 893
 */
895 894
static VALUE
896 895
fsdbm_has_value(VALUE obj, VALUE valstr)
......
915 914

  
916 915
/*
917 916
 * call-seq:
918
 *      sdbm.to_a -> array
917
 *      sdbm.to_a -> Array
919 918
 *
920
 * Returns a new array containing each key-value pair in the database.
919
 * Returns a new Array containing each key-value pair in the database.
921 920
 *
922 921
 * Example:
923 922
 *
......
979 978
 *
980 979
 * Creates a new Hash using the key-value pairs from the database, then
981 980
 * calls Hash#reject with the given _block_, which returns a Hash with
982
 * only the key-value pairs for which the block returns false.
981
 * only the key-value pairs for which the _block_ returns +false+.
983 982
 */
984 983
static VALUE
985 984
fsdbm_reject(VALUE obj)
986
-