Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change
 
PerlMonks  

Do the Splice Docs on Length Need Tweak?

by QM (Parson)
on Apr 29, 2019 at 13:36 UTC ( #1233117=perlquestion: print w/replies, xml ) Need Help??

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".

      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));

      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

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)

    ...roboticus

    When your only tool is a hammer, all problems look like your thumb.

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, ...

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://1233117]
Approved by marto
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others chanting in the Monastery: (8)
As of 2021-01-27 22:48 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Notices?