* array.c: rdoc patch - unified margin.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@6624 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 169 insertions, 168 deletions

diff --git a/array.c b/array.c
index b55c7389f2..10b6d64504 100644
--- a/array.c
+++ b/array.c
@@ -78,11 +78,11 @@ rb_ary_freeze(ary)
 }
 
 /*
- * call-seq:
- *   array.frozen?  -> true or false
+ *  call-seq:
+ *     array.frozen?  -> true or false
  *
- * Return <code>true</code> if this array is frozen (or temporarily frozen
- * while being sorted).
+ *  Return <code>true</code> if this array is frozen (or temporarily frozen
+ *  while being sorted).
  */
 
 static VALUE
@@ -222,42 +222,42 @@ rb_check_array_type(ary)
 
 static VALUE rb_ary_replace _((VALUE, VALUE));
 
-/* 
- * call-seq:
- *       Array.new(size=0, obj=nil)
- *       Array.new(array)
- *       Array.new(size) {|index| block }
-
- * Returns a new array. In the first form, the new array is
- * empty. In the second it is created with _size_ copies of _obj_
- * (that is, _size_ references to the same
- * _obj_). The third form creates a copy of the array
- * passed as a parameter (the array is generated by calling
- * to_ary  on the parameter). In the last form, an array
- * of the given size is created. Each element in this array is
- * calculated by passing the element's index to the given block and
- * storing the return value.
+/*
+ *  call-seq:
+ *     Array.new(size=0, obj=nil)
+ *     Array.new(array)
+ *     Array.new(size) {|index| block }
+ *
+ *  Returns a new array. In the first form, the new array is
+ *  empty. In the second it is created with _size_ copies of _obj_
+ *  (that is, _size_ references to the same
+ *  _obj_). The third form creates a copy of the array
+ *  passed as a parameter (the array is generated by calling
+ *  to_ary  on the parameter). In the last form, an array
+ *  of the given size is created. Each element in this array is
+ *  calculated by passing the element's index to the given block and
+ *  storing the return value.
  *
- *   Array.new
- *   Array.new(2)
- *   Array.new(5, "A")
+ *     Array.new
+ *     Array.new(2)
+ *     Array.new(5, "A")
  * 
- *   # only one copy of the object is created
- *   a = Array.new(2, Hash.new)
- *   a[0]['cat'] = 'feline'
- *   a
- *   a[1]['cat'] = 'Felix'
- *   a
+ *     # only one copy of the object is created
+ *     a = Array.new(2, Hash.new)
+ *     a[0]['cat'] = 'feline'
+ *     a
+ *     a[1]['cat'] = 'Felix'
+ *     a
  * 
- *   # here multiple copies are created
- *   a = Array.new(2) { Hash.new }
- *   a[0]['cat'] = 'feline'
- *   a
+ *     # here multiple copies are created
+ *     a = Array.new(2) { Hash.new }
+ *     a[0]['cat'] = 'feline'
+ *     a
  * 
- *   squares = Array.new(5) {|i| i*i}
- *   squares
+ *     squares = Array.new(5) {|i| i*i}
+ *     squares
  * 
- *   copy = Array.new(squares)
+ *     copy = Array.new(squares)
  */
 
 static VALUE
@@ -384,13 +384,13 @@ rb_ary_store(ary, idx, val)
     RARRAY(ary)->ptr[idx] = val;
 }
 
