Update to Array#join

This is my first attempt to post a documentation patch so
don't be
too harsh. I just used 'svn diff array.c' against the 1.8.5
branch.
Should I be submitting diffs against trunk?

This patch clarifies the behavior of Array#join and was
prompted by a recent thread on ruby-talk.

Gary Wright


Index: array.c
============================================================
=======
--- array.c     (revision 11744)
+++ array.c     (working copy)
 -1299,11
+1299,16 
   *  call-seq:
   *     array.join(sep=$,)    -> str
   *
- *  Returns a string created by converting each element of
the array to
- *  a string, separated by <i>sep</i>.
+ *  Returns a string created by converting each element of
the array
+ *  to a string, separated by <i>sep</i>. For
every element that is an
+ *  array, the element is converted to a string by applying
the  
conversion
+ *  procedure recursively. Elements that are not strings or
arrays are
+ *  converted by calling to_s.
   *
- *     [ "a", "b", "c" ].join
       #=> "abc"
- *     [ "a", "b", "c"
].join("-")   #=> "a-b-c"
+ *     [ "a", "b", "c" ].join
            #=> "abc"
+ *     [ "a", "b", "c"
].join("-")        #=> "a-b-c"
+ *     [ "w", ["x", "y"],
"z"].join("-")  #=>
"w-x-y-z"
+ *     [ nil, :a, 1].join("/")            #=>
"/a/1"
   */
static VALUE

