Project

General

Profile

Bug #5393 ยป 0001-more-consistent-doc-block-style-for-enum.c.patch

enum.c doc patch - bt (Bernd Homuth), 10/04/2011 03:32 PM

View differences:

enum.c
60 60

  
61 61
/*
62 62
 *  call-seq:
63
 *     enum.grep(pattern)                   -> array
64
 *     enum.grep(pattern) {| obj | block }  -> array
63
 *     enum.grep(pattern)                  -> array
64
 *     enum.grep(pattern) { |obj| block }  -> array
65 65
 *
66 66
 *  Returns an array of every element in <i>enum</i> for which
67 67
 *  <code>Pattern === element</code>. If the optional <em>block</em> is
......
71 71
 *     (1..100).grep 38..44   #=> [38, 39, 40, 41, 42, 43, 44]
72 72
 *     c = IO.constants
73 73
 *     c.grep(/SEEK/)         #=> [:SEEK_SET, :SEEK_CUR, :SEEK_END]
74
 *     res = c.grep(/SEEK/) {|v| IO.const_get(v) }
74
 *     res = c.grep(/SEEK/) { |v| IO.const_get(v) }
75 75
 *     res                    #=> [0, 1, 2]
76 76
 *
77 77
 */
......
125 125

  
126 126
/*
127 127
 *  call-seq:
128
 *     enum.count                   -> int
129
 *     enum.count(item)             -> int
130
 *     enum.count {| obj | block }  -> int
128
 *     enum.count                 -> int
129
 *     enum.count(item)           -> int
130
 *     enum.count { |obj| block } -> int
131 131
 *
132 132
 *  Returns the number of items in <i>enum</i>, where #size is called
133 133
 *  if it responds to it, otherwise the items are counted through
......
136 136
 *  given, counts the number of elements yielding a true value.
137 137
 *
138 138
 *     ary = [1, 2, 4, 2]
139
 *     ary.count             #=> 4
140
 *     ary.count(2)          #=> 2
141
 *     ary.count{|x|x%2==0}  #=> 3
139
 *     ary.count               #=> 4
140
 *     ary.count(2)            #=> 2
141
 *     ary.count{ |x| x%2==0 } #=> 3
142 142
 *
143 143
 */
144 144

  
......
183 183

  
184 184
/*
185 185
 *  call-seq:
186
 *     enum.detect(ifnone = nil) {| obj | block }  -> obj or nil
187
 *     enum.find(ifnone = nil)   {| obj | block }  -> obj or nil
188
 *     enum.detect(ifnone = nil)                   -> an_enumerator
189
 *     enum.find(ifnone = nil)                     -> an_enumerator
186
 *     enum.detect(ifnone = nil) { |obj| block } -> obj or nil
187
 *     enum.find(ifnone = nil)   { |obj| block } -> obj or nil
188
 *     enum.detect(ifnone = nil)                 -> an_enumerator
189
 *     enum.find(ifnone = nil)                   -> an_enumerator
190 190
 *
191 191
 *  Passes each entry in <i>enum</i> to <em>block</em>. Returns the
192 192
 *  first for which <em>block</em> is not false.  If no
......
195 195
 *
196 196
 *  If no block is given, an enumerator is returned instead.
197 197
 *
198
 *     (1..10).detect  {|i| i % 5 == 0 and i % 7 == 0 }   #=> nil
199
 *     (1..100).detect {|i| i % 5 == 0 and i % 7 == 0 }   #=> 35
198
 *     (1..10).detect  { |i| i % 5 == 0 and i % 7 == 0 }   #=> nil
199
 *     (1..100).detect { |i| i % 5 == 0 and i % 7 == 0 }   #=> 35
200 200
 *
201 201
 */
202 202

  
......
248 248

  
249 249
/*
250 250
 *  call-seq:
251
 *     enum.find_index(value)            -> int or nil
252
 *     enum.find_index {| obj | block }  -> int or nil
253
 *     enum.find_index                   -> an_enumerator
251
 *     enum.find_index(value)          -> int or nil
252
 *     enum.find_index { |obj| block } -> int or nil
253
 *     enum.find_index                 -> an_enumerator
254 254
 *
255 255
 *  Compares each entry in <i>enum</i> with <em>value</em> or passes
256 256
 *  to <em>block</em>.  Returns the index for the first for which the
......
259 259
 *
260 260
 *  If neither block nor argument is given, an enumerator is returned instead.
261 261
 *
262
 *     (1..10).find_index  {|i| i % 5 == 0 and i % 7 == 0 }   #=> nil
263
 *     (1..100).find_index {|i| i % 5 == 0 and i % 7 == 0 }   #=> 34
262
 *     (1..10).find_index  { |i| i % 5 == 0 and i % 7 == 0 }  #=> nil
263
 *     (1..100).find_index { |i| i % 5 == 0 and i % 7 == 0 }  #=> 34
264 264
 *     (1..100).find_index(50)                                #=> 49
265 265
 *
266 266
 */
......
302 302

  
303 303
/*
304 304
 *  call-seq:
305
 *     enum.find_all {| obj | block }  -> array
306
 *     enum.select   {| obj | block }  -> array
307
 *     enum.find_all                   -> an_enumerator
308
 *     enum.select                     -> an_enumerator
305
 *     enum.find_all { |obj| block } -> array
306
 *     enum.select   { |obj| block } -> array
307
 *     enum.find_all                 -> an_enumerator
308
 *     enum.select                   -> an_enumerator
309 309
 *
310 310
 *  Returns an array containing all elements of <i>enum</i> for which
311 311
 *  <em>block</em> is not <code>false</code> (see also
......
314 314
 *  If no block is given, an enumerator is returned instead.
315 315
 *
316 316
 *
317
 *     (1..10).find_all {|i|  i % 3 == 0 }   #=> [3, 6, 9]
317
 *     (1..10).find_all { |i|  i % 3 == 0 }   #=> [3, 6, 9]
318 318
 *
319 319
 */
