Project

General

Profile

Bug #5656 ยป 01-better-range-documentation.patch

zetter (Chris Zetter), 11/22/2011 08:08 AM

View differences:

range.c (working copy)
68 68

  
69 69
/*
70 70
 *  call-seq:
71
 *     Range.new(start, end, exclusive=false)    -> range
71
 *     Range.new(begin, end, exclude_end=false)    -> rng
72 72
 *
73
 *  Constructs a range using the given <i>start</i> and <i>end</i>. If the third
74
 *  parameter is omitted or is <code>false</code>, the <i>range</i> will include
73
 *  Constructs a range using the given +begin+ and +end+. If the +exclude_end+
74
 *  parameter is omitted or is <code>false</code>, the +rng+ will include
75 75
 *  the end object; otherwise, it will be excluded.
76 76
 */
77 77

  
......
95 95
 *  call-seq:
96 96
 *     rng.exclude_end?    -> true or false
97 97
 *
98
 *  Returns <code>true</code> if <i>rng</i> excludes its end value.
98
 *  Returns <code>true</code> if the range excludes its end value.
99
 *
100
 *     (1..5).exclude_end?     #=> false
101
 *     (1...5).exclude_end?    #=> true
99 102
 */
100 103

  
101 104
static VALUE
......
123 126
 *  call-seq:
124 127
 *     rng == obj    -> true or false
125 128
 *
126
 *  Returns <code>true</code> only if <i>obj</i> is a Range, has equivalent
127
 *  beginning and end items (by comparing them with <code>==</code>), and has
128
 *  the same <code>exclude_end?</code> setting as <i>rng</i>.
129
 *  Returns <code>true</code> only if +obj+ is a Range, has equivalent
130
 *  begin and end items (by comparing them with <code>==</code>), and has
131
 *  the same #exclude_end? setting as the range.
129 132
 *
130 133
 *    (0..2) == (0..2)            #=> true
131 134
 *    (0..2) == Range.new(0,2)    #=> true
......
191 194
 *  call-seq:
192 195
 *     rng.eql?(obj)    -> true or false
193 196
 *
194
 *  Returns <code>true</code> only if <i>obj</i> is a Range, has equivalent
