Do the Splice Docs on Length Need Tweak?

QM has asked for the wisdom of the Perl Monks concerning the following question:

I recently looked up something on splice. Specifically, I wanted to insert something in an array, but not delete anything.

While it's implicit that a length of zero should not remove anything, and only insert the given list, it's not explicit. Should it be?

Specifically, should the documentation include a line like so:

If LENGTH is zero, nothing is removed.

That would have reduced my time reading the doc, or needing to TIAS.

Or maybe I've misread something in my haste, and it's there, plain as day?

-QM
--
Quantum Mechanics: The dreams stuff is made of

Comment on Do the Splice Docs on Length Need Tweak?

Replies are listed 'Best First'.
Re: Do the Splice Docs on Length Need Tweak? by Eily (Monsignor) on Apr 29, 2019 at 13:55 UTC
The doc looks clear enough to me, but maybe it's because I already knew splice's behaviour. Were you expecting something else instead? Like zero being equivalent to an omitted length, where everything until the end is removed? The unshift example does show explicitly that a length of 0 removes nothing, but it requires understanding unshift, which is not beginner friendly. Maybe the examples list could include an insertion and removal, which is would be more helpful than things that can be done using more specific functions. Edit: I realized that while the case where LENGTH is omitted or negative are explicitly described, the case where it's positive is only implied because of the name of the parameter. So, rather than the specific case of zero, "If LENGTH is positive (or zero), LENGTH elements are removed".	[reply]
Re^2: Do the Splice Docs on Length Need Tweak? by QM (Parson) on Apr 30, 2019 at 08:04 UTC
As usual when I post, what's obvious to me doesn't get written down. :/ I should have added: Here's my use case: `splice(@array, 7, 0, qw(stuff I want to insert));` [download] So if I want to insert something, but not remove anything, I need a length of zero. -QM -- Quantum Mechanics: The dreams stuff is made of	[reply] [d/l]
Re: Do the Splice Docs on Length Need Tweak? by roboticus (Chancellor) on Apr 29, 2019 at 15:03 UTC
QM: The documentation seems clear enough to me, but I can see where a little extra info could help. I think I'd suggest adding "If LENGTH is zero, nothing is removed. " just before the "If LENGTH is omitted" bit. It might also be helpful to rearrange the examples under "The following equivalences hold" bit with a couple comments: `# delete nothing but add to end or beginning of array: push @a,$x,$y splice(@a,@a,0,$x,$y) unshift @a,$x,$y splice(@a,0,0,$x,$y) # Remove first or last item from array: $t=pop @a $t=splice(@a,-1) $t=shift @a $t=splice(@a,0,1) # Replace item in middle of array $a[$i]=$y splice(@a,$i,1,$y)` [download] ...roboticus When your only tool is a hammer, all problems look like your thumb.	[reply] [d/l]
Re: Do the Splice Docs on Length Need Tweak? by Anonymous Monk on Apr 29, 2019 at 14:37 UTC
If LENGTH is zero, nothing is removed. if LENGTH is 3, three elements are removed. if LENGTH is 2, two elements are removed. if LENGTH is 1, one element is removed. if LENGTH is 0, ...	[reply]