320 320

  
......
344 344

  
345 345
/*
346 346
 *  call-seq:
347
 *     enum.reject {| obj | block }  -> array
348
 *     enum.reject                   -> an_enumerator
347
 *     enum.reject { |obj| block } -> array
348
 *     enum.reject                 -> an_enumerator
349 349
 *
350 350
 *  Returns an array for all elements of <i>enum</i> for which
351 351
 *  <em>block</em> is false (see also <code>Enumerable#find_all</code>).
352 352
 *
353 353
 *  If no block is given, an enumerator is returned instead.
354 354
 *
355
 *     (1..10).reject {|i|  i % 3 == 0 }   #=> [1, 2, 4, 5, 7, 8, 10]
355
 *     (1..10).reject { |i|  i % 3 == 0 }   #=> [1, 2, 4, 5, 7, 8, 10]
356 356
 *
357 357
 */
358 358

  
......
388 388

  
389 389
/*
390 390
 *  call-seq:
391
 *     enum.collect {| obj | block }  -> array
392
 *     enum.map     {| obj | block }  -> array
393
 *     enum.collect                   -> an_enumerator
394
 *     enum.map                       -> an_enumerator
391
 *     enum.collect { |obj| block } -> array
392
 *     enum.map     { |obj| block } -> array
393
 *     enum.collect                 -> an_enumerator
394
 *     enum.map                     -> an_enumerator
395 395
 *
396 396
 *  Returns a new array with the results of running <em>block</em> once
397 397
 *  for every element in <i>enum</i>.
398 398
 *
399 399
 *  If no block is given, an enumerator is returned instead.
400 400
 *
401
 *     (1..4).collect {|i| i*i }   #=> [1, 4, 9, 16]
401
 *     (1..4).collect { |i| i*i }  #=> [1, 4, 9, 16]
402 402
 *     (1..4).collect { "cat"  }   #=> ["cat", "cat", "cat", "cat"]
403 403
 *
404 404
 */
......
435 435

  
436 436
/*
437 437
 *  call-seq:
438
 *     enum.flat_map       {| obj | block }  -> array
439
 *     enum.collect_concat {| obj | block }  -> array
440
 *     enum.flat_map                         -> an_enumerator
441
 *     enum.collect_concat                   -> an_enumerator
438
 *     enum.flat_map       { |obj| block } -> array
439
 *     enum.collect_concat { |obj| block } -> array
440
 *     enum.flat_map                       -> an_enumerator
441
 *     enum.collect_concat                 -> an_enumerator
442 442
 *
443 443
 *  Returns a new array with the concatenated results of running
444 444
 *  <em>block</em> once for every element in <i>enum</i>.
445 445
 *
446 446
 *  If no block is given, an enumerator is returned instead.
447 447
 *
448
 *     [[1,2],[3,4]].flat_map {|i| i }   #=> [1, 2, 3, 4]
448
 *     [[1,2],[3,4]].flat_map { |i| i }   #=> [1, 2, 3, 4]
449 449
 *
450 450
 */
451 451

  
......
464 464

  
465 465
/*
466 466
 *  call-seq:
467
 *     enum.to_a      ->    array
468
 *     enum.entries   ->    array
467
 *     enum.to_a      -> array
468
 *     enum.entries   -> array
469 469
 *
470 470
 *  Returns an array containing the items in <i>enum</i>.
471 471
 *
......
519 519
 *  call-seq:
520 520
 *     enum.inject(initial, sym) -> obj
521 521
 *     enum.inject(sym)          -> obj
522
 *     enum.inject(initial) {| memo, obj | block }  -> obj
523
 *     enum.inject          {| memo, obj | block }  -> obj
522
 *     enum.inject(initial) { |memo, obj| block }  -> obj
523
 *     enum.inject          { |memo, obj| block }  -> obj
524 524
 *     enum.reduce(initial, sym) -> obj
525 525
 *     enum.reduce(sym)          -> obj
526
 *     enum.reduce(initial) {| memo, obj | block }  -> obj
527
 *     enum.reduce          {| memo, obj | block }  -> obj
526
 *     enum.reduce(initial) { |memo, obj| block }  -> obj
527
 *     enum.reduce          { |memo, obj| block }  -> obj
528 528
 *
529 529
 *  Combines all elements of <i>enum</i> by applying a binary
530 530
 *  operation, specified by a block or a symbol that names a
......
545 545
 *  Examples:
546 546
 *
547 547
 *     # Sum some numbers
548
 *     (5..10).reduce(:+)                            #=> 45
548
 *     (5..10).reduce(:+)                             #=> 45
549 549
 *     # Same using a block and inject
550
 *     (5..10).inject {|sum, n| sum + n }            #=> 45
550
 *     (5..10).inject { |sum, n| sum + n }            #=> 45
551 551
 *     # Multiply some numbers
552
 *     (5..10).reduce(1, :*)                         #=> 151200
552
 *     (5..10).reduce(1, :*)                          #=> 151200
553 553
 *     # Same using a block
554
 *     (5..10).inject(1) {|product, n| product * n } #=> 151200
554
 *     (5..10).inject(1) { |product, n| product * n } #=> 151200
555 555
 *     # find the longest word
556 556
 *     longest = %w{ cat sheep bear }.inject do |memo,word|
557 557
 *        memo.length > word.length ? memo : word
558 558
 *     end
559
 *     longest                                       #=> "sheep"
559
 *     longest                                        #=> "sheep"
560 560
 *
561 561
 */