I think it's far clearer to simply say that the array is
flattened  
(in effect, though not by calling #flatten) before being
joined.

On Feb 14, 2007, at 5:57 PM, Gary Wright wrote:

> This is my first attempt to post a documentation patch
so don't be
> too harsh. I just used 'svn diff array.c' against the
1.8.5 branch.
> Should I be submitting diffs against trunk?
>
> This patch clarifies the behavior of Array#join and
was
> prompted by a recent thread on ruby-talk.
>
> Gary Wright
>
>
> Index: array.c
>
============================================================
=======
> --- array.c     (revision 11744)
> +++ array.c     (working copy)
>  -1299,11 +1299,16 
>   *  call-seq:
>   *     array.join(sep=$,)    -> str
>   *
> - *  Returns a string created by converting each
element of the  
> array to
> - *  a string, separated by <i>sep</i>.
> + *  Returns a string created by converting each
element of the array
> + *  to a string, separated by <i>sep</i>.
For every element that  
> is an
> + *  array, the element is converted to a string by
applying the  
> conversion
> + *  procedure recursively. Elements that are not
strings or arrays  
> are
> + *  converted by calling to_s.
>   *
> - *     [ "a", "b", "c"
].join        #=> "abc"
> - *     [ "a", "b", "c"
].join("-")   #=> "a-b-c"
> + *     [ "a", "b", "c"
].join             #=> "abc"
> + *     [ "a", "b", "c"
].join("-")        #=> "a-b-c"
> + *     [ "w", ["x",
"y"], "z"].join("-")  #=>
"w-x-y-z"
> + *     [ nil, :a, 1].join("/")           
#=> "/a/1"
>   */
> static VALUE
>
>

On 2/14/07, Gary Wright <gwtmp01mac.com> wrote:
> This is my first attempt to post a documentation patch
so don't be
> too harsh. I just used 'svn diff array.c' against the
1.8.5 branch.
> Should I be submitting diffs against trunk?
>
> This patch clarifies the behavior of Array#join and
was
> prompted by a recent thread on ruby-talk.
>
> Gary Wright
>
>
> Index: array.c
>
============================================================
=======
> --- array.c     (revision 11744)
> +++ array.c     (working copy)
>  -1299,11 +1299,16 
>    *  call-seq:
>    *     array.join(sep=$,)    -> str
>    *
> - *  Returns a string created by converting each
element of the array to
> - *  a string, separated by <i>sep</i>.
> + *  Returns a string created by converting each
element of the array
> + *  to a string, separated by <i>sep</i>.
For every element that is an
> + *  array, the element is converted to a string by
applying the
> conversion
> + *  procedure recursively. Elements that are not
strings or arrays are
> + *  converted by calling to_s.
>    *
> - *     [ "a", "b", "c"
].join        #=> "abc"
> - *     [ "a", "b", "c"
].join("-")   #=> "a-b-c"
> + *     [ "a", "b", "c"
].join             #=> "abc"
> + *     [ "a", "b", "c"
].join("-")        #=> "a-b-c"
> + *     [ "w", ["x",
"y"], "z"].join("-")  #=>
"w-x-y-z"
> + *     [ nil, :a, 1].join("/")           
#=> "/a/1"
>    */
> static VALUE
>
>
>

Yes, you should be submitting diffs to trunk, but most of
the time it
doesn't take much/any work at all to do. See
<http://ruby-doc.org/documentation-guidelines.html>.

-- 
Konrad Meyer

I think it's far clearer to simply say that the array is
flattened  
(in effect, though not by calling #flatten) before being
joined.

On Feb 14, 2007, at 5:57 PM, Gary Wright wrote:

> This is my first attempt to post a documentation patch
so don't be
> too harsh. I just used 'svn diff array.c' against the
1.8.5 branch.
> Should I be submitting diffs against trunk?
>
> This patch clarifies the behavior of Array#join and
was
> prompted by a recent thread on ruby-talk.
>
> Gary Wright
>
>
> Index: array.c
>
============================================================
=======
> --- array.c     (revision 11744)
> +++ array.c     (working copy)
>  -1299,11 +1299,16 
>   *  call-seq:
>   *     array.join(sep=$,)    -> str
>   *
> - *  Returns a string created by converting each
element of the  
> array to
> - *  a string, separated by <i>sep</i>.
> + *  Returns a string created by converting each
element of the array
> + *  to a string, separated by <i>sep</i>.
For every element that  
> is an
> + *  array, the element is converted to a string by
applying the  
> conversion
> + *  procedure recursively. Elements that are not
strings or arrays  
> are
> + *  converted by calling to_s.
>   *
> - *     [ "a", "b", "c"
].join        #=> "abc"
> - *     [ "a", "b", "c"
].join("-")   #=> "a-b-c"
> + *     [ "a", "b", "c"
].join             #=> "abc"
> + *     [ "a", "b", "c"
].join("-")        #=> "a-b-c"
> + *     [ "w", ["x",
"y"], "z"].join("-")  #=>
"w-x-y-z"
> + *     [ nil, :a, 1].join("/")           
#=> "/a/1"
>   */
> static VALUE
>
>

On 2/14/07, Gary Wright <gwtmp01mac.com> wrote:
> This is my first attempt to post a documentation patch
so don't be
> too harsh. I just used 'svn diff array.c' against the
1.8.5 branch.
> Should I be submitting diffs against trunk?
>
> This patch clarifies the behavior of Array#join and
was
> prompted by a recent thread on ruby-talk.
>
> Gary Wright
>
>
> Index: array.c
>
============================================================
=======
> --- array.c     (revision 11744)
> +++ array.c     (working copy)
>  -1299,11 +1299,16 
>    *  call-seq:
>    *     array.join(sep=$,)    -> str
>    *
> - *  Returns a string created by converting each
element of the array to
> - *  a string, separated by <i>sep</i>.
> + *  Returns a string created by converting each
element of the array
> + *  to a string, separated by <i>sep</i>.
For every element that is an
> + *  array, the element is converted to a string by
applying the
> conversion
> + *  procedure recursively. Elements that are not
strings or arrays are
> + *  converted by calling to_s.
>    *
> - *     [ "a", "b", "c"
].join        #=> "abc"
> - *     [ "a", "b", "c"
].join("-")   #=> "a-b-c"
> + *     [ "a", "b", "c"
].join             #=> "abc"
> + *     [ "a", "b", "c"
].join("-")        #=> "a-b-c"
> + *     [ "w", ["x",
"y"], "z"].join("-")  #=>
"w-x-y-z"
> + *     [ nil, :a, 1].join("/")           
#=> "/a/1"
>    */
> static VALUE
>
>
>

Yes, you should be submitting diffs to trunk, but most of
the time it
doesn't take much/any work at all to do. See
<http://ruby-doc.org/documentation-guidelines.html>.

-- 
Konrad Meyer