8000 [ruby/csv] Enhanced RDoc for CSV::Table (#165) · ruby/ruby@7deff88 · GitHub
[go: up one dir, main page]
Skip to content

Commit 7deff88

Browse files
BurdetteLamarkou
BurdetteLamar
authored and
kou
committed
[ruby/csv] Enhanced RDoc for CSV::Table (#165)
ruby/csv@bce4b696a7
1 parent 72997f4 commit 7deff88

File tree

1 file changed

+101
-18
lines changed

1 file changed

+101
-18
lines changed

‎lib/csv/table.rb

Lines changed: 101 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -333,7 +333,7 @@ def []=(index_or_header, value)
333333
#
334334
# ---
335335
#
336-
# Returns columns data as Arrays,
336+
# Returns columns data as row Arrays,
337337
# each consisting of the specified columns data for that row:
338338
# values = table.values_at('Name')
339339
# values # => [["foo"], ["bar"], ["baz"]]
@@ -399,11 +399,46 @@ def push(*rows)
399399
self # for chaining
400400
end
401401

402+
# :call-seq:
403+
# table.delete(*indexes) -> deleted_values
404+
# table.delete(*headers) -> deleted_values
405+
#
406+
# If the access mode is <tt>:row</tt> or <tt>:col_or_row</tt>,
407+
# and each argument is either an \Integer or a \Range,
408+
# returns deleted rows.
409+
# Otherwise, returns deleted columns data.
410+
#
411+
# In either case, the returned values are in the order
412+
# specified by the arguments. Arguments may be repeated.
413+
#
414+
# ---
402415
#
403-
# Removes and returns the indicated columns or rows. In the default mixed
404-
# mode indices refer to rows and everything else is assumed to be a column
405-
# headers. Use by_col!() or by_row!() to force the lookup.
416+
# Returns rows as an \Array of \CSV::Row objects.
406417
#
418+
# One index:
419+
# source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
420+
# table = CSV.parse(source, headers: true)
421+
# deleted_values = table.delete(0)
422+
# deleted_values # => [#<CSV::Row "Name":"foo" "Value":"0">]
423+
#
424+
# Two indexes:
425+
# table = CSV.parse(source, headers: true)
426+
# deleted_values = table.delete(2, 0)
427+
# deleted_values # => [#<CSV::Row "Name":"baz" "Value":"2">, #<CSV::Row "Name":"foo" "Value":"0">]
428+
#
429+
# ---
430+
#
431+
# Returns columns data as column Arrays.
432+
#
433+
# One header:
434+
# table = CSV.parse(source, headers: true)
435+
# deleted_values = table.delete('Name')
436+
# deleted_values # => ["foo", "bar", "baz"]
437+
#
438+
# Two headers:
439+
# table = CSV.parse(source, headers: true)
440+
# deleted_values = table.delete('Value', 'Name')
441+
# deleted_values # => [["0", "1", "2"], ["foo", "bar", "baz"]]
407442
def delete(*indexes_or_headers)
408443
if indexes_or_headers.empty?
409444
raise ArgumentError, "wrong number of arguments (given 0, expected 1+)"
@@ -428,16 +463,32 @@ def delete(*indexes_or_headers)
428463
end
429464
end
430465

466+
# Removes rows or columns for which the block returns a truthy value;
467+
# returns +self+.
431468
#
432-
# Removes any column or row for which the block returns +true+. In the
433-
# default mixed mode or row mode, iteration is the standard row major
434-
# walking of rows. In column mode, iteration will +yield+ two element
435-
# tuples containing the column name and an Array of values for that column.
436-
#
437-
# This method returns the table for chaining.
469+
# Removes rows when the access mode is <tt>:row</tt> or <tt>:col_or_row</tt>;
470+
# calls the block with each \CSV::Row object:
471+
# source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
472+
# table = CSV.parse(source, headers: true)
473+
# table.by_row! # => #<CSV::Table mode:row row_count:4>
474+
# table.size # => 3
475+
# table.delete_if {|row| row['Name'].start_with?('b') }
476+
# table.size # => 1
438477
#
439-
# If no block is given, an Enumerator is returned.
478+
# Removes columns when the access mode is <tt>:col</tt>;
479+
# calls the block with each column as a 2-element array
480+
# containing the header and an \Array of column fields:
481+
# source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
482+
# table = CSV.parse(source, headers: true)
483+
# table.by_col! # => #<CSV::Table mode:col row_count:4>
484+
# table.headers.size # => 2
485+
# table.delete_if {|column_data| column_data[1].include?('2') }
486+
# table.headers.size # => 1
440487
#
488+
# Returns a new \Enumerator if no block is given:
489+
# source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
490+
# table = CSV.parse(source, headers: true)
491+
# table.delete_if # => #<Enumerator: #<CSV::Table mode:col_or_row row_count:4>:delete_if>
441492
def delete_if(&block)
442493
return enum_for(__method__) { @mode == :row or @mode == :col_or_row ? size : headers.size } unless block_given?
443494

@@ -455,15 +506,30 @@ def delete_if(&block)
455506

456507
include Enumerable
457508

509+
# Calls the block with each row or column; returns +self+.
458510
#
459-
# In the default mixed mode or row mode, iteration is the standard row major
460-
# walking of rows. In column mode, iteration will +yield+ two element
461-
# tuples containing the column name and an Array of values for that column.
462-
#
463-
# This method returns the table for chaining.
511+
# When the access mode is <tt>:row</tt> or <tt>:col_or_row</tt>,
512+
# calls the block with each \CSV::Row object:
513+
# source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
514+
# table = CSV.parse(source, headers: true)
515+
# table.by_row! # => #<CSV::Table mode:row row_count:4>
516+
# table.each {|row| p row }
517+
# Output:
518+
# #<CSV::Row "Name":"foo" "Value":"0">
519+
# #<CSV::Row "Name":"bar" "Value":"1">
520+
# #<CSV::Row "Name":"baz" "Value":"2">
464521
#
465-
# If no block is given, an Enumerator is returned.
522+
# When the access mode is <tt>:col</tt>,
523+
# calls the block with each column as a 2-element array
524+
# containing the header and an \Array of column fields:
525+
# table.by_col! # => #<CSV::Table mode:col row_count:4>
526+
# table.each {|column_data| p column_data }
527+
# Output:
528+
# ["Name", ["foo", "bar", "baz"]]
529+
# ["Value", ["0", "1", "2"]]
466530
#
531+
# Returns a new \Enumerator if no block is given:
532+
# table.each # => #<Enumerator: #<CSV::Table mode:col row_count:4>:each>
467533
def each(&block)
468534
return enum_for(__method__) { @mode == :col ? headers.size : size } unless block_given?
469535

@@ -476,7 +542,24 @@ def each(&block)
476542
self # for chaining
477543
end
478544

479-
# Returns +true+ if all rows of this table ==() +other+'s rows.
545+
# Returns +true+ if all each row of +self+ <tt>==</tt>
546+
# the corresponding row of +other_table+, otherwise, +false+.
547+
#
548+
# The access mode does no affect the result.
549+
#
550+
# Equal tables:
551+
# source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
552+
# table = CSV.parse(source, headers: true)
553+
# other_table = CSV.parse(source, headers: true)
554+
# table == other_table # => true
555+
#
556+
# Different row count:
557+
# other_table.delete(2)
558+
# table == other_table # => false
559+
#
560+
# Different last row:
561+
# other_table << ['bat', 3]
562+
# table == other_table # => false
480563
def ==(other)
481564
return @table == other.table if other.is_a? CSV::Table
482565
@table == other

0 commit comments

Comments
 (0)
0