562 562
static VALUE
......
606 606

  
607 607
/*
608 608
 *  call-seq:
609
 *     enum.partition {| obj | block }  -> [ true_array, false_array ]
610
 *     enum.partition                   -> an_enumerator
609
 *     enum.partition { |obj| block } -> [ true_array, false_array ]
610
 *     enum.partition                 -> an_enumerator
611 611
 *
612 612
 *  Returns two arrays, the first containing the elements of
613 613
 *  <i>enum</i> for which the block evaluates to true, the second
......
615 615
 *
616 616
 *  If no block is given, an enumerator is returned instead.
617 617
 *
618
 *     (1..6).partition {|v| v.even? }  #=> [[2, 4, 6], [1, 3, 5]]
618
 *     (1..6).partition { |v| v.even? }  #=> [[2, 4, 6], [1, 3, 5]]
619 619
 *
620 620
 */
621 621

  
......
655 655

  
656 656
/*
657 657
 *  call-seq:
658
 *     enum.group_by {| obj | block }  -> a_hash
659
 *     enum.group_by                   -> an_enumerator
658
 *     enum.group_by { |obj| block } -> a_hash
659
 *     enum.group_by                 -> an_enumerator
660 660
 *
661 661
 *  Returns a hash, which keys are evaluated result from the
662 662
 *  block, and values are arrays of elements in <i>enum</i>
......
664 664
 *
665 665
 *  If no block is given, an enumerator is returned instead.
666 666
 *
667
 *     (1..6).group_by {|i| i%3}   #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]}
667
 *     (1..6).group_by { |i| i%3 }   #=> {0=>[3, 6], 1=>[1, 4], 2=>[2, 5]}
668 668
 *
669 669
 */
670 670

  
......
748 748

  
749 749
/*
750 750
 *  call-seq:
751
 *     enum.sort                     -> array
752
 *     enum.sort {| a, b | block }   -> array
751
 *     enum.sort                  -> array
752
 *     enum.sort { |a, b| block } -> array
753 753
 *
754 754
 *  Returns an array containing the items in <i>enum</i> sorted,
755 755
 *  either according to their own <code><=></code> method, or by using
......
759 759
 *  built-in Schwartzian Transform, useful when key computation or
760 760
 *  comparison is expensive.
761 761
 *
762
 *     %w(rhea kea flea).sort         #=> ["flea", "kea", "rhea"]
763
 *     (1..10).sort {|a,b| b <=> a}   #=> [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
762
 *     %w(rhea kea flea).sort          #=> ["flea", "kea", "rhea"]
763
 *     (1..10).sort { |a,b| b <=> a }  #=> [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
764 764
 */
765 765

  
766 766
static VALUE
......
823 823

  
824 824
/*
825 825
 *  call-seq:
826
 *     enum.sort_by {| obj | block }    -> array
827
 *     enum.sort_by                     -> an_enumerator
826
 *     enum.sort_by { |obj| block }   -> array
827
 *     enum.sort_by                   -> an_enumerator
828 828
 *
829 829
 *  Sorts <i>enum</i> using a set of keys generated by mapping the
830 830
 *  values in <i>enum</i> through the given block.
831 831
 *
832 832
 *  If no block is given, an enumerator is returned instead.
833 833
 *
834
 *     %w{ apple pear fig }.sort_by {|word| word.length}
834
 *     %w{apple pear fig}.sort_by { |word| word.length}
835 835
 *                   #=> ["fig", "pear", "apple"]
836 836
 *
837 837
 *  The current implementation of <code>sort_by</code> generates an
......
841 841
 *
842 842
 *     require 'benchmark'
843 843
 *
844
 *     a = (1..100000).map {rand(100000)}
844
 *     a = (1..100000).map { rand(100000) }
845 845
 *
846 846
 *     Benchmark.bm(10) do |b|
847 847
 *       b.report("Sort")    { a.sort }
848
 *       b.report("Sort by") { a.sort_by {|a| a} }
848
 *       b.report("Sort by") { a.sort_by { |a| a } }
849 849
 *     end
850 850
 *
851 851
 *  <em>produces:</em>
......
859 859
 *  using the basic <code>sort</code> method.
860 860
 *
861 861
 *     files = Dir["*"]
862
 *     sorted = files.sort {|a,b| File.new(a).mtime <=> File.new(b).mtime}
862
 *     sorted = files.sort { |a,b| File.new(a).mtime <=> File.new(b).mtime }
863 863
 *     sorted   #=> ["mon", "tues", "wed", "thurs"]
864 864
 *
865 865
 *  This sort is inefficient: it generates two new <code>File</code>
......
888 888
 *
889 889
 *  This is exactly what <code>sort_by</code> does internally.
890 890
 *
891
 *     sorted = Dir["*"].sort_by {|f| test(?M, f)}
891
 *     sorted = Dir["*"].sort_by { |f| test(?M, f) }
892 892
 *     sorted   #=> ["mon", "tues", "wed", "thurs"]
893 893
 */
894 894

  
......
965 965

  
966 966
/*
967 967
 *  call-seq:
968
 *     enum.all? [{|obj| block } ]   -> true or false
968
 *     enum.all? [{ |obj| block }]   -> true or false
969 969
 *
970 970
 *  Passes each element of the collection to the given block. The method
971 971
 *  returns <code>true</code> if the block never returns
972 972
 *  <code>false</code> or <code>nil</code>. If the block is not given,
973
 *  Ruby adds an implicit block of <code>{|obj| obj}</code> (that is
973
 *  Ruby adds an implicit block of <code>{ |obj| obj }</code> (that is
974 974
 *  <code>all?</code> will return <code>true</code> only if none of the
975 975
 *  collection members are <code>false</code> or <code>nil</code>.)
976 976
 *
977
 *     %w{ant bear cat}.all? {|word| word.length >= 3}   #=> true
978
 *     %w{ant bear cat}.all? {|word| word.length >= 4}   #=> false
979
 *     [ nil, true, 99 ].all?                            #=> false
977
 *     %w{ant bear cat}.all? { |word| word.length >= 3 }  #=> true
978
 *     %w{ant bear cat}.all? { |word| word.length >= 4 }  #=> false
979
 *     [ nil, true, 99 ].all?                             #=> false
980 980
 *
981 981
 */
