[pull] master from ruby:master

doc/string/index.rdoc

@@ -1,31 +1,35 @@
-Returns the integer index of the first match for the given argument,
-or +nil+ if none found;
-the search of +self+ is forward, and begins at position +offset+ (in characters).
+Returns the integer position of the first substring that matches the given argument +pattern+,
+or +nil+ if none found.
 
-With string argument +substring+,
+When +pattern+ is a string,
 returns the index of the first matching substring in +self+:
 
   'foo'.index('f')         # => 0
   'foo'.index('o')         # => 1
   'foo'.index('oo')        # => 1
   'foo'.index('ooo')       # => nil
-  'тест'.index('с')        # => 2
-  'こんにちは'.index('ち')   # => 3
+  'тест'.index('с')        # => 2  # Characters, not bytes.
+  'こんにちは'.index('ち')  # => 3
 
-With Regexp argument +regexp+, returns the index of the first match in +self+:
+When +pattern is a Regexp, returns the index of the first match in +self+:
 
   'foo'.index(/o./) # => 1
   'foo'.index(/.o/) # => 0
 
-With positive integer +offset+, begins the search at position +offset+:
+When +offset+ is non-negative, begins the search at position +offset+;
+the returned index is relative to the beginning of +self+:
 
-  'foo'.index('o', 1)        # => 1
-  'foo'.index('o', 2)        # => 2
-  'foo'.index('o', 3)        # => nil
+  'bar'.index('r', 0)        # => 2
+  'bar'.index('r', 1)        # => 2
+  'bar'.index('r', 2)        # => 2
+  'bar'.index('r', 3)        # => nil
+  'bar'.index(/[r-z]/, 0)    # => 2
   'тест'.index('с', 1)       # => 2
-  'こんにちは'.index('ち', 2)  # => 3
+  'тест'.index('с', 2)       # => 2
+  'тест'.index('с', 3)       # => nil  # Offset in characters, not bytes.
+  'こんにちは'.index('ち', 2) # => 3
 
-With negative integer +offset+, selects the search position by counting backward
+With negative integer argument +offset+, selects the search position by counting backward
 from the end of +self+:
 
   'foo'.index('o', -1)  # => 2
@@ -35,4 +39,4 @@ from the end of +self+:
   'foo'.index(/o./, -2) # => 1
   'foo'.index(/.o/, -2) # => 1
 
-Related: String#rindex.
+Related: see {Querying}[rdoc-ref:String@Querying].

gc.rb

@@ -252,61 +252,142 @@ def self.stat hash_or_key = nil
   end
 
   # call-seq:
-  #    GC.stat_heap -> Hash
-  #    GC.stat_heap(nil, hash) -> Hash
-  #    GC.stat_heap(heap_name) -> Hash
-  #    GC.stat_heap(heap_name, hash) -> Hash
-  #    GC.stat_heap(heap_name, :key) -> Numeric
+  #    GC.stat_heap -> new_hash
+  #    GC.stat_heap(heap_id) -> new_hash
+  #    GC.stat_heap(heap_id, key) -> value
+  #    GC.stat_heap(nil, hash) -> hash
+  #    GC.stat_heap(heap_id, hash) -> hash
   #
-  # Returns information for heaps in the \GC.
+  # This method is implementation-specific to CRuby.
   #
-  # If the first optional argument, +heap_name+, is passed in and not +nil+, it
-  # returns a +Hash+ containing information about the particular heap.
-  # Otherwise, it will return a +Hash+ with heap names as keys and
-  # a +Hash+ containing information about the heap as values.
+  # Returns statistics for \GC heaps.
+  # The particular statistics are implementation-specific
+  # and may change in the future without notice.
   #
-  # If the second optional argument, +hash_or_key+, is given as a +Hash+, it will
-  # be overwritten and returned. This is intended to avoid the probe effect.
+  # With no argument given, returns statistics for all heaps:
   #
