=begin pod

=TITLE class Array

=SUBTITLE Sequence of itemized values

    class Array is List { ... }

An C<Array> is a L<List> which forces all its elements to be
scalar containers, which means you can assign to array elements.

=head1 Methods

=head2 routine pop

Defined as:

    multi sub    pop(Array:D )
    multi method pop(Array:D:)

Usage:

    pop ARRAY
    ARRAY.pop

Removes and returns the last item from the array. Fails for an empty array.

Example:

    > my @foo = <a b>;
    a b
    > @foo.pop;
    b
    > pop @foo
    a
    > pop @foo
    Element popped from empty list

=head2 routine push

Defined as:

    multi sub    push(Array:D, **@values) returns Array:D
    multi method push(Array:D: **@values) returns Array:D

Usage:

    push ARRAY, VALUES
    ARRAY.push(VALUES)
    ARRAY.push: VALUES

Adds the C<@values> to the end of the array, and returns the modified list.
Fails for infinite arrays.

Example:

    my @foo = <a b c>;
    @foo.push: 'd';
    say @foo;                   # a b c d

Note that C<push> does not attempt to flatten its argument list. If you pass
an array or list as the thing to push, it becomes one additional element:

    my @a = <a b c>;
    my @b = <d e f>;
    @a.push: @b;
    say @a.elems;               # 4
    say @a[3].join;             # def

Only if you supply multiple values as separate arguments to C<push> are
multiple values added to the array:

   my @a = '1';
   my @b = <a b>;
   my @c = <E F>;
   @a.push: @b, @c;
   say @a.elems;                # 3

See L<method append|#method append> for when you want to append multiple
values that are stored in a single array.

=head2 method append

Defined as

    sub append(\array, elems)
    multi method append(Array:D: \values)
    multi method append(Array:D: **@values is raw)

Usage:

    ARRAY.append(LIST)
    append ARRAY, LIST

Appends the argument list to the array passed as first argument. This modifies
the array in-place. Returns the modified array.

The difference to method C<push> is that with an array or list argument,
C<append> appends several elements (one for each array or list element),
whereas C<push> appends just one element.

Example:

    my @a = <a b c>;
    my @b = <d e f>;
    @a.append: @b;
    say @a.elems;               # 6
    say @a;                     # a b c d e f

=head2 routine shift

Defined as:

    multi sub    shift(Array:D )
    multi method shift(Array:D:)

Usage:

    shift ARRAY
    ARRAY.shift

Removes and returns the first item from the array. Fails for an empty arrays.

Example:

    my @foo = <a b>;
    say @foo.shift;     # a
    say @foo.shift;     # b
    say @foo.shift;     # Element shifted from empty list

=head2 routine unshift

Defined as:

    multi sub    unshift(Array:D, **@values) returns Array:D
    multi method unshift(Array:D: **@values) returns Array:D

Usage:

    unshift ARRAY, VALUES
    ARRAY.unshift(VALUES)
    ARRAY.unshift: VALUES

Adds the C<@values> to the start of the array, and returns the modified array.
Fails if C<@values> is infinite.

Example:

    my @foo = <a b c>;
    @foo.unshift: 1, 3 ... 11;
    say @foo;                   # (1 3 5 7 9 11) a b c

The notes in L<the documentation for method push|#method push> apply,
regarding how many elements are added to the array.

L<#method prepend> is the equivalent for adding multiple elements from one
list or array.

=head2 method prepend

Defined as

    sub prepend(\array, elems)
    multi method prepend(Array:D: \values)
    multi method prepend(Array:D: **@values is raw)

Usage:

    ARRAY.prepend(LIST)
    prepend ARRAY, LIST

Adds the elements from C<LIST> to the front of the array, modifying it
in-place.

Example:

    my @foo = <a b c>;
    @foo.prepend: 1, 3 ... 11;
    say @foo;                   # 1 3 5 7 9 11 a b c

=head2 routine splice

Defined as:

    multi sub    splice(@list,  $start, $elems?, *@replacement) returns Array
    multi method splice(Array:D $start, $elems?, *@replacement) returns Array

Usage:

    splice(ARRAY, START, ELEMS?, REPLACEMENT?)
    ARRAY.splice(START, ELEMS?, REPLACEMENT?)

Deletes C<$elems> elements starting from index C<$start> from the C<Array>,
returns them and replaces them by C<@replacement>. If C<$elems> is omitted,
all the elements starting from index C<$start> are deleted.

Example:

    my @foo = <a b c d e f g>;
    say @foo.splice(2, 3, <M N O P>);       # c d e
    say @foo;                               # a b M N O P f g
    
=head2 method shape

Defined as:

    method shape() { (*,) }

Usage:

    ARRAY.shape

Returns the shape of the array as a list.

Example:

    my @foo[2;3] = ( < 1 2 3 >, < 4 5 6 > ); # Array with fixed dimensions
    say @foo.shape; # (2 3)
    my @bar = ( < 1 2 3 >, < 4 5 6 > ); # Normal array (of arrays)
    say @bar.shape; # (*)

=end pod