-/* 
- * call-seq:
- *   array << obj            -> array
+/*
+ *  call-seq:
+ *     array << obj            -> array
  *  
- *   Append---Pushes the given object on to the end of this array. This
- *   expression returns the array itself, so several appends
- *   may be chained together.
+ *  Append---Pushes the given object on to the end of this array. This
+ *  expression returns the array itself, so several appends
+ *  may be chained together.
  *
  *     [ 1, 2 ] << "c" << "d" << [ 3, 4 ]
  *             #=>  [ 1, 2, "c", "d", [ 3, 4 ] ]
@@ -407,12 +407,12 @@ rb_ary_push(ary, item)
 }
 
 /* 
- * call-seq:
- *   array.push(obj, ... )   -> array
+ *  call-seq:
+ *     array.push(obj, ... )   -> array
  *  
- *   Append---Pushes the given object(s) on to the end of this array. This
- *   expression returns the array itself, so several appends
- *   may be chained together.
+ *  Append---Pushes the given object(s) on to the end of this array. This
+ *  expression returns the array itself, so several appends
+ *  may be chained together.
  *
  *     a = [ "a", "b", "c" ]
  *     a.push("d", "e", "f")  
@@ -607,23 +607,23 @@ rb_ary_subseq(ary, beg, len)
 }
 
 /* 
- * call-seq:
- *       array[index]                -> obj      or nil
- *       array[start, length]        -> an_array or nil
- *       array[range]                -> an_array or nil
- *       array.slice(index)          -> obj      or nil
- *       array.slice(start, length)  -> an_array or nil
- *       array.slice(range)          -> an_array or nil
+ *  call-seq:
+ *     array[index]                -> obj      or nil
+ *     array[start, length]        -> an_array or nil
+ *     array[range]                -> an_array or nil
+ *     array.slice(index)          -> obj      or nil
+ *     array.slice(start, length)  -> an_array or nil
+ *     array.slice(range)          -> an_array or nil
  *
- * Element Reference---Returns the element at _index_,
- * or returns a subarray starting at _start_ and
- * continuing for _length_ elements, or returns a subarray
- * specified by _range_.
- * Negative indices count backward from the end of the
- * array (-1 is the last element). Returns nil if any indices
- * are out of range unless the index equals the array size and a
- * _length_ or _range_ parameter is given, in which case an
- * empty array is returned.
+ *  Element Reference---Returns the element at _index_,
+ *  or returns a subarray starting at _start_ and
+ *  continuing for _length_ elements, or returns a subarray
+ *  specified by _range_.
+ *  Negative indices count backward from the end of the
+ *  array (-1 is the last element). Returns nil if any indices
+ *  are out of range unless the index equals the array size and a
+ *  _length_ or _range_ parameter is given, in which case an
+ *  empty array is returned.
  *
  *     a = [ "a", "b", "c", "d", "e" ]
  *     a[2] +  a[0] + a[1]    #=> "cab"
@@ -684,14 +684,14 @@ rb_ary_aref(argc, argv, ary)
 }
 
 /* 
- * call-seq:
- *      array.at(index)   ->   obj  or nil
+ *  call-seq:
+ *     array.at(index)   ->   obj  or nil
  *
- *   Returns the element at _index_. A
- *   negative index counts from the end of _self_.  Returns +nil+
- *   if the index is out of range. See also <code>Array#[]</code>.
- *   (<code>Array#at</code> is slightly faster than <code>Array#[]</code>,
- *   as it does not accept ranges and so on.)
+ *  Returns the element at _index_. A
+ *  negative index counts from the end of _self_.  Returns +nil+
+ *  if the index is out of range. See also <code>Array#[]</code>.
+ *  (<code>Array#at</code> is slightly faster than <code>Array#[]</code>,
+ *  as it does not accept ranges and so on.)
  *
  *     a = [ "a", "b", "c", "d", "e" ]
  *     a.at(0)     #=> "a"
@@ -986,22 +986,22 @@ rb_ary_update(ary, beg, len, rpl)
 }
 
 /* 
- * call-seq:
- *    array[index]         = obj                     ->  obj
- *    array[start, length] = obj or an_array or nil  ->  obj or an_array or nil
- *    array[range]         = obj or an_array or nil  ->  obj or an_array or nil
+ *  call-seq:
+ *     array[index]         = obj                     ->  obj
+ *     array[start, length] = obj or an_array or nil  ->  obj or an_array or nil
+ *     array[range]         = obj or an_array or nil  ->  obj or an_array or nil
  *
- *   Element Assignment---Sets the element at _index_,
- *   or replaces a subarray starting at _start_ and
- *   continuing for _length_ elements, or replaces a subarray
- *   specified by _range_.  If indices are greater than
- *   the current capacity of the array, the array grows
- *   automatically. A negative indices will count backward
- *   from the end of the array. Inserts elements if _length_ is
- *   zero. If +nil+ is used in the second and third form,
- *   deletes elements from _self_. An +IndexError+ is raised if a
- *   negative index points past the beginning of the array. See also
- *   <code>Array#push</code>, and <code>Array#unshift</code>.
+ *  Element Assignment---Sets the element at _index_,
+ *  or replaces a subarray starting at _start_ and
+ *  continuing for _length_ elements, or replaces a subarray
+ *  specified by _range_.  If indices are greater than
+ *  the current capacity of the array, the array grows
+ *  automatically. A negative indices will count backward
+ *  from the end of the array. Inserts elements if _length_ is
+ *  zero. If +nil+ is used in the second and third form,
+ *  deletes elements from _self_. An +IndexError+ is raised if a
+ *  negative index points past the beginning of the array. See also
+ *  <code>Array#push</code>, and <code>Array#unshift</code>.
  * 
  *     a = Array.new
  *     a[4] = "4";                 #=> [nil, nil, nil, nil, "4"]
@@ -1426,10 +1426,10 @@ inspect_ary(ary)
 }
 
 /*
- * call-seq:
- *   array.inspect  -> string
+ *  call-seq:
+ *     array.inspect  -> string
  *
- * Create a printable version of <i>array</i>.
+ *  Create a printable version of <i>array</i>.
  */
 
 static VALUE