982 982

  
......
1000 1000

  
1001 1001
/*
1002 1002
 *  call-seq:
1003
 *     enum.any? [{|obj| block } ]   -> true or false
1003
 *     enum.any? [{ |obj| block }]   -> true or false
1004 1004
 *
1005 1005
 *  Passes each element of the collection to the given block. The method
1006 1006
 *  returns <code>true</code> if the block ever returns a value other
1007 1007
 *  than <code>false</code> or <code>nil</code>. If the block is not
1008
 *  given, Ruby adds an implicit block of <code>{|obj| obj}</code> (that
1008
 *  given, Ruby adds an implicit block of <code>{ |obj| obj }</code> (that
1009 1009
 *  is <code>any?</code> will return <code>true</code> if at least one
1010 1010
 *  of the collection members is not <code>false</code> or
1011 1011
 *  <code>nil</code>.
1012 1012
 *
1013
 *     %w{ant bear cat}.any? {|word| word.length >= 3}   #=> true
1014
 *     %w{ant bear cat}.any? {|word| word.length >= 4}   #=> true
1015
 *     [ nil, true, 99 ].any?                            #=> true
1013
 *     %w{ant bear cat}.any? { |word| word.length >= 3 }  #=> true
1014
 *     %w{ant bear cat}.any? { |word| word.length >= 4 }  #=> true
1015
 *     [ nil, true, 99 ].any?                             #=> true
1016 1016
 *
1017 1017
 */
1018 1018

  
......
1041 1041

  
1042 1042
/*
1043 1043
 *  call-seq:
1044
 *     enum.one? [{|obj| block }]   -> true or false
1044
 *     enum.one? [{ |obj| block }]   -> true or false
1045 1045
 *
1046 1046
 *  Passes each element of the collection to the given block. The method
1047 1047
 *  returns <code>true</code> if the block returns <code>true</code>
......
1049 1049
 *  <code>true</code> only if exactly one of the collection members is
1050 1050
 *  true.
1051 1051
 *
1052
 *     %w{ant bear cat}.one? {|word| word.length == 4}   #=> true
1053
 *     %w{ant bear cat}.one? {|word| word.length > 4}    #=> false
1054
 *     %w{ant bear cat}.one? {|word| word.length < 4}    #=> false
1055
 *     [ nil, true, 99 ].one?                            #=> false
1056
 *     [ nil, true, false ].one?                         #=> true
1052
 *     %w{ant bear cat}.one? { |word| word.length == 4 }  #=> true
1053
 *     %w{ant bear cat}.one? { |word| word.length > 4 }   #=> false
1054
 *     %w{ant bear cat}.one? { |word| word.length < 4 }   #=> false
1055
 *     [ nil, true, 99 ].one?                             #=> false
1056
 *     [ nil, true, false ].one?                          #=> true
1057 1057
 *
1058 1058
 */
1059 1059

  
......
1078 1078

  
1079 1079
/*
1080 1080
 *  call-seq:
1081
 *     enum.none? [{|obj| block }]   -> true or false
1081
 *     enum.none? [{ |obj| block }]   -> true or false
1082 1082
 *
1083 1083
 *  Passes each element of the collection to the given block. The method
1084 1084
 *  returns <code>true</code> if the block never returns <code>true</code>
1085 1085
 *  for all elements. If the block is not given, <code>none?</code> will return
1086 1086
 *  <code>true</code> only if none of the collection members is true.
1087 1087
 *
1088
 *     %w{ant bear cat}.none? {|word| word.length == 5}  #=> true
1089
 *     %w{ant bear cat}.none? {|word| word.length >= 4}  #=> false
1090
 *     [].none?                                          #=> true
1091
 *     [nil].none?                                       #=> true
1092
 *     [nil,false].none?                                 #=> true
1088
 *     %w{ant bear cat}.none? { |word| word.length == 5 } #=> true
1089
 *     %w{ant bear cat}.none? { |word| word.length >= 4 } #=> false
1090
 *     [].none?                                           #=> true
1091
 *     [nil].none?                                        #=> true
1092
 *     [nil,false].none?                                  #=> true
1093 1093
 */
1094 1094
static VALUE
1095 1095
enum_none(VALUE obj)
......
1141 1141

  
1142 1142
/*
1143 1143
 *  call-seq:
1144
 *     enum.min                    -> obj
1145
 *     enum.min {| a,b | block }   -> obj
1144
 *     enum.min                 -> obj
1145
 *     enum.min { |a,b| block } -> obj
1146 1146
 *
1147 1147
 *  Returns the object in <i>enum</i> with the minimum value. The
1148 1148
 *  first form assumes all objects implement <code>Comparable</code>;
......
1150 1150
 *
1151 1151
 *     a = %w(albatross dog horse)
1152 1152
 *     a.min                                  #=> "albatross"
1153
 *     a.min {|a,b| a.length <=> b.length }   #=> "dog"
1153
 *     a.min { |a,b| a.length <=> b.length }  #=> "dog"
1154 1154
 */