-  # If both optional arguments are passed in and the second optional argument is
-  # a symbol, it will return a +Numeric+ value for the particular heap.
+  #   GC.stat_heap
+  #   # =>
+  #   {0 =>
+  #     {slot_size: 40,
+  #      heap_eden_pages: 246,
+  #      heap_eden_slots: 402802,
+  #      total_allocated_pages: 246,
+  #      force_major_gc_count: 2,
+  #      force_incremental_marking_finish_count: 1,
+  #      total_allocated_objects: 33867152,
+  #      total_freed_objects: 33520523},
+  #    1 =>
+  #     {slot_size: 80,
+  #      heap_eden_pages: 84,
+  #      heap_eden_slots: 68746,
+  #      total_allocated_pages: 84,
+  #      force_major_gc_count: 1,
+  #      force_incremental_marking_finish_count: 4,
+  #      total_allocated_objects: 147491,
+  #      total_freed_objects: 90699},
+  #    2 =>
+  #     {slot_size: 160,
+  #      heap_eden_pages: 157,
+  #      heap_eden_slots: 64182,
+  #      total_allocated_pages: 157,
+  #      force_major_gc_count: 0,
+  #      force_incremental_marking_finish_count: 0,
+  #      total_allocated_objects: 211460,
+  #      total_freed_objects: 190075},
+  #    3 =>
+  #     {slot_size: 320,
+  #      heap_eden_pages: 8,
+  #      heap_eden_slots: 1631,
+  #      total_allocated_pages: 8,
+  #      force_major_gc_count: 0,
+  #      force_incremental_marking_finish_count: 0,
+  #      total_allocated_objects: 1422,
+  #      total_freed_objects: 700},
+  #    4 =>
+  #     {slot_size: 640,
+  #      heap_eden_pages: 16,
+  #      heap_eden_slots: 1628,
+  #      total_allocated_pages: 16,
+  #      force_major_gc_count: 0,
+  #      force_incremental_marking_finish_count: 0,
+  #      total_allocated_objects: 1230,
+  #      total_freed_objects: 309}}
+  #
+  # In the example above, the keys in the outer hash are the heap identifiers:
+  #
+  #   GC.stat_heap.keys # => [0, 1, 2, 3, 4]
+  #
+  # On CRuby, each heap identifier is an integer;
+  # on other implementations, a heap identifier may be a string.
+  #
+  # With only argument +heap_id+ given,
+  # returns statistics for the given heap identifier:
+  #
+  #   GC.stat_heap(2)
+  #   # =>
+  #   {slot_size: 160,
+  #    heap_eden_pages: 157,
+  #    heap_eden_slots: 64182,
+  #    total_allocated_pages: 157,
+  #    force_major_gc_count: 0,
+  #    force_incremental_marking_finish_count: 0,
+  #    total_allocated_objects: 225018,
+  #    total_freed_objects: 206647}
   #
-  # On CRuby, +heap_name+ is of the type +Integer+ but may be of type +String+
-  # on other implementations.
+  # With arguments +heap_id+ and +key+ given,
+  # returns the value for the given key in the given heap:
   #
-  # The contents of the hash are implementation-specific and may change in
-  # the future without notice.
+  #   GC.stat_heap(2, :slot_size) # => 160
   #
-  # If the optional argument, hash, is given, it is overwritten and returned.
+  # With arguments +nil+ and +hash+ given,
+  # merges the statistics for all heaps into the given hash:
   #
-  # This method is only expected to work on CRuby.
+  #   h = {foo: 0, bar: 1}
+  #   GC.stat_heap(nil, h).keys # => [:foo, :bar, 0, 1, 2, 3, 4]
   #
-  # The hash includes the following keys about the internal information in
-  # the \GC:
+  # With arguments +heap_id+ and +hash+ given,
+  # merges the statistics for the given heap into the given hash:
   #
-  # [slot_size]
+  #   h = {foo: 0, bar: 1}
+  #   GC.stat_heap(2, h).keys
+  #   # =>
+  #   [:foo,
+  #    :bar,
+  #    :slot_size,
+  #    :heap_eden_pages,
+  #    :heap_eden_slots,
+  #    :total_allocated_pages,
+  #    :force_major_gc_count,
+  #    :force_incremental_marking_finish_count,
+  #    :total_allocated_objects,
+  #    :total_freed_objects]
+  #
+  # The statistics for a heap may include:
+  #
+  # - +:slot_size+:
   #   The slot size of the heap in bytes.
