develooper Front page | perl.perl5.porters | Postings from October 2013

Re: [perl #120386] av_len documentation

Thread Previous | Thread Next
From:
Lukas Mai
Date:
October 30, 2013 08:43
Subject:
Re: [perl #120386] av_len documentation
Message ID:
5270C6A2.206@gmail.com
On 30.10.2013 06:27, Karl Williamson wrote:
> On 10/27/2013 03:56 PM, root@mail.nethype.de (via RT) wrote:
>> # New Ticket Created by  root@mail.nethype.de
>> # Please include the string:  [perl #120386]
>> # in the subject line of all future correspondence about this issue.
>> # <URL: https://rt.perl.org/Ticket/Display.html?id=120386 >
>>
>>
>>
>> This is a bug report for perl from root@mail.nethype.de,
>> generated with the help of perlbug 1.39 running under perl 5.18.1.
>>
>>
>> -----------------------------------------------------------------
>> [Please describe your issue here]
>>
>> The av_len documentation for 5.18.1 says:
>>
>>     Note that the return value is +1 what its name implies it returns;
>> and
>>     hence differs in meaning from what the similarly named "sv_len"
>> returns.
>>
>> That seems wrong. Shouldn't it be:
>>
>>     Note that the return value +1 is what its name implies it returns
>>
>> Or maybe even less confusing:
>>
>>     Note that, unlike the name implies, it returns the highest index
>> in the array, so to get the size
>>     of the array you need to use C<av_len (av) + 1>.
>>
>>
> 
> I wrote the original text.  I realize that I do not have the talent to
> explain things easily, so I often look at what I've written and think of
> a better way to say it, or appreciate other people cleaning it up.  But
> this time, I don't see anything wrong with the original.  sv_len of a
> length 1 string will return 1.  av_len of a length 1 array will return
> 0.  I think it is worth pointing out that their behaviors do not
> correspond.

"Note that the return value is +1 what its name implies it returns."

Its name implies that it returns 5 for a length 5 array. The
documentation says its return value R is that plus one; i.e. R = 5 + 1,
thus R = 6. That's the bug.

> In your first proposal, the word 'is' is missing, so it is not correct
> grammatically.

No, it's not.

"Note that the return value +1 is what its name implies it returns."
-------------------------------^^ (I hope you have a fixed-width font)

Its name implies it returns 5 for a length 5 array. The sentence says
that the actual return value R, plus one, equals that; i.e. R + 1 == 5.
By algebra we get R = 4, so the sentence is correct but weirdly worded.

> I like your second proposal, but again, I think it useful to contrast
> this behavior with sv_len.

Sure, but that seems orthogonal to the problem at hand. How about this
addition?

Note that, unlike the name implies, it returns the highest index in the
array, so to get the size of the array you need to use C<av_len(av) +
1>. This is unlike C<sv_len>, which returns what you would expect.


-- 
Lukas Mai <plokinom@gmail.com>

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About