# Bug or bad documentation for Array.insert()

**URL:** <https://www.ruby-forum.com/t/bug-or-bad-documentation-for-array-insert/111678>\
**Category:** Ruby\
**Created:** [August 9, 2007, 6:37pm UTC](https://www.ruby-forum.com/t/bug-or-bad-documentation-for-array-insert/111678 "2007-08-09T18:37:31Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![Markus\_E](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/dbc845/32.png) [@Markus\_E](https://www.ruby-forum.com/u/Markus_E)\
**Post date:** [August 9, 2007, 6:37pm UTC](https://www.ruby-forum.com/t/bug-or-bad-documentation-for-array-insert/111678/1 "2007-08-09T18:37:31Z")

</div>

I just came across ruby and noticed a difference between the behavior of  
Array.insert() and its documentation.

Method: [http://www.ruby-doc.org/core/classes/Array.src/M002195.html](http://www.ruby-doc.org/core/classes/Array.src/M002195.html)

From the RDoc it seems that two arguments are mandatory, yet  
Array.insert()  
only raises an error if there is no argument passed at all.

Code snippet from Array.insert():

```
if (argc == 1) return ary;
if (argc < 1) {
    rb_raise(rb_eArgError, "wrong number of arguments (at least 

```

1)");  
}

From my semantic understanding of an “insert” Method it should raise an  
error  
if called with less than two arguments, for silently returning the array  
can  
be irritating for beginners (Took me some time to figure it out).

best regards,  
Markus E.

---

<div class="post-metadata">

**Author:** ![Markus\_E](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/dbc845/32.png) [@Markus\_E](https://www.ruby-forum.com/u/Markus_E)\
**Post date:** [August 9, 2007, 7:56pm UTC](https://www.ruby-forum.com/t/bug-or-bad-documentation-for-array-insert/111678/2 "2007-08-09T19:56:42Z")

</div>

On Aug 9, 10:35 am, Markus E. [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) wrote:

> ```
> if (argc == 1) return ary;
> if (argc < 1) {
> rb_raise(rb_eArgError, "wrong number of arguments (at least 1)");
> }
> 
> ```
> 
> From my semantic understanding of an “insert” Method it should raise an error  
> if called with less than two arguments, for silently returning the array can  
> be irritating for beginners (Took me some time to figure it out).

Nope, the docs show that the second argument is optional. As it stands  
now there are a few methods like this scattered throughout Ruby where  
you can end up with what amounts to a no-op in certain situations,  
e.g. File.join with no arguments.

Not that I necessarily agree with the current semantics, but it is  
documented properly. It does require that you understand “obj…” to  
mean “0 or more”.

Regards,

Dan

---

<div class="post-metadata">

**Author:** ![Markus\_E](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/dbc845/32.png) [@Markus\_E](https://www.ruby-forum.com/u/Markus_E)\
**Post date:** [August 9, 2007, 9:16pm UTC](https://www.ruby-forum.com/t/bug-or-bad-documentation-for-array-insert/111678/3 "2007-08-09T21:16:51Z")

</div>

Markus E. wrote:

> ```
> if (argc == 1) return ary;
> if (argc < 1) {
> rb_raise(rb_eArgError, "wrong number of arguments (at least 1)");
> }
> 
> ```
> 
> From my semantic understanding of an “insert” Method it should raise an error  
> if called with less than two arguments, for silently returning the array can  
> be irritating for beginners (Took me some time to figure it out).

I think the semantics are just fine. Consider this case:

b = [] # maybe a result from some other method  
a.insert 23, \*b

I wouldn’t want an exception thrown here. It would make it necessary to  
check for b’s emptiness before every call to Array#insert. If people  
forget the check, it might cause an error when the impossible occurs  
anyway.

---

<div class="post-metadata">

**Author:** ![Markus\_E](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/m/dbc845/32.png) [@Markus\_E](https://www.ruby-forum.com/u/Markus_E)\
**Post date:** [August 12, 2007, 2:01pm UTC](https://www.ruby-forum.com/t/bug-or-bad-documentation-for-array-insert/111678/4 "2007-08-12T14:01:36Z")

</div>

On Thursday 09 August 2007 19:55:23 Daniel B. wrote:

> Dan

Thanks, when I read the “obj…” as you say it’s clear.

On Thursday 09 August 2007 21:15:43 Florian F. wrote:

> I think the semantics are just fine. Consider this case:
> 
> b = [] # maybe a result from some other method  
> a.insert 23, \*b
> 
> I wouldn’t want an exception thrown here. It would make it necessary to  
> check for b’s emptiness before every call to Array#insert. If people  
> forget the check, it might cause an error when the impossible occurs  
> anyway.

I think this is also true. I like errors thrown on everything I didn’t  
expect.  
I just hope this is a constant behavior and not changing from method to  
method, so that I can expect it and relax without argument checking.