# -*- cperl -*-

=head1 Array base class

This pod file documents the Array base class usage. For implementation
details you should look inside the class file, found on
C<classes/array.pmc> in the parrot source code.

=head2 Synopsis

  new P0, .Array    # initialize P0 as an array

  set I0, P0        # get to I0 size of the array P0
  set P0, 2         # set array P0 size to 2

  set P0[0], "foo"  # put "foo" on array position 0
  set I1, P0[1]     # get value from array position 1

  defined I2, P0[1] # value on position 1 is defined?
  exists  I3, P0[0] # there is an element on position 0?

=head2 Creation

As any other PMC, the following line creates an array PMC on register C<P0>.

  new P0, .Array

As soon the array is created, you can test if it is defined using:

  defined I0, P0

which will put C<1> on C<I0> if it is defined, otherwise, C<0>.

=head2 Array sizes

When used on numeric context the PMC register containing the array
object contains the size of the array. You can use

  set I0, P0

to retrieve to C<I0> the size of the array on register C<P0>. In the
same way, you can assign directly the size of the array using

  set P0, 2

which will expand the array size to two.

=head2 Accessing elements

Elements are accessed using indexes, as in any programming
language. Notice that these arrays do not expand as Perl arrays, when
you access non-existing indexes.

The following code initializes an array on C<P0> with size two, and
sets the first position with an integer C<-8> and second position with
a real, C<3.1415>.

  new P0, .Array
  set P0, 2

  set P0[0], -8
  set P0[1], 3.1415

It must be clear that you can assign directly from a register. Check
this second example, with the same meaning:

  new P0, .Array
  set P0, 2

  set I0, -8
  set N0, 3.1415

  set P0[0], I0
  set P0[1], N0

To retrieve the elements we use the same syntax, switching registers:

  set N1, P0[1]
  set I1, P0[0]

These two lines retrieve the values from the array back to registers.
Whenever you want, it is possible to change the value type on some
position:

  set P0[1], "A string"

Accessing an out-of-bounds array element, an exception will be raised
(as soon as we have exceptions).

You can test if there is a defined element on some array position using

  defined I0, P0[1]

for the position you want to test. On the other hand, if you want only
to test if there is an element (rather than testing if it is defines)
you should use the C<exists> keyword:

  exists I0, P0[0]

=head2 TODO

Explain a little more which exception will be raised in case you
access a out-of-bounds index on the array (as soon we have
exceptions).

=cut