1155 1155

  
1156 1156
static VALUE
......
1208 1208

  
1209 1209
/*
1210 1210
 *  call-seq:
1211
 *     enum.max                   -> obj
1212
 *     enum.max {|a,b| block }    -> obj
1211
 *     enum.max                 -> obj
1212
 *     enum.max { |a,b| block } -> obj
1213 1213
 *
1214 1214
 *  Returns the object in _enum_ with the maximum value. The
1215 1215
 *  first form assumes all objects implement <code>Comparable</code>;
......
1217 1217
 *
1218 1218
 *     a = %w(albatross dog horse)
1219 1219
 *     a.max                                  #=> "horse"
1220
 *     a.max {|a,b| a.length <=> b.length }   #=> "albatross"
1220
 *     a.max { |a,b| a.length <=> b.length }  #=> "albatross"
1221 1221
 */
1222 1222

  
1223 1223
static VALUE
......
1347 1347

  
1348 1348
/*
1349 1349
 *  call-seq:
1350
 *     enum.minmax                   -> [min,max]
1351
 *     enum.minmax {|a,b| block }    -> [min,max]
1350
 *     enum.minmax                 -> [min,max]
1351
 *     enum.minmax { |a,b| block } -> [min,max]
1352 1352
 *
1353 1353
 *  Returns two elements array which contains the minimum and the
1354 1354
 *  maximum value in the enumerable.  The first form assumes all
......
1357 1357
 *
1358 1358
 *     a = %w(albatross dog horse)
1359 1359
 *     a.minmax                                  #=> ["albatross", "horse"]
1360
 *     a.minmax {|a,b| a.length <=> b.length }   #=> ["dog", "albatross"]
1360
 *     a.minmax { |a,b| a.length <=> b.length }  #=> ["dog", "albatross"]
1361 1361
 */
1362 1362

  
1363 1363
static VALUE
......
1406 1406

  
1407 1407
/*
1408 1408
 *  call-seq:
1409
 *     enum.min_by {|obj| block }   -> obj
1410
 *     enum.min_by                  -> an_enumerator
1409
 *     enum.min_by { |obj| block } -> obj
1410
 *     enum.min_by                 -> an_enumerator
1411 1411
 *
1412 1412
 *  Returns the object in <i>enum</i> that gives the minimum
1413 1413
 *  value from the given block.
......
1415 1415
 *  If no block is given, an enumerator is returned instead.
1416 1416
 *
1417 1417
 *     a = %w(albatross dog horse)
1418
 *     a.min_by {|x| x.length }   #=> "dog"
1418
 *     a.min_by { |x| x.length }   #=> "dog"
1419 1419
 */
1420 1420

  
1421 1421
static VALUE
......
1452 1452

  
1453 1453
/*
1454 1454
 *  call-seq:
1455
 *     enum.max_by {|obj| block }   -> obj
1456
 *     enum.max_by                  -> an_enumerator
1455
 *     enum.max_by { |obj| block } -> obj
1456
 *     enum.max_by                 -> an_enumerator
1457 1457
 *
1458 1458
 *  Returns the object in <i>enum</i> that gives the maximum
1459 1459
 *  value from the given block.
......
1461 1461
 *  If no block is given, an enumerator is returned instead.
1462 1462
 *
1463 1463
 *     a = %w(albatross dog horse)
1464
 *     a.max_by {|x| x.length }   #=> "albatross"
1464
 *     a.max_by { |x| x.length }   #=> "albatross"
1465 1465
 */
1466 1466

  
1467 1467
static VALUE
......
1549 1549

  
1550 1550
/*
1551 1551
 *  call-seq:
1552
 *     enum.minmax_by {|obj| block }   -> [min, max]
1553
 *     enum.minmax_by                  -> an_enumerator
1552
 *     enum.minmax_by { |obj| block } -> [min, max]
1553
 *     enum.minmax_by                 -> an_enumerator
1554 1554
 *
1555 1555
 *  Returns two elements array array containing the objects in
1556 1556
 *  <i>enum</i> that gives the minimum and maximum values respectively
......
1559 1559
 *  If no block is given, an enumerator is returned instead.
1560 1560
 *
1561 1561
 *     a = %w(albatross dog horse)
1562
 *     a.minmax_by {|x| x.length }   #=> ["dog", "albatross"]
1562
 *     a.minmax_by { |x| x.length }   #=> ["dog", "albatross"]
1563 1563
 */
