Section 9.7. Scalar Return Values

9.7. Scalar Return Values

Always return scalar in scalar returns.

One of the more subtle features of Perl subroutines is the way that their call context propagates to their return statements. In most places in Perl, the context (list, scalar, or void) can be deduced at compile time. One place where it can't be determined in advance is to the right of a return. The argument of a return is evaluated in whatever context the subroutine itself was called.

That's a very handy feature, which makes it easy to factor out or rename specific uses of built-in functions. For example, if you found yourself repeatedly filtering undefined and negative values out of lists:

      @valid_samples = grep {defined($_) && $_ >= 0} @raw_samples;

it would be better to encapsulate that complex filter and rename it more meaningfully:

      sub valid_samples_in {         return grep {defined($_) && $_ >= 0} @_;     }     
# and then...
     @valid_samples = valid_samples_in(@raw_samples);

Because the return expression is always evaluated in the same context as the surrounding call, it's also still okay to use this subroutine in scalar context:

      if (valid_samples_in(@raw_samples) < $MIN_SAMPLE_COUNT) {         report_sensor_malfunction(  );     }

When the subroutine is called in scalar context, its return statement imposes scalar context on the grep, which then returns the total number of valid samplesjust as a raw grep would do in the same position.

Unfortunately, it's easy to forget about the contextual lycanthropy of a return, especially when you write a subroutine that is "only ever going to be used one way"^[*]. For example:

^[*] Yep, that's the sound of alarm bells you're hearing.

     sub how_many_defined {         return grep {defined $_} @_;     }     # and "always" thereafter:     my $found = how_many_defined(@raw_samples);

But eventually someone will write:

     my ($found) = how_many_defined(@raw_samples);

and introduce a very subtle bug. The parentheses around $found put it in a list context, which puts the call to how_many_defined( ) in a list context, which puts the grep inside how_many_defined( ) in a list context, which causes the return to return the list of defined samples, the first of which is then assigned to $found^[].

] And if that sample happens to be an integer, then $found will be assigned a numeric value, exactly as expected. It will be the If there were even the slightest chance that this scalar-returning subroutine might ever be called in a list context, it should have been written as follows:

      sub how_many_defined {         return scalar grep {defined $_} @_;     }

There is no shame in using an explicit scalar anywhere you know you want a scalar but you're not confident of your context. And because you can never be confident of your context in a return statement, an explicit scalar is always acceptable there.

At very least, you should always add one anywhere that a previously mistaken expectation regarding context has already bitten you. That way, the same misconception won't bite whoever is eventually responsible for the care and feeding of your code (that is, most likely you again, six months later).