@@ -1662,13 +1662,13 @@ rb_ary_collect(ary)
 }
 
 /* 
- * call-seq:
- *    array.collect! {|item| block }   ->   array
- *    array.map!     {|item| block }   ->   array
+ *  call-seq:
+ *     array.collect! {|item| block }   ->   array
+ *     array.map!     {|item| block }   ->   array
  *
- *   Invokes the block once for each element of _self_, replacing the
- *   element with the value returned by _block_.
- *   See also <code>Enumerable#collect</code>.
+ *  Invokes the block once for each element of _self_, replacing the
+ *  element with the value returned by _block_.
+ *  See also <code>Enumerable#collect</code>.
  *   
  *     a = [ "a", "b", "c", "d" ]
  *     a.collect! {|x| x + "!" }
@@ -1722,19 +1722,19 @@ rb_values_at(obj, olen, argc, argv, func)
 }
 
 /* 
- * call-seq:
- *   array.values_at(selector,... )  -> an_array
+ *  call-seq:
+ *     array.values_at(selector,... )  -> an_array
  *
- *   Returns an array containing the elements in
- *   _self_ corresponding to the given selector(s). The selectors
- *   may be either integer indices or ranges. 
- *   See also <code>Array#select</code>.
+ *  Returns an array containing the elements in
+ *  _self_ corresponding to the given selector(s). The selectors
+ *  may be either integer indices or ranges. 
+ *  See also <code>Array#select</code>.
  * 
- *      a = %w{ a b c d e f }
- *      a.values_at(1, 3, 5)
- *      a.values_at(1, 3, 5, 7)
- *      a.values_at(-1, -3, -5, -7)
- *      a.values_at(1..3, 2...5)
+ *     a = %w{ a b c d e f }
+ *     a.values_at(1, 3, 5)
+ *     a.values_at(1, 3, 5, 7)
+ *     a.values_at(-1, -3, -5, -7)
+ *     a.values_at(1..3, 2...5)
  */
 
 static VALUE
@@ -2243,11 +2243,11 @@ rb_ary_fill(argc, argv, ary)
 }
 
 /* 
- * call-seq:
- *    array + other_array   -> an_array
+ *  call-seq:
+ *     array + other_array   -> an_array
  *
- *   Concatenation---Returns a new array built by concatenating the
- *   two arrays together to produce a third array.
+ *  Concatenation---Returns a new array built by concatenating the
+ *  two arrays together to produce a third array.
  * 
  *     [ 1, 2, 3 ] + [ 4, 5 ]    #=> [ 1, 2, 3, 4, 5 ]
  */