1564 1564

  
1565 1565
static VALUE
......
1625 1625

  
1626 1626
/*
1627 1627
 *  call-seq:
1628
 *     enum.each_with_index(*args) {|obj, i| block }   ->  enum
1629
 *     enum.each_with_index(*args)                     ->  an_enumerator
1628
 *     enum.each_with_index(*args) { |obj, i| block } ->  enum
1629
 *     enum.each_with_index(*args)                    ->  an_enumerator
1630 1630
 *
1631 1631
 *  Calls <em>block</em> with two arguments, the item and its index,
1632 1632
 *  for each item in <i>enum</i>.  Given arguments are passed through
......
1635 1635
 *  If no block is given, an enumerator is returned instead.
1636 1636
 *
1637 1637
 *     hash = Hash.new
1638
 *     %w(cat dog wombat).each_with_index {|item, index|
1638
 *     %w(cat dog wombat).each_with_index { |item, index|
1639 1639
 *       hash[item] = index
1640 1640
 *     }
1641 1641
 *     hash   #=> {"cat"=>0, "dog"=>1, "wombat"=>2}
......
1657 1657

  
1658 1658
/*
1659 1659
 *  call-seq:
1660
 *     enum.reverse_each(*args) {|item| block }   ->  enum
1661
 *     enum.reverse_each(*args)                   ->  an_enumerator
1660
 *     enum.reverse_each(*args) { |item| block } ->  enum
1661
 *     enum.reverse_each(*args)                  ->  an_enumerator
1662 1662
 *
1663 1663
 *  Builds a temporary array and traverses that array in reverse order.
1664 1664
 *
1665 1665
 *  If no block is given, an enumerator is returned instead.
1666 1666
 *
1667
 *      (1..3).reverse_each {|v| p v }
1667
 *      (1..3).reverse_each { |v| p v }
1668 1668
 *
1669 1669
 *    produces:
1670 1670
 *
......
1701 1701

  
1702 1702
/*
1703 1703
 *  call-seq:
1704
 *     enum.each_entry {|obj| block}  -> enum
1705
 *     enum.each_entry                -> an_enumerator
1704
 *     enum.each_entry { |obj| block }  -> enum
1705
 *     enum.each_entry                  -> an_enumerator
1706 1706
 *
1707 1707
 *  Calls <i>block</i> once for each element in +self+, passing that
1708 1708
 *  element as a parameter, converting multiple values from yield to an
......
1718 1718
 *         yield
1719 1719
 *       end
1720 1720
 *     end
1721
 *     Foo.new.each_entry{|o| p o }
1721
 *     Foo.new.each_entry{ |o| p o }
1722 1722
 *
1723 1723
 *  produces:
1724 1724
 *
......
1756 1756

  
1757 1757
/*
1758 1758
 *  call-seq:
1759
 *    enum.each_slice(n) {...}  ->  nil
1760
 *    enum.each_slice(n)        ->  an_enumerator
1759
 *    enum.each_slice(n) { ... }  ->  nil
1760
 *    enum.each_slice(n)          ->  an_enumerator
1761 1761
 *
1762 1762
 *  Iterates the given block for each slice of <n> elements.  If no
1763 1763
 *  block is given, returns an enumerator.
1764 1764
 *
1765 1765
 *  e.g.:
1766
 *      (1..10).each_slice(3) {|a| p a}
1766
 *      (1..10).each_slice(3) { |a| p a }
1767 1767
 *      # outputs below
1768 1768
 *      [1, 2, 3]
1769 1769
 *      [4, 5, 6]
......
1810 1810

  
1811 1811
/*
1812 1812
 *  call-seq:
1813
 *    enum.each_cons(n) {...}   ->  nil
1813
 *    enum.each_cons(n) { ... } ->  nil
1814 1814
 *    enum.each_cons(n)         ->  an_enumerator
1815 1815
 *
1816 1816
 *  Iterates the given block for each array of consecutive <n>
1817 1817
 *  elements.  If no block is given, returns an enumerator.
1818 1818
 *
1819 1819
 *  e.g.:
1820
 *      (1..10).each_cons(3) {|a| p a}
1820
 *      (1..10).each_cons(3) { |a| p a }
1821 1821
 *      # outputs below
1822 1822
 *      [1, 2, 3]
1823 1823
 *      [2, 3, 4]
......
1854 1854

  
1855 1855
/*
1856 1856
 *  call-seq:
1857
 *    enum.each_with_object(obj) {|(*args), memo_obj| ... }  ->  obj
1858
 *    enum.each_with_object(obj)                             ->  an_enumerator
1857
 *    enum.each_with_object(obj) { |(*args), memo_obj| ... }  ->  obj
1858
 *    enum.each_with_object(obj)                              ->  an_enumerator
1859 1859
 *
1860 1860
 *  Iterates the given block for each element with an arbitrary
1861 1861
 *  object given, and returns the initially given object.
......
1863 1863
 *  If no block is given, returns an enumerator.
1864 1864
 *
1865 1865
 *  e.g.:
1866
 *      evens = (1..10).each_with_object([]) {|i, a| a << i*2 }
1866
 *      evens = (1..10).each_with_object([]) { |i, a| a << i*2 }
1867 1867
 *      #=> [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]
1868 1868
 *
1869 1869
 */
......
1956 1956

  
1957 1957
/*
1958 1958
 *  call-seq:
1959
 *     enum.zip(arg, ...)                   -> an_array_of_array
1960
 *     enum.zip(arg, ...) {|arr| block }    -> nil
1959
 *     enum.zip(arg, ...)                  -> an_array_of_array
1960
 *     enum.zip(arg, ...) { |arr| block }  -> nil
1961 1961
 *
1962 1962
 *  Takes one element from <i>enum</i> and merges corresponding
1963 1963
 *  elements from each <i>args</i>.  This generates a sequence of
......
2059 2059

  
2060 2060
/*
2061 2061
 *  call-seq:
2062
 *     enum.take_while {|arr| block }   -> array
2063
 *     enum.take_while                  -> an_enumerator
2062
 *     enum.take_while { |arr| block } -> array
2063
 *     enum.take_while                 -> an_enumerator
2064 2064
 *
2065 2065
 *  Passes elements to the block until the block returns +nil+ or +false+,
2066 2066
 *  then stops iterating and returns an array of all prior elements.
......
2068 2068
 *  If no block is given, an enumerator is returned instead.
2069 2069
 *
2070 2070
 *     a = [1, 2, 3, 4, 5, 0]
2071
 *     a.take_while {|i| i < 3 }   #=> [1, 2]
2071
 *     a.take_while { |i| i < 3 }   #=> [1, 2]
2072 2072
 *
2073 2073
 */
2074 2074

  
......
2140 2140

  
2141 2141
/*
2142 2142
 *  call-seq:
2143
 *     enum.drop_while {|arr| block }   -> array
2143
 *     enum.drop_while { |arr| block }  -> array
2144 2144
 *     enum.drop_while                  -> an_enumerator
2145 2145
 *
2146 2146
 *  Drops elements up to, but not including, the first element for
......
2150 2150
 *  If no block is given, an enumerator is returned instead.
2151 2151
 *
2152 2152
 *     a = [1, 2, 3, 4, 5, 0]
2153
 *     a.drop_while {|i| i < 3 }   #=> [3, 4, 5, 0]
2153
 *     a.drop_while { |i| i < 3 }   #=> [3, 4, 5, 0]
2154 2154
 *
2155 2155
 */
