Re: Re: Re: Re: Re: What should be returned in scalar context? (best practice)by sauoq (Abbot)
|on Dec 22, 2003 at 02:23 UTC||Need Help??|
documenting that a subroutine returns an array is very ambiguous especially considering the fact that you can have a subroutine detect context and return the contents of the array for list context and an arrayref in scalar context (this is the behavior I actually expect when the documentation says array
Well, if the function returns an array reference in scalar context, the documentation should state that it "returns an array reference in scalar context." Simple as that. An "array" is not an "array reference" and to expect it to become one in scalar context is ridiculous.
Just take these two functions:
To document that the first returns a list and the second returns an array is perfectly acceptable (preferable, imho.) When you see f1() in the code, you know how it is going to act. Number of elements: my $nelts = f1(); ... First element: my ($first) = f1(); ... similarly, when you see f2() in the code, you can know how it will act. Last element: my $last = f2(); ... First element: my ($first) = f2(); (This is exactly why this discussion came up in the first place. Read the first node in this thread to orient yourself.)
Juerd's mumblings (or ravings) about Perl builtins are quite irrelevant. Besides the fact that every single one of them is a special case, they aren't implemented in Perl to begin with; they are implemented in C.
The phrase "returns an array" is a very nice way of explaining exactly what you mean without addressing every context separately. I won't avoid it.
Update: Examples flipped. Thanks jarich for pointing that out. (I actually flipped my description, because I wanted to talk about list values first, and forgot to flip my examples.
-sauoq "My two cents aren't worth a dime.";