You are viewing the version of this documentation from Perl 5.38.0. View the latest version
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.