@@ -2269,8 +2269,8 @@ rb_ary_plus(x, y)
 }
 
 /* 
- * call-seq:
- *   array.concat(other_array)   ->  array
+ *  call-seq:
+ *     array.concat(other_array)   ->  array
  *
  *  Appends the elements in other_array to _self_.
  *  
@@ -2291,13 +2291,13 @@ rb_ary_concat(x, y)
 
 
 /* 
- * call-seq:
+ *  call-seq:
  *     array * int     ->    an_array
  *     array * str     ->    a_string
  *
- *   Repetition---With a String argument, equivalent to
- *   self.join(str). Otherwise, returns a new array
- *   built by concatenating the _int_ copies of _self_.
+ *  Repetition---With a String argument, equivalent to
+ *  self.join(str). Otherwise, returns a new array
+ *  built by concatenating the _int_ copies of _self_.
  *
  *
  *     [ 1, 2, 3 ] * 3    #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]
@@ -2339,16 +2339,16 @@ rb_ary_times(ary, times)
 }
 
 /* 
- *   call-seq:
+ *  call-seq:
  *     array.assoc(obj)   ->  an_array  or  nil
  *
- *   Searches through an array whose elements are also arrays
- *   comparing _obj_ with the first element of each contained array
- *   using obj.==.
- *   Returns the first contained array that matches (that
- *   is, the first associated array),
- *   or +nil+ if no match is found.
- *   See also <code>Array#rassoc</code>.
+ *  Searches through an array whose elements are also arrays
+ *  comparing _obj_ with the first element of each contained array
+ *  using obj.==.
+ *  Returns the first contained array that matches (that
+ *  is, the first associated array),
+ *  or +nil+ if no match is found.
+ *  See also <code>Array#rassoc</code>.
  *
  *     s1 = [ "colors", "red", "blue", "green" ]
  *     s2 = [ "letters", "a", "b", "c" ]
@@ -2411,12 +2411,12 @@ rb_ary_rassoc(ary, value)
 }
 
 /* 
- * call-seq:
- *   array == other_array   ->   bool
+ *  call-seq:
+ *     array == other_array   ->   bool
  *
- *   Equality---Two arrays are equal if they contain the same number
- *   of elements and if each element is equal to (according to
- *   Object.==) the corresponding element in the other array.
+ *  Equality---Two arrays are equal if they contain the same number
+ *  of elements and if each element is equal to (according to
+ *  Object.==) the corresponding element in the other array.
  *
  *     [ "a", "c" ]    == [ "a", "c", 7 ]     #=> false
  *     [ "a", "c", 7 ] == [ "a", "c", 7 ]     #=> true
@@ -2446,11 +2446,11 @@ rb_ary_equal(ary1, ary2)
 }
 
 /*
- * call-seq:
- *   array.eql?(other)  -> true or false
+ *  call-seq:
+ *     array.eql?(other)  -> true or false
  *
- * Returns <code>true</code> if _array_ and _other_ are the same object,
- * or are both arrays with the same content.
+ *  Returns <code>true</code> if _array_ and _other_ are the same object,
+ *  or are both arrays with the same content.
  */
 
 static VALUE
@@ -2470,11 +2470,11 @@ rb_ary_eql(ary1, ary2)
 }
 
 /*
- * call-seq:
- *   array.hash   -> fixnum
+ *  call-seq:
+ *     array.hash   -> fixnum
  *
- * Compute a hash-code for this array. Two arrays with the same content
- * will have the same hash code (and will compare using <code>eql?</code>).
+ *  Compute a hash-code for this array. Two arrays with the same content
+ *  will have the same hash code (and will compare using <code>eql?</code>).
  */
 
 static VALUE
