ruby-changes:23807
From: drbrain <ko1@a...>
Date: Fri, 1 Jun 2012 08:51:43 +0900 (JST)
Subject: [ruby-changes:23807] drbrain:r35858 (trunk): * array.c: Updated Array documentation formatting. Patch by Zachary
drbrain 2012-06-01 08:51:33 +0900 (Fri, 01 Jun 2012) New Revision: 35858 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=35858 Log: * array.c: Updated Array documentation formatting. Patch by Zachary Scott. [ruby-trunk - Feature #6517] Modified files: trunk/ChangeLog trunk/array.c Index: array.c =================================================================== --- array.c (revision 35857) +++ array.c (revision 35858) @@ -274,6 +274,16 @@ } } +/* + * call-seq: + * ary.freeze -> ary + * + * Calls Object#freeze on +ary+ to prevent any further + * modification. A RuntimeError will be raised if a modification + * attempt is made. + * + */ + VALUE rb_ary_freeze(VALUE ary) { @@ -284,8 +294,8 @@ * call-seq: * ary.frozen? -> true or false * - * Return <code>true</code> if this array is frozen (or temporarily frozen - * while being sorted). + * Return +true+ if this array is frozen (or temporarily frozen + * while being sorted). See also Object#frozen? */ static VALUE @@ -772,13 +782,16 @@ * call-seq: * ary.push(obj, ... ) -> ary * - * Append---Pushes the given object(s) on to the end of this array. This + * 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. + * may be chained together. See also Array#pop for the opposite + * effect. * * a = [ "a", "b", "c" ] * a.push("d", "e", "f") * #=> ["a", "b", "c", "d", "e", "f"] + * [1, 2, 3,].push(4).push(5) + * #=> [1, 2, 3, 4, 5] */ static VALUE @@ -810,10 +823,11 @@ * ary.pop(n) -> new_ary * * Removes the last element from +self+ and returns it, or - * <code>nil</code> if the array is empty. + * +nil+ if the array is empty. * - * If a number +n+ is given, returns an array of the last n elements - * (or less) just like <code>array.slice!(-n, n)</code> does. + * If a number +n+ is given, returns an array of the last +n+ elements + * (or less) just like <code>array.slice!(-n, n)</code> does. See also + * Array#push for the opposite effect. * * a = [ "a", "b", "c", "d" ] * a.pop #=> "d" @@ -869,12 +883,14 @@ * ary.shift -> obj or nil * ary.shift(n) -> new_ary * - * Returns the first element of +self+ and removes it (shifting all - * other elements down by one). Returns <code>nil</code> if the array + * Removes the first element of +self+ and returns it (shifting all + * other elements down by one). Returns +nil+ if the array * is empty. * - * If a number +n+ is given, returns an array of the first n elements - * (or less) just like <code>array.slice!(0, n)</code> does. + * If a number +n+ is given, returns an array of the first +n+ elements + * (or less) just like <code>array.slice!(0, n)</code> does. With +ary+ + * containing only the remainder elements, not including what was shifted to + * +new_ary+. See also Array#unshift for the opposite effect. * * args = [ "-m", "-q", "filename" ] * args.shift #=> "-m" @@ -916,8 +932,8 @@ * call-seq: * ary.unshift(obj, ...) -> ary * - * Prepends objects to the front of +self+, - * moving other elements upwards. + * Prepends objects to the front of +self+, moving other elements upwards. + * See also Array#shift for the opposite effect. * * a = [ "b", "c", "d" ] * a.unshift("a") #=> ["a", "b", "c", "d"] @@ -1056,9 +1072,9 @@ * call-seq: * ary.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>. + * 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 + * Array#[]. * * a = [ "a", "b", "c", "d", "e" ] * a.at(0) #=> "a" @@ -1077,8 +1093,9 @@ * ary.first(n) -> new_ary * * Returns the first element, or the first +n+ elements, of the array. - * If the array is empty, the first form returns <code>nil</code>, and the - * second form returns an empty array. + * If the array is empty, the first form returns +nil+, and the + * second form returns an empty array. See also Array#last for + * the opposite effect. * * a = [ "q", "r", "s", "t" ] * a.first #=> "q" @@ -1103,8 +1120,10 @@ * ary.last(n) -> new_ary * * Returns the last element(s) of +self+. If the array is empty, - * the first form returns <code>nil</code>. + * the first form returns +nil+. * + * See also Array#first for the opposite effect. + * * a = [ "w", "x", "y", "z" ] * a.last #=> "z" * a.last(2) #=> ["y", "z"] @@ -1125,22 +1144,18 @@ /* * call-seq: * ary.fetch(index) -> obj - * ary.fetch(index, default ) -> obj - * ary.fetch(index) {|index| block } -> obj + * ary.fetch(index, default) -> obj + * ary.fetch(index) { |index| block } -> obj * - * Tries to return the element at position +index+. If the index lies outside - * the array, the first form throws an IndexError exception, the second form - * returns +default+, and the third form returns the value of invoking the - * block, passing in the index. Negative values of +index+ count from the end - * of the array. - * * Tries to return the element at position +index+, but throws an IndexError - * exception if the referenced index lies outside of the array bounds. This + * exception if the referenced +index+ lies outside of the array bounds. This * error can be prevented by supplying a second argument, which will act as a - * +default+ value. Alternatively, if the second argument is a block it will - * only be executed when an invalid index is referenced. Negative values of - * +index+ count from the end of the array. + * +default+ value. * + * Alternatively, if a block is given it will only be executed when an + * invalid +index+ is referenced. Negative values of +index+ count from the + * end of the array. + * * a = [ 11, 22, 33, 44 ] * a.fetch(1) #=> 22 * a.fetch(-1) #=> 44 @@ -1179,24 +1194,27 @@ /* * call-seq: - * ary.index(obj) -> int or nil - * ary.index {|item| block} -> int or nil - * ary.index -> an_enumerator + * ary.index(obj) -> int or nil + * ary.index { |item| block } -> int or nil + * ary.index -> Enumerator * - * Returns the index of the first object in +self+ such that the object is - * <code>==</code> to +obj+. If a block is given instead of an - * argument, returns index of first object for which <em>block</em> is true. - * Returns <code>nil</code> if no match is found. - * See also <code>Array#rindex</code>. + * Returns the _index_ of the first object in +ary+ such that the object is + * <code>==</code> to +obj+. * - * If neither block nor argument is given, an enumerator is returned instead. + * If a block is given instead of an argument, returns the _index_ of first + * the object for which the block returns +true+. Returns +nil+ if no match + * is found. * + * See also Array#rindex. + * + * An Enumerator is returned if neither a block nor argument is given. + * * a = [ "a", "b", "c" ] - * a.index("b") #=> 1 - * a.index("z") #=> nil - * a.index{|x|x=="b"} #=> 1 + * a.index("b") #=> 1 + * a.index("z") #=> nil + * a.index { |x| x == "b" } #=> 1 * - * This is an alias of <code>#find_index</code>. + * This is an alias of Array#find_index. */ static VALUE @@ -1226,18 +1244,20 @@ /* * call-seq: - * ary.rindex(obj) -> int or nil - * ary.rindex {|item| block} -> int or nil - * ary.rindex -> an_enumerator + * ary.rindex(obj) -> int or nil + * ary.rindex { |item| block } -> int or nil + * ary.rindex -> Enumerator * - * Returns the index of the last object in +self+ - * <code>==</code> to +obj+. If a block is given instead of an - * argument, returns index of first object for which <em>block</em> is - * true, starting from the last object. - * Returns <code>nil</code> if no match is found. + * Returns the _index_ of the last object in +self+ <code>==</code> to +obj+. + * + * If a block is given instead of an argument, returns _index_ of first object + * for which block returns +true+, starting from the last object. + * + * Returns +nil+ if no match is found. + * * See also Array#index. * - * If neither block nor argument is given, an enumerator is returned instead. + * If neither block nor argument is given, an Enumerator is returned instead. * * a = [ "a", "b", "b", "b", "c" ] * a.rindex("b") #=> 3 @@ -1409,17 +1429,19 @@ * ary[start, length] = obj or other_ary or nil -> obj or other_ary or nil * ary[range] = obj or other_ary or nil -> obj or other_ary 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. An IndexError is raised if a negative index points - * past the beginning of the array. See also - * Array#push, and Array#unshift. + * Element Assignment --- Sets the element at +index+, or replaces a subarray + * from +start+ 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. Negative indices will count backward from the end of + * the array. Inserts elements if +length+ is zero. + * + * An IndexError is raised if a negative index points past the beginning of + * the array. + * + * See also Array#push, and Array#unshift. + * * a = Array.new * a[4] = "4"; #=> [nil, nil, nil, nil, "4"] * a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"] @@ -1465,9 +1487,11 @@ * call-seq: * ary.insert(index, obj...) -> ary * - * Inserts the given values before the element with the given index - * (which may be negative). + * Inserts the given values before the element with the given +index+. * + * Negative indices count backwards from the end of the array, where +-1+ is + * the last element. + * * a = %w{ a b c d } * a.insert(2, 99) #=> ["a", "b", 99, "c", "d"] * a.insert(-2, 1, 2, 3) #=> ["a", "b", 99, "c", 1, 2, 3, "d"] @@ -1494,13 +1518,13 @@ /* * call-seq: - * ary.each {|item| block } -> ary - * ary.each -> an_enumerator + * ary.each { |item| block } -> ary + * ary.each -> Enumerator * - * Calls +block+ once for each element in +self+, passing that - * element as a parameter. + * Calls the given block once for each element in +self+, passing that element + * as a parameter. * - * If no block is given, an enumerator is returned instead. + * An Enumerator is returned if no block is given. * * a = [ "a", "b", "c" ] * a.each {|x| print x, " -- " } @@ -1525,15 +1549,14 @@ /* * call-seq: - * ary.each_index {|index| block } -> ary - * ary.each_index -> an_enumerator + * ary.each_index { |index| block } -> ary + * ary.each_index -> Enumerator * - * Same as Array#each, but passes the index of the element instead of the + * Same as Array#each, but passes the +index+ of the element instead of the * element itself. * - * If no block is given, an enumerator is returned instead. + * An Enumerator is returned if no block is given. * - * * a = [ "a", "b", "c" ] * a.each_index {|x| print x, " -- " } * @@ -1556,8 +1579,8 @@ /* * call-seq: - * ary.reverse_each {|item| block } -> ary - * ary.reverse_each -> an_enumerator + * ary.reverse_each { |item| block } -> ary + * ary.reverse_each -> Enumerator * * Same as Array#each, but traverses +self+ in reverse order. * @@ -1592,6 +1615,7 @@ * Returns the number of elements in +self+. May be zero. * * [ 1, 2, 3, 4, 5 ].length #=> 5 + * [].length #=> 0 */ static VALUE @@ -1605,7 +1629,7 @@ * call-seq: * ary.empty? -> true or false * - * Returns <code>true</code> if +self+ contains no elements. + * Returns +true+ if +self+ contains no elements. * * [].empty? #=> true */ @@ -1771,10 +1795,10 @@ /* * call-seq: - * ary.join(sep=$,) -> str + * ary.join(separator=$,) -> str * * Returns a string created by converting each element of the array to - * a string, separated by +sep+. + * a string, separated by the given +separator+. * * [ "a", "b", "c" ].join #=> "abc" * [ "a", "b", "c" ].join("-") #=> "a-b-c" @@ -1817,10 +1841,12 @@ /* * call-seq: - * ary.to_s -> string * ary.inspect -> string + * ary.to_s -> string * * Creates a string representation of +self+. + * + * [ "a", "b", "c" ].to_s #=> "[\"a\", \"b\", \"c\"]" */ static VALUE @@ -1840,8 +1866,9 @@ * call-seq: * ary.to_a -> ary * - * Returns +self+. If called on a subclass of Array, converts - * the receiver to an Array object. + * Returns +self+. + * + * If called on a subclass of Array, converts the receiver to an Array object. */ static VALUE @@ -1912,7 +1939,7 @@ /* * call-seq: - * ary.reverse -> new_ary + * ary.reverse -> new_ary * * Returns a new array containing +self+'s elements in reverse order. * @@ -1964,12 +1991,14 @@ /* * call-seq: - * ary.rotate!(cnt=1) -> ary + * ary.rotate!(count=1) -> ary * - * Rotates +self+ in place so that the element at +cnt+ comes first, - * and returns +self+. If +cnt+ is negative then it rotates in - * the opposite direction. + * Rotates +self+ in place so that the element at +count+ comes first, and + * returns +self+. * + * If +count+ is negative then it rotates in the opposite direction, starting + * from the end of the array where +-1+ is the last element. + * * a = [ "a", "b", "c", "d" ] * a.rotate! #=> ["b", "c", "d", "a"] * a #=> ["b", "c", "d", "a"] @@ -1993,12 +2022,14 @@ /* * call-seq: - * ary.rotate(cnt=1) -> new_ary + * ary.rotate(count=1) -> new_ary * - * Returns new array by rotating +self+ so that the element at - * +cnt+ in +self+ is the first element of the new array. If +cnt+ - * is negative then it rotates in the opposite direction. + * Returns new array by rotating +self+ so that the element at +count+ is the + * first element of the new array. * + * If +count+ is negative then it rotates in the opposite direction, starting + * from the end of +self+ where +-1+ is the last element. + * * a = [ "a", "b", "c", "d" ] * a.rotate #=> ["b", "c", "d", "a"] * a #=> ["a", "b", "c", "d"] @@ -2104,17 +2135,22 @@ /* * call-seq: * ary.sort! -> ary - * ary.sort! {| a,b | block } -> ary + * ary.sort! { |a, b| block } -> ary * - * Sorts +self+. Comparisons for - * the sort will be done using the <code><=></code> operator or using - * an optional code block. The block implements a comparison between - * +a+ and +b+, returning -1, 0, or +1. See also - * Enumerable#sort_by. + * Sorts +self+ in place. * + * Comparisons for the sort will be done using the <code><=></code> operator + * or using an optional code block. + * + * The block must implement a comparison between +a+ and +b+, and return + * +-1+, when +a+ follows +b+, +0+ when +a+ and +b+ are equivalent, or ++1+ + * if +b+ follows +a+. + * + * See also Enumerable#sort_by. + * * a = [ "d", "a", "e", "c", "b" ] * a.sort! #=> ["a", "b", "c", "d", "e"] - * a.sort! {|x,y| y <=> x } #=> ["e", "d", "c", "b", "a"] + * a.sort! { |x,y| y <=> x } #=> ["e", "d", "c", "b", "a"] */ VALUE @@ -2180,17 +2216,23 @@ /* * call-seq: * ary.sort -> new_ary - * ary.sort {| a,b | block } -> new_ary + * ary.sort { |a, b| block } -> new_ary * - * Returns a new array created by sorting +self+. Comparisons for - * the sort will be done using the <code><=></code> operator or using - * an optional code block. The block implements a comparison between - * +a+ and +b+, returning -1, 0, or +1. See also - * Enumerable#sort_by. + * Returns a new array created by sorting +self+. * + * Comparisons for the sort will be done using the <code><=></code> operator + * or using an optional code block. + * + * The block must implement a comparison between +a+ and +b+, and return + * +-1+, when +a+ follows +b+, +0+ when +a+ and +b+ are equivalent, or ++1+ + * if +b+ follows +a+. + * + * + * See also Enumerable#sort_by. + * * a = [ "d", "a", "e", "c", "b" ] * a.sort #=> ["a", "b", "c", "d", "e"] - * a.sort {|x,y| y <=> x } #=> ["e", "d", "c", "b", "a"] + * a.sort { |x,y| y <=> x } #=> ["e", "d", "c", "b", "a"] */ VALUE @@ -2210,13 +2252,13 @@ /* * call-seq: - * ary.sort_by! {| obj | block } -> ary - * ary.sort_by! -> an_enumerator + * ary.sort_by! { |obj| block } -> ary + * ary.sort_by! -> Enumerator * * Sorts +self+ in place using a set of keys generated by mapping the * values in +self+ through the given block. * - * If no block is given, an enumerator is returned instead. + * If no block is given, an Enumerator is returned instead. * */ @@ -2235,20 +2277,22 @@ /* * call-seq: - * ary.collect {|item| block } -> new_ary - * ary.map {|item| block } -> new_ary - * ary.collect -> an_enumerator - * ary.map -> an_enumerator + * ary.collect { |item| block } -> new_ary + * ary.map { |item| block } -> new_ary + * ary.collect -> Enumerator + * ary.map -> Enumerator * - * Invokes +block+ once for each element of +self+. Creates a - * new array containing the values returned by the block. + * Invokes the given block once for each element of +self+. + * + * Creates a new array containing the values returned by the block. + * * See also Enumerable#collect. * - * If no block is given, an enumerator is returned instead. + * If no block is given, an Enumerator is returned instead. * * a = [ "a", "b", "c", "d" ] - * a.map {|x| x + "!" } #=> ["a!", "b!", "c!", "d!"] - * a #=> ["a", "b", "c", "d"] + * a.map { |x| x + "!" } #=> ["a!", "b!", "c!", "d!"] + * a #=> ["a", "b", "c", "d"] */ static VALUE @@ -2270,14 +2314,15 @@ * call-seq: * ary.collect! {|item| block } -> ary * ary.map! {|item| block } -> ary - * ary.collect -> an_enumerator - * ary.map -> an_enumerator + * ary.collect! -> Enumerator + * ary.map! -> Enumerator * - * Invokes the block once for each element of +self+, replacing the - * element with the value returned by +block+. + * Invokes the given block once for each element of +self+, replacing the + * element with the value returned by the block. + * * See also Enumerable#collect. * - * If no block is given, an enumerator is returned instead. + * If no block is given, an Enumerator is returned instead. * * a = [ "a", "b", "c", "d" ] * a.map! {|x| x + "!" } @@ -2327,11 +2372,13 @@ /* * call-seq: - * ary.values_at(selector,... ) -> new_ary + * (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/