push#

Append one or more values to the end of an array.

push adds every element of LIST to the end of ARRAY, in order. It is the paired counterpart of pop at the tail and of unshift / shift at the head. The array grows in place; no new array is returned.

Synopsis#

push @arr, $val
push @arr, @more
push @arr, list, of, values
push @$aref, $val

What you get back#

The new number of elements in ARRAY after the append — i.e. scalar @arr as it stands once push returns. Not the pushed values, not the old length, not the array itself.

my @colors = ("red");
my $n = push @colors, "blue", "green";   # $n is 3

Useful when the push and the subsequent length check would otherwise be two statements:

if (push @queue, $job > $limit) { ... }  # one call, count + test

Examples#

Basic append of a single value:

my @animals = ("cat");
push @animals, "mouse";                   # ("cat", "mouse")

Append several values in one call — each argument becomes its own element:

my @colors = ("red");
push @colors, "blue", "green";            # ("red", "blue", "green")

Append the contents of another array. The second array is flattened into the list, so its elements are appended, not the array as a single item:

my @a = (1, 2);
my @b = (3, 4);
push @a, @b;                              # (1, 2, 3, 4)

Queue discipline — push at the tail, shift at the head:

my @queue;
push @queue, $job;                        # enqueue
my $next = shift @queue;                  # dequeue

Stack discipline — push and pop at the same end:

my @stack;
push @stack, $frame;                      # enter
my $top = pop @stack;                     # leave

Push onto an array held by reference. The reference must be dereferenced with @{ ... } (or the short @$ref form) before push sees an array:

my $aref = [1, 2];
push @$aref, 3;                           # $aref now refers to [1, 2, 3]
push @{ $aref }, 4, 5;                    # same, explicit deref

Count elements after appending without a temporary:

my $size = push @log, $entry;
warn "log is large: $size entries" if $size > 1000;

Edge cases#

Arrayref needs a deref. push $ref, $x is a compile-time error in Perl 5.24+. Use push @$ref, $x or push @{ $ref }, $x. An experimental feature allowed a scalar first argument in 5.14–5.22 and was removed; do not rely on it.
Array arguments auto-flatten. push @a, @b appends @b’s elements individually. To append @b as a single nested entry you need an arrayref: push @a, \@b or push @a, [ @b ].
Hash arguments also flatten. push @a, %h appends alternating keys and values in hash iteration order — almost never what you want. Use push @a, \%h to store the hash by reference instead.
List context but scalar return. push is documented as taking a LIST and therefore evaluates its arguments in list context, but the value push itself produces is always the resulting count. Inside print push @a, @b the count is what gets printed, not the array.
Empty LIST. push @a; (no second argument) is a no-op and returns the current scalar @a. Legal and occasionally useful for “give me the count without modifying anything” — though scalar @a is clearer.
Tied arrays. push on a tied array calls PUSH on the tied object if defined; otherwise it falls back to repeated STORE calls at FETCHSIZE-derived indices. See perltie.
Autovivification. Pushing through an undef-valued reference vivifies an anonymous array:
```
my %index;
push @{ $index{$key} }, $value;         # $index{$key} becomes an arrayref
```
After the first push, $index{$key} holds an arrayref containing $value. This is the standard idiom for building a hash-of-arrays incrementally.
Readonly array. Pushing onto a readonly or fixed-size array (e.g. an element of @_ bound to a caller’s variable, or an array locked with Hash::Util::lock_value) raises Modification of a read-only value attempted.

Differences from upstream#

Fully compatible with upstream Perl 5.42.