# Copyright (C) 2001-2012, Parrot Foundation.

=pod

=head1 NAME

docs/pmc/array.pod - Array base class.

=head1 SYNOPSIS

=begin PIR_FRAGMENT

  new $P0, 'Array'    # initialize P0 as an array

  set $I0, $P0        # set I0 to the size of the array in P0
  set $P0, 2          # set the size of the array in P0 to 2

  set $P0[0], "foo "  # put "foo" into the array at position 0
  set $I1, $P0[1]     # get an integer value from the entry 
                      # at array position 1

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

=end PIR_FRAGMENT

=head1 DESCRIPTION

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

=head2 Creation

As with any other PMC, the following line creates an array PMC in register 
C<P0>:

=begin PIR_FRAGMENT

  new $P0, 'Array'

=end PIR_FRAGMENT

=head2 Array sizes

You can retrieve the size of the array using

=begin PIR_FRAGMENT

  set $I0, $P0

=end PIR_FRAGMENT

This will put the size of the array in register C<P0> into C<I0>. In the same
way, assigning an integer directly to the array sets the size of the  array.
For instance:

=begin PIR_FRAGMENT

  new $P0, 'Array'
  set $P0, 2

=end PIR_FRAGMENT

creates a new Array (with default size 0) and then expands the size of the 
array to two.

Arrays do not automatically resize themselves when you access out-of-bounds
elements. This means that you must remember to size an Array appropriately
before storing anything in it.

=head2 Accessing elements

Elements are accessed using indexes, as in any programming language.

The following code initializes an array in C<P0> with size two, and sets the
first position to the integer C<-8> and second position to the floating point
number C<3.1415>.

=begin PIR_FRAGMENT

  new $P0, 'Array'
  set $P0, 2

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

=end PIR_FRAGMENT

You can also assign directly from registers; for instance:

=begin PIR_FRAGMENT

  new $P0, 'Array'
  set $P0, 2

  set $I0, -8
  set $N0, 3.1415

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

=end PIR_FRAGMENT

leaves P0 in the same state as in the previous code snippet.

To retrieve elements, we use the same syntax:

=begin PIR_FRAGMENT

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

=end PIR_FRAGMENT

Those two lines retrieve the values from the array back into registers.

The value stored at a given position is not fixed; it can be changed simply by
assigning a new value:

=begin PIR_FRAGMENT

  set $P0[1], "A string"

=end PIR_FRAGMENT

Accessing an out-of-bounds array element raises an exception; if you want an
Array that will automatically resize, then use a C<ResizablePMCArray>.

You can test if there is a defined element at an array position by using

=begin PIR_FRAGMENT

  defined $I0, $P0[1]

=end PIR_FRAGMENT

for the position you want to test. On the other hand, if you only want to test
whether a given element exists (rather than whether it is defined),  then use
the C<exists> op instead:

=begin PIR_FRAGMENT

  exists $I0, $P0[0]

=end PIR_FRAGMENT

=head1 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