-  # [heap_allocatable_pages]
+  # - +:heap_allocatable_pages+:
   #   The number of pages that can be allocated without triggering a new
   #   garbage collection cycle.
-  # [heap_eden_pages]
+  # - +:heap_eden_pages+:
   #   The number of pages in the eden heap.
-  # [heap_eden_slots]
+  # - +:heap_eden_slots+:
   #   The total number of slots in all of the pages in the eden heap.
-  # [heap_tomb_pages]
+  # - +:heap_tomb_pages+:
   #   The number of pages in the tomb heap. The tomb heap only contains pages
   #   that do not have any live objects.
-  # [heap_tomb_slots]
+  # - +:heap_tomb_slots+:
   #   The total number of slots in all of the pages in the tomb heap.
-  # [total_allocated_pages]
+  # - +:total_allocated_pages+:
   #   The total number of pages that have been allocated in the heap.
-  # [total_freed_pages]
+  # - +:total_freed_pages+:
   #   The total number of pages that have been freed and released back to the
   #   system in the heap.
-  # [force_major_gc_count]
+  # - +:force_major_gc_count+:
   #   The number of times this heap has forced major garbage collection cycles
   #   to start due to running out of free slots.
-  # [force_incremental_marking_finish_count]
+  # - +:force_incremental_marking_finish_count+:
   #   The number of times this heap has forced incremental marking to complete
   #   due to running out of pooled slots.
   #

string.c

@@ -4501,8 +4501,7 @@ rb_strseq_index(VALUE str, VALUE sub, long offset, int in_byte)
 
 /*
  *  call-seq:
- *    index(substring, offset = 0) -> integer or nil
- *    index(regexp, offset = 0) -> integer or nil
+ *    index(pattern, offset = 0) -> integer or nil
  *
  *  :include: doc/string/index.rdoc
  *
@@ -7083,13 +7082,17 @@ rb_str_reverse_bang(VALUE str)
  *  call-seq:
  *    include?(other_string) -> true or false
  *
- *  Returns +true+ if +self+ contains +other_string+, +false+ otherwise:
+ *  Returns whether +self+ contains +other_string+:
  *
- *    s = 'foo'
- *    s.include?('f')    # => true
- *    s.include?('fo')   # => true
- *    s.include?('food') # => false
+ *    s = 'bar'
+ *    s.include?('ba')  # => true
+ *    s.include?('ar')  # => true
+ *    s.include?('bar') # => true
+ *    s.include?('a')   # => true
+ *    s.include?('')    # => true
+ *    s.include?('foo') # => false
  *
+ *  Related: see {Querying}[rdoc-ref:String@Querying].
  */
 
 VALUE
@@ -10681,18 +10684,21 @@ rb_str_scan(VALUE str, VALUE pat)
  *  call-seq:
  *    hex -> integer
  *
- *  Interprets the leading substring of +self+ as a string of hexadecimal digits
- *  (with an optional sign and an optional <code>0x</code>) and returns the
- *  corresponding number;
- *  returns zero if there is no such leading substring:
+ *  Interprets the leading substring of +self+ as hexadecimal;
+ *  returns its integer value:
+ *
+ *    '0xFFFF'.hex     # => 65535
+ *    'FFzzzFF'.hex    # =>   255  # Hex ends at first non-hex character, 'z'.
+ *    'ffzzzFF'.hex    # =>   255  # Case does not matter.
+ *    '-FFzzzFF'.hex   # =>  -255  # May have leading '-'.
+ *    '0xFFzzzFF'.hex  # =>   255  # May have leading '0x'.
+ *    '-0xFFzzzFF'.hex # =>  -255  # May have leading '-0x'.
  *
- *    '0x0a'.hex        # => 10
- *    '-1234'.hex       # => -4660
- *    '0'.hex           # => 0
- *    'non-numeric'.hex # => 0
+ *  Returns zero if there is no such leading substring:
  *
- *  Related: String#oct.
+ *    'zzz'.hex # => 0
  *
+ *  Related: See {Converting to Non-String}[rdoc-ref:String@Converting+to+Non--5CString].
  */
 
 static VALUE