@@ -2523,19 +2523,19 @@ rb_ary_includes(ary, item)
 
 
 /* 
- * call-seq:
- *   array <=> other_array   ->  -1, 0, +1
+ *  call-seq:
+ *     array <=> other_array   ->  -1, 0, +1
  *
- *   Comparison---Returns an integer (-1, 0,
- *   or +1) if this array is less than, equal to, or greater than
- *   other_array.  Each object in each array is compared
- *   (using <=>). If any value isn't
- *   equal, then that inequality is the return value. If all the
- *   values found are equal, then the return is based on a
- *   comparison of the array lengths.  Thus, two arrays are
- *   ``equal'' according to <code>Array#<=></code> if and only if they have
- *   the same length and the value of each element is equal to the
- *   value of the corresponding element in the other array.
+ *  Comparison---Returns an integer (-1, 0,
+ *  or +1) if this array is less than, equal to, or greater than
+ *  other_array.  Each object in each array is compared
+ *  (using <=>). If any value isn't
+ *  equal, then that inequality is the return value. If all the
+ *  values found are equal, then the return is based on a
+ *  comparison of the array lengths.  Thus, two arrays are
+ *  ``equal'' according to <code>Array#<=></code> if and only if they have
+ *  the same length and the value of each element is equal to the
+ *  value of the corresponding element in the other array.
  *  
  *     [ "a", "a", "c" ]    <=> [ "a", "b", "c" ]   #=> -1
  *     [ 1, 2, 3, 4, 5, 6 ] <=> [ 1, 2 ]            #=> +1
@@ -2584,13 +2584,13 @@ ary_make_hash(ary1, ary2)
 }
 
 /* 
- * call-seq:
+ *  call-seq:
  *     array - other_array    -> an_array
  *
- *   Array Difference---Returns a new array that is a copy of
- *   the original array, removing any items that also appear in
- *   other_array. (If you need set-like behavior, see the
- *   library class Set.)
+ *  Array Difference---Returns a new array that is a copy of
+ *  the original array, removing any items that also appear in
+ *  other_array. (If you need set-like behavior, see the
+ *  library class Set.)
  *
  *     [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ]  #=>  [ 3, 3, 5 ]
  */
@@ -2613,13 +2613,13 @@ rb_ary_diff(ary1, ary2)
 }
 
 /* 
- * call-seq:
- *   array & other_array
+ *  call-seq:
+ *     array & other_array
  *
- *   Set Intersection---Returns a new array
- *   containing elements common to the two arrays, with no duplicates.
+ *  Set Intersection---Returns a new array
+ *  containing elements common to the two arrays, with no duplicates.
  *
- *      [ 1, 1, 3, 5 ] & [ 1, 2, 3 ]   #=> [ 1, 3 ]
+ *     [ 1, 1, 3, 5 ] & [ 1, 2, 3 ]   #=> [ 1, 3 ]
  */
 
 
@@ -2646,13 +2646,13 @@ rb_ary_and(ary1, ary2)
 }
 
 /* 
- * call-seq:
- *    array | other_array     ->  an_array
+ *  call-seq:
+ *     array | other_array     ->  an_array
  *
  *  Set Union---Returns a new array by joining this array with
  *  other_array, removing duplicates.
  *
- *    [ "a", "b", "c" ] | [ "c", "d", "a" ]
+ *     [ "a", "b", "c" ] | [ "c", "d", "a" ]
  *            #=> [ "a", "b", "c", "d" ]
  */
 
@@ -2745,11 +2745,12 @@ rb_ary_uniq(ary)
 }
 
 /* 
- * call-seq:
- *      array.compact!    ->   array  or  nil
+ *  call-seq:
+ *     array.compact!    ->   array  or  nil
  *
  *  Removes +nil+ elements from array.
  *  Returns +nil+ if no changes were made.
+ *
  *     [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
  *     [ "a", "b", "c" ].compact!           #=> nil
  */
@@ -2777,13 +2778,13 @@ rb_ary_compact_bang(ary)
     return ary;
 }
 
-/* 
- * call-seq:
- *    array.compact     ->  an_array
+/*
+ *  call-seq:
+ *     array.compact     ->  an_array
  *
- * Returns a copy of _self_ with all +nil+ elements removed.
- *   
- *      [ "a", nil, "b", nil, "c", nil ].compact
+ *  Returns a copy of _self_ with all +nil+ elements removed.
+ *
+ *     [ "a", nil, "b", nil, "c", nil ].compact
  *                       #=> [ "a", "b", "c" ]
  */