You are viewing the version of this documentation from Perl 5.40.0-RC1. This is a development version of Perl.
unshift ARRAY,LIST

Add one or more elements to the beginning of an array. This is the opposite of a shift.

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

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

Returns the new number of elements in the updated array.

# Return value is the number of items in the updated array
my $color_count = unshift(@colors, ("yellow", "purple"));

say "There are $color_count colors in the updated array";

Note the LIST is prepended whole, not one element at a time, so the prepended elements stay in the same order. Use reverse to do the reverse.

Starting with Perl 5.14, an experimental feature allowed unshift to take a scalar expression. This experiment has been deemed unsuccessful, and was removed as of Perl 5.24.