Perl Context Guide — Scalar vs List Context and wantarray

In this tutorial, you will learn about Perl Context Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

Perl context is the fundamental concept where how a function is called (scalar, list, or void) determines what it returns -- with wantarray enabling functions to behave differently based on the calling context for maximum flexibility.

Scalar vs List Context

# Array in scalar context = length
my @array = (1, 2, 3, 4, 5);
my $count = @array;        # 5 (scalar context)
my @copy  = @array;        # (1,2,3,4,5) (list context)

# localtime
my $time_str = localtime();   # "Sun Jun 28 12:00:00 2026"
my @time_arr = localtime();   # (0, 0, 12, 28, 5, 126, 0, 179, 0)

Creating Context-Sensitive Functions

sub get_data {
    my @data = (10, 20, 30, 40, 50);
    
    if (wantarray) {
        # List context - return all
        return @data;
    } else {
        # Scalar context - return count
        return scalar @data;
    }
}

my @all = get_data();    # (10, 20, 30, 40, 50)
my $num = get_data();    # 5

Forcing Context

# Force scalar context
my @items = qw(a b c);
my $count = scalar @items;    # 3

# Force list context
my @info = localtime();       # list context
my $info = localtime();       # scalar context

# Boolean context
if (@items) {                 # true if non-empty
    print "Has items\n";
}

Common Context Examples

# grep and map are context-sensitive
my @array = (1, 2, 3, 4, 5);

my @big = grep { $_ > 2 } @array;  # (3, 4, 5) - list
my $count = grep { $_ > 2 } @array; # 3 - scalar

# Reading from filehandle
my $line = <$fh>;   # one line (scalar)
my @lines = <$fh>;  # all lines (list)

Void Context

# Void context - result is discarded
some_function();     # return value not used

# Warning in void context with use warnings
1 + 2;              # "useless use of addition in void context"

Common Mistakes

1. Assuming array in scalar context returns last element

Scalar context for arrays returns the length, not the last element. $value = @array gives count, not last item.

2. Not considering context in custom functions

Functions that return different things in scalar vs list context can surprise users. Document the behavior.

3. Forcing scalar on a list operation

my $count = @array is correct. my $count = scalar(@array) is explicit but equivalent.

Practice Questions

1. What does an array return in scalar context? Its length (number of elements). Use $count = @array.

2. What does wantarray do? Returns true if the calling code expects a list, false for scalar, undef for void context.

3. How do you force scalar context explicitly? Use the scalar keyword: my $count = scalar(@array).

FAQ

{{< faq question="What is void context?" >}} When a function's return value is not used at all. Perl may warn about useless operations in void context. {{< /faq >}}

{{< faq question="Does print impose list context?" >}} Yes, print's arguments are evaluated in list context. print func() calls func in list context. {{< /faq >}}

{{< faq question="How do I check context in a function?" >}} Use if (wantarray) { ... } to behave differently. Returns undef for void context, which is also false. {{< /faq >}}

What's Next

Now learn about string functions in Perl.