195
 *  beginning and end items (by comparing them with #eql?), and has the same
196
 *  #exclude_end? setting as <i>rng</i>.
197
 *  Returns <code>true</code> only if +obj+ is a Range, has equivalent
198
 *  begin and end items (by comparing them with <code>eql?</code>),
199
 *  and has the same #exclude_end? setting as the range.
197 200
 *
198 201
 *    (0..2).eql?(0..2)            #=> true
199 202
 *    (0..2).eql?(Range.new(0,2))  #=> true
......
234 237
 * call-seq:
235 238
 *   rng.hash    -> fixnum
236 239
 *
237
 * Generate a hash value such that two ranges with the same start and
238
 * end points, and the same value for the "exclude end" flag, generate
239
 * the same hash value.
240
 * Compute a hash-code for this range. Two ranges with equal
241
 * begin and end points (using <code>eql?</code>), and the same
242
 * #exclude_end? value will generate the same hash-code.
240 243
 */
241 244

  
242 245
static VALUE
......
318 321
 *     rng.step(n=1) {| obj | block }    -> rng
319 322
 *     rng.step(n=1)                     -> an_enumerator
320 323
 *
321
 *  Iterates over <i>rng</i>, passing each <i>n</i>th element to the block. If
322
 *  the range contains numbers, <i>n</i> is added for each iteration.  Otherwise
323
 *  <code>step</code> invokes <code>succ</code> to iterate through range
324
 *  elements. The following code uses class <code>Xs</code>, which is defined
325
 *  in the class-level documentation.
324
 *  Iterates over the range, passing each <code>n</code>th element to the block.
325
 *  If begin and end are numeric, +n+ is added for each iteration.
326
 *  Otherwise <code>step</code> invokes <code>succ</code> to iterate through
327
 *  range elements.
326 328
 *
327 329
 *  If no block is given, an enumerator is returned instead.
328 330
 *
329
 *     range = Xs.new(1)..Xs.new(10)
330
 *     range.step(2) {|x| puts x}
331
 *     range.step(3) {|x| puts x}
331
 *     (3..10).step(3) {|n| puts n }
332 332
 *
333 333
 *  <em>produces:</em>
334 334
 *
335
 *      1 x
336
 *      3 xxx
337
 *      5 xxxxx
338
 *      7 xxxxxxx
339
 *      9 xxxxxxxxx
340
 *      1 x
341
 *      4 xxxx
342
 *      7 xxxxxxx
343
 *     10 xxxxxxxxxx
335
 *      3
336
 *      6
337
 *      9
344 338
 */
345 339

  
346 340

  
......
455 449
 *     rng.each {| i | block } -> rng
456 450
 *     rng.each                -> an_enumerator
457 451
 *
458
 *  Iterates over the elements <i>rng</i>, passing each in turn to the
459
 *  block. You can only iterate if the start object of the range
460
 *  supports the +succ+ method (which means that you can't iterate over
461
 *  ranges of +Float+ objects).
452
 *  Iterates over the elements of range, passing each in turn to the
453
 *  block.
462 454
 *
455
 *  The +each+ method can only be used if the begin object of the range
456
 *  supports the +succ+ method. A TypeError is raised if the object
457
 *  does not have +succ+ method defined.
458
 *
463 459
 *  If no block is given, an enumerator is returned instead.
460
 *     (10..15).each {|n| print n, ' ' }
461
 *     # prints: 10 11 12 13 14 15
464 462
 *
465
 *     (10..15).each do |n|
466
 *        print n, ' '
467
 *     end
468
 *
469
 *  <em>produces:</em>
470
 *
471
 *     10 11 12 13 14 15
463
 *     ((2.5)..5).each {|n| print n, ' ' }
464
 *     # raises: TypeError: can't iterate from Float
472 465
 */
473 466

  
474 467
static VALUE
......
523 516
 *  call-seq:
524 517
 *     rng.begin    -> obj
525 518
 *
526
 *  Returns the first object in <i>rng</i>.
519
 *  Returns the object that defines the beginning of the range.
520
 *
521
 *      (1..10).begin   #=> 1
527 522
 */
528 523

  
529 524
static VALUE
......
537 532
 *  call-seq:
538 533
 *     rng.end    -> obj
539 534
 *
540
 *  Returns the object that defines the end of <i>rng</i>.
535
 *  Returns the object that defines the end of the range.
541 536
 *
542 537
 *     (1..10).end    #=> 10
543 538
 *     (1...10).end   #=> 10
......
570 565
 *     rng.first    -> obj
571 566
 *     rng.first(n) -> an_array
572 567
 *
573
 *  Returns the first object in <i>rng</i>, or the first +n+ elements.
568
 *  Returns the first object in the range,
569
 *  or an array of the first +n+ elements.
570
 *
571
 *    (10..20).first     #=> 10
572
 *    (10..20).first(3)  #=> [10, 11, 12]
574 573
 */
575 574

  
576 575
static VALUE
......
594 593
 *     rng.last    -> obj
595 594
 *     rng.last(n) -> an_array
596 595
 *
597
 *  Returns the last object in <i>rng</i>, or the last +n+ elements.
596
 *  Returns the last object in the range,
597
 *  or an array of the last +n+ elements.
598
 *
599
 *  Note that with no arguments +last+ will return the object that defines
600
 *  the end of the range even if #exclude_end? is +true+.
601
 *
602
 *    (10..20).last      #=> 20
603
 *    (10...20).last     #=> 20
604
 *    (10..20).last(3)   #=> [18, 19, 20]
605
 *    (10...20).last(3)  #=> [17, 18, 19]
598 606
 */
599 607

  
600 608
static VALUE
......
610 618
 *     rng.min                    -> obj
611 619
 *     rng.min {| a,b | block }   -> obj
612 620
 *
613
 *  Returns the minimum value in <i>rng</i>. The second uses
614
 *  the block to compare values.  Returns nil if the first
615
 *  value in range is larger than the last value.
621
 *  Returns the minimum value in the range. Returns +nil+ if the begin
622
 *  value of the range is larger than the end value.
616 623
 *
624
 *  Can be given an optional block to override the default comparison
625
 *  method <code>a <=> b</code>.
626
 *
627
 *    (10..20).min    #=> 10
617 628
 */
618 629

  
619 630

  
......
639 650
 *     rng.max                    -> obj
640 651
 *     rng.max {| a,b | block }   -> obj
641 652
 *
642
 *  Returns the maximum value in <i>rng</i>. The second uses
643
 *  the block to compare values.  Returns nil if the first
644
 *  value in range is larger than the last value.
653
 *  Returns the maximum value in the range. Returns +nil+ if the begin
654
 *  value of the range larger than the end value.
645 655
 *
656
 *  Can be given an optional block to override the default comparison
657
 *  method <code>a <=> b</code>.
658
 *
659
 *    (10..20).max    #=> 20
646 660
 */
647 661

  
648 662
static VALUE
......
749 763
 * call-seq:
750 764
 *   rng.to_s   -> string
751 765
 *
752
 * Convert this range object to a printable form.
766
 * Convert this range object to a printable form (using
767
 * <code>to_s</code> to convert the begin and end objects).
753 768
 */
754 769

  
755 770
static VALUE
......
790 805
 *   rng.inspect  -> string
791 806
 *
792 807
 * Convert this range object to a printable form (using
793
 * <code>inspect</code> to convert the start and end
808
 * <code>inspect</code> to convert the begin and end
794 809
 * objects).
795 810
 */
796 811

  
......
805 820
 *  call-seq:
806 821
 *     rng === obj       ->  true or false
807 822
 *
808
 *  Returns <code>true</code> if <i>obj</i> is an element of
809
 *  <i>rng</i>, <code>false</code> otherwise. Conveniently,
810
 *  <code>===</code> is the comparison operator used by
811
 *  <code>case</code> statements.
812
 *
813
 *     case 79
814
 *     when 1..50   then   print "low\n"
815
 *     when 51..75  then   print "medium\n"
816
 *     when 76..100 then   print "high\n"
817
 *     end
818
 *
819
 *  <em>produces:</em>
820
 *
821
 *     high
823
 *  Returns <code>true</code> if +obj+ is an element of
824
 *  the range, <code>false</code> otherwise.
822 825
 */
823 826

  
824 827
static VALUE
......
830 833

  
831 834
/*
832 835
 *  call-seq:
833
 *     rng.member?(val)  ->  true or false
834
 *     rng.include?(val) ->  true or false
836
 *     rng.member?(obj)  ->  true or false
837
 *     rng.include?(obj) ->  true or false
835 838
 *
836
 *  Returns <code>true</code> if <i>obj</i> is an element of
837
 *  <i>rng</i>, <code>false</code> otherwise.  If beg and end are
838
 *  numeric, comparison is done according magnitude of values.
839
 *  Returns <code>true</code> if +obj+ is an element of
840
 *  the range, <code>false</code> otherwise.  If begin and end are
841
 *  numeric, comparison is done according to the magnitude of the values.
839 842
 *
840
 *     ("a".."z").include?("g")  # -> true
841
 *     ("a".."z").include?("A")  # -> false
843
 *     ("a".."z").include?("g")   #=> true
844
 *     ("a".."z").include?("A")   #=> false
845
 *     ("a".."z").include?("cc")  #=> false
842 846
 */
843 847

  
844 848
static VALUE
......
891 895

  
892 896
/*
893 897
 *  call-seq:
894
 *     rng.cover?(val)  ->  true or false
898
 *     rng.cover?(obj)  ->  true or false
895 899
 *
896
 *  Returns <code>true</code> if <i>obj</i> is between beg and end,
897
 *  i.e <code>beg <= obj <= end</code> (or <i>end</i> exclusive when
898
 *  <code>exclude_end?</code> is true).
900
 *  Returns <code>true</code> if +obj+ is between the begin and end of
901
 *  the range.
899 902
 *
903
 *  This tests <code>begin <= obj <= end</code> when #exclude_end? is +false+
904
 *  and <code>begin <= obj < end</code> when #exclude_end? is +true+.
905
 *
900 906
 *     ("a".."z").cover?("c")    #=> true
901 907
 *     ("a".."z").cover?("5")    #=> false
908
 *     ("a".."z").cover?("cc")   #=> true
902 909
 */
903 910

  
904 911
static VALUE
......
958 965
}
959 966

  
960 967
/*  A <code>Range</code> represents an interval---a set of values with a
961
 *  start and an end. Ranges may be constructed using the
968
 *  beginning and an end. Ranges may be constructed using the
962 969
 *  <em>s</em><code>..</code><em>e</em> and
963 970
 *  <em>s</em><code>...</code><em>e</em> literals, or with
964
 *  <code>Range::new</code>. Ranges constructed using <code>..</code>
965
 *  run from the start to the end inclusively. Those created using
971
 *  Range::new. Ranges constructed using <code>..</code>
972
 *  run from the beginning to the end inclusively. Those created using
966 973
 *  <code>...</code> exclude the end value. When used as an iterator,
967 974
 *  ranges return each value in the sequence.
968 975
 *
......
971 978
 *     ('a'..'e').to_a    #=> ["a", "b", "c", "d", "e"]
972 979
 *     ('a'...'e').to_a   #=> ["a", "b", "c", "d"]
973 980
 *
974
 *  Ranges can be constructed using objects of any type, as long as the
975
 *  objects can be compared using their <code><=></code> operator and
976
 *  they support the <code>succ</code> method to return the next object
977
 *  in sequence.
981
 *  == Custom Objects in Ranges
982
 *  Ranges can be constructed using any objects that can be compared
983
 *  using the <code><=></code> operator.
984
 *  Methods that treat the range as a sequence (#each and methods inherited
985
 *  from Enumerable) expect the begin object to implement a
986
 *  <code>succ</code> method to return the next object in sequence.
987
 *  The #step and #include? methods require the begin
988
 *  object to implement <code>succ</code> or to be numeric.
978 989
 *
990
 *  In the <code>Xs</code> class below both <code><=></code> and
991
 *  <code>succ</code> are implemented so <code>Xs</code> can be used
992
 *  to construct ranges. Note that the Comparable module is included
993
 *  so the <code>==</code> method is defined in terms of <code><=></code>.
994
 *
979 995
 *     class Xs                # represent a string of 'x's
980 996
 *       include Comparable
981 997
 *       attr :length
......
988 1004
 *       def <=>(other)
989 1005
 *         @length <=> other.length
990 1006
 *       end
991
 *       def to_s
992
 *         sprintf "%2d #{inspect}", @length
993
 *       end
994 1007
 *       def inspect
995 1008
 *         'x' * @length
996 1009
 *       end
997 1010
 *     end
998 1011
 *
1012
 *  A example of using <code>Xs</code> to construct a range follows:
1013
 *
999 1014
 *     r = Xs.new(3)..Xs.new(6)   #=> xxx..xxxxxx
1000 1015
 *     r.to_a                     #=> [xxx, xxxx, xxxxx, xxxxxx]
1001 1016
 *     r.member?(Xs.new(5))       #=> true
1002 1017
 *
1003
 *  In the previous code example, class <code>Xs</code> includes the
1004
 *  <code>Comparable</code> module. This is because
1005
 *  <code>Enumerable#member?</code> checks for equality using
1006
 *  <code>==</code>. Including <code>Comparable</code> ensures that the
1007
 *  <code>==</code> method is defined in terms of the <code><=></code>
1008
 *  method implemented in <code>Xs</code>.
1018
 *  == Ranges in Case Statements
1009 1019
 *
1020
 *  When Ranges are compared to other objects using the <code>===</code>
1021
 *  operator <code>true</code> is returned if the object is an element
1022
 *  of range, <code>false</code> otherwise. Since <code>===</code> is
1023
 *  the comparison operator used by <code>case</code> statements this
1024
 *  allows ranges to be used as conditions in case statements such as
1025
 *  in the following:
1026
 *
1027
 *     case 79
1028
 *     when 1..50   then   puts "low"
1029
 *     when 51..75  then   puts "medium"
1030
 *     when 76..100 then   puts "high"
1031
 *     end
1032
 *
1033
 *  <em>produces:</em>
1034
 *
1035
 *     high
1036
 *
1010 1037
 */
1011 1038

  
1012 1039
void