2156 2156

  
......
2178 2178

  
2179 2179
/*
2180 2180
 *  call-seq:
2181
 *     enum.cycle(n=nil) {|obj| block }   ->  nil
2181
 *     enum.cycle(n=nil) { |obj| block }  ->  nil
2182 2182
 *     enum.cycle(n=nil)                  ->  an_enumerator
2183 2183
 *
2184 2184
 *  Calls <i>block</i> for each element of <i>enum</i> repeatedly _n_
......
2192 2192
 *  If no block is given, an enumerator is returned instead.
2193 2193
 *
2194 2194
 *     a = ["a", "b", "c"]
2195
 *     a.cycle {|x| puts x }  # print, a, b, c, a, b, c,.. forever.
2196
 *     a.cycle(2) {|x| puts x }  # print, a, b, c, a, b, c.
2195
 *     a.cycle { |x| puts x }  # print, a, b, c, a, b, c,.. forever.
2196
 *     a.cycle(2) { |x| puts x }  # print, a, b, c, a, b, c.
2197 2197
 *
2198 2198
 */
2199 2199

  
......
2309 2309

  
2310 2310
/*
2311 2311
 *  call-seq:
2312
 *     enum.chunk {|elt| ... }                       -> an_enumerator
2313
 *     enum.chunk(initial_state) {|elt, state| ... } -> an_enumerator
2312
 *     enum.chunk { |elt| ... }                       -> an_enumerator
2313
 *     enum.chunk(initial_state) { |elt, state| ... } -> an_enumerator
2314 2314
 *
2315 2315
 *  Creates an enumerator for each chunked elements.
2316 2316
 *  The consecutive elements which have same block value are chunked.
......
2318 2318
 *  The result enumerator yields the block value and an array of chunked elements.
2319 2319
 *  So "each" method can be called as follows.
2320 2320
 *
2321
 *    enum.chunk {|elt| key }.each {|key, ary| ... }
2322
 *    enum.chunk(initial_state) {|elt, state| key }.each {|key, ary| ... }
2321
 *    enum.chunk { |elt| key }.each { |key, ary| ... }
2322
 *    enum.chunk(initial_state) { |elt, state| key }.each { |key, ary| ... }
2323 2323
 *
2324 2324
 *  For example, consecutive even numbers and odd numbers can be
2325 2325
 *  splitted as follows.
2326 2326
 *
2327
 *    [3,1,4,1,5,9,2,6,5,3,5].chunk {|n|
2327
 *    [3,1,4,1,5,9,2,6,5,3,5].chunk { |n|
2328 2328
 *      n.even?
2329
 *    }.each {|even, ary|
2329
 *    }.each { |even, ary|
2330 2330
 *      p [even, ary]
2331 2331
 *    }
2332 2332
 *    #=> [false, [3, 1]]
......
2338 2338
 *  This method is especially useful for sorted series of elements.
2339 2339
 *  The following example counts words for each initial letter.
2340 2340
 *
2341
 *    open("/usr/share/dict/words", "r:iso-8859-1") {|f|
2342
 *      f.chunk {|line| line.ord }.each {|ch, lines| p [ch.chr, lines.length] }
2341
 *    open("/usr/share/dict/words", "r:iso-8859-1") { |f|
2342
 *      f.chunk { |line| line.ord }.each { |ch, lines| p [ch.chr, lines.length] }
2343 2343
 *    }
2344 2344
 *    #=> ["\n", 1]
2345 2345
 *    #   ["A", 1327]
......
2357 2357
 *  For example, the sequence of hyphens in svn log can be eliminated as follows.
2358 2358
 *
2359 2359
 *    sep = "-"*72 + "\n"
2360
 *    IO.popen("svn log README") {|f|
2361
 *      f.chunk {|line|
2360
 *    IO.popen("svn log README") { |f|
2361
 *      f.chunk { |line|
2362 2362
 *        line != sep || nil
2363
 *      }.each {|_, lines|
2363
 *      }.each { |_, lines|
2364 2364
 *        pp lines
2365 2365
 *      }
2366 2366
 *    }
......
2376 2376
 *
2377 2377
 *  paragraphs separated by empty lines can be parsed as follows.
2378 2378
 *
2379
 *    File.foreach("README").chunk {|line|
2379
 *    File.foreach("README").chunk { |line|
2380 2380
 *      /\A\s*\z/ !~ line || nil
2381
 *    }.each {|_, lines|
2381
 *    }.each { |_, lines|
2382 2382
 *      pp lines
2383 2383
 *    }
2384 2384
 *
......
2387 2387
 *  pass other lines, chunk can be used as follows.
2388 2388
 *
2389 2389
 *    pat = /\A[A-Z][A-Za-z0-9_]+\#/
2390
 *    open(filename) {|f|
2391
 *      f.chunk {|line| pat =~ line ? $& : :_alone }.each {|key, lines|
2390
 *    open(filename) { |f|
2391
 *      f.chunk { |line| pat =~ line ? $& : :_alone }.each { |key, lines|
2392 2392
 *        if key != :_alone
2393 2393
 *          print lines.sort.join('')
2394 2394
 *        else
......
2484 2484

  
2485 2485
/*
2486 2486
 *  call-seq:
2487
 *     enum.slice_before(pattern)                            -> an_enumerator
2488
 *     enum.slice_before {|elt| bool }                       -> an_enumerator
2489
 *     enum.slice_before(initial_state) {|elt, state| bool } -> an_enumerator
2487
 *     enum.slice_before(pattern)                             -> an_enumerator
2488
 *     enum.slice_before { |elt| bool }                       -> an_enumerator
2489
 *     enum.slice_before(initial_state) { |elt, state| bool } -> an_enumerator
2490 2490
 *
2491 2491
 *  Creates an enumerator for each chunked elements.
2492 2492
 *  The beginnings of chunks are defined by _pattern_ and the block.
......
2502 2502
 *  method.
2503 2503
 *  +each+ method can be called as follows.
2504 2504
 *
2505
 *    enum.slice_before(pattern).each {|ary| ... }
2506
 *    enum.slice_before {|elt| bool }.each {|ary| ... }
2507
 *    enum.slice_before(initial_state) {|elt, state| bool }.each {|ary| ... }
2505
 *    enum.slice_before(pattern).each { |ary| ... }
2506
 *    enum.slice_before { |elt| bool }.each { |ary| ... }
2507
 *    enum.slice_before(initial_state) { |elt, state| bool }.each { |ary| ... }
2508 2508
 *
2509 2509
 *  Other methods of Enumerator class and Enumerable module,
2510 2510
 *  such as map, etc., are also usable.
......
2513 2513
 *  follows.
2514 2514
 *
2515 2515
 *    # iterate over ChangeLog entries.
2516
 *    open("ChangeLog") {|f|
2517
 *      f.slice_before(/\A\S/).each {|e| pp e}
2516
 *    open("ChangeLog") { |f|
2517
 *      f.slice_before(/\A\S/).each { |e| pp e }
2518 2518
 *    }
2519 2519
 *
2520 2520
 *    # same as above.  block is used instead of pattern argument.
2521
 *    open("ChangeLog") {|f|
2522
 *      f.slice_before {|line| /\A\S/ === line }.each {|e| pp e}
2521
 *    open("ChangeLog") { |f|
2522
 *      f.slice_before { |line| /\A\S/ === line }.each { |e| pp e }
2523 2523
 *    }
2524 2524
 *
2525 2525
 * "svn proplist -R" produces multiline output for each file.
2526 2526
 * They can be chunked as follows:
2527 2527
 *
2528
 *    IO.popen([{"LC_ALL"=>"C"}, "svn", "proplist", "-R"]) {|f|
2529
 *      f.lines.slice_before(/\AProp/).each {|lines| p lines }
2528
 *    IO.popen([{"LC_ALL"=>"C"}, "svn", "proplist", "-R"]) { |f|
2529
 *      f.lines.slice_before(/\AProp/).each { |lines| p lines }
2530 2530
 *    }
2531 2531
 *    #=> ["Properties on '.':\n", "  svn:ignore\n", "  svk:merge\n"]
2532 2532
 *    #   ["Properties on 'goruby.c':\n", "  svn:eol-style\n"]
......
2541 2541
 *
2542 2542
 *    a = [0,2,3,4,6,7,9]
2543 2543
 *    prev = a[0]
2544
 *    p a.slice_before {|e|
2544
 *    p a.slice_before { |e|
2545 2545
 *      prev, prev2 = e, prev
2546 2546
 *      prev2 + 1 != e
2547
 *    }.map {|es|
2547
 *    }.map { |es|
2548 2548
 *      es.length <= 2 ? es.join(",") : "#{es.first}-#{es.last}"
2549 2549
 *    }.join(",")
2550 2550
 *    #=> "0,2-4,6,7,9"
......
2562 2562
 *    # this assumes all characters have same width.
2563 2563
 *    def wordwrap(words, maxwidth)
2564 2564
 *      # if cols is a local variable, 2nd "each" may start with non-zero cols.
2565
 *      words.slice_before(cols: 0) {|w, h|
2565
 *      words.slice_before(cols: 0) { |w, h|
2566 2566
 *        h[:cols] += 1 if h[:cols] != 0
2567 2567
 *        h[:cols] += w.length
2568 2568
 *        if maxwidth < h[:cols]
......
2576 2576
 *    text = (1..20).to_a.join(" ")
2577 2577
 *    enum = wordwrap(text.split(/\s+/), 10)
2578 2578
 *    puts "-"*10
2579
 *    enum.each {|ws| puts ws.join(" ") }
2579
 *    enum.each { |ws| puts ws.join(" ") }
2580 2580
 *    puts "-"*10
2581 2581
 *    #=> ----------
2582 2582
 *    #   1 2 3 4 5
......
2591 2591
 * So each mail can be extracted by slice before Unix From line.
2592 2592
 *
2593 2593
 *    # parse mbox
2594
 *    open("mbox") {|f|
2595
 *      f.slice_before {|line|
2594
 *    open("mbox") { |f|
2595
 *      f.slice_before { |line|
2596 2596
 *        line.start_with? "From "
2597
 *      }.each {|mail|
2597
 *      }.each { |mail|
2598 2598
 *        unix_from = mail.shift
2599 2599
 *        i = mail.index("\n")
2600 2600
 *        header = mail[0...i]
2601 2601
 *        body = mail[(i+1)..-1]
2602 2602
 *        body.pop if body.last == "\n"
2603
 *        fields = header.slice_before {|line| !" \t".include?(line[0]) }.to_a
2603
 *        fields = header.slice_before { |line| !" \t".include?(line[0]) }.to_a
2604 2604
 *        p unix_from
2605 2605
 *        pp fields
2606 2606
 *        pp body
......
2608 2608
 *    }
2609 2609
 *
2610 2610
 *    # split mails in mbox (slice before Unix From line after an empty line)
2611
 *    open("mbox") {|f|
2612
 *      f.slice_before(emp: true) {|line,h|
2611
 *    open("mbox") { |f|
2612
 *      f.slice_before(emp: true) { |line,h|
2613 2613
 *        prevemp = h[:emp]
2614 2614
 *        h[:emp] = line == "\n"
2615 2615
 *        prevemp && line.start_with?("From ")
2616
 *      }.each {|mail|
2616
 *      }.each { |mail|
2617 2617
 *        mail.pop if mail.last == "\n"
2618 2618
 *        pp mail
2619 2619
 *      }
2620
-