NAME

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

SYNOPSIS

  new $P0, 'ResizablePMCArray' # initialize P0 as an resizable array for PMC items

  $P0 = 2             # set the size of the array in P0 to 2
  $I0 = $P0           # get the size of the array in P0 into I0

  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?

DESCRIPTION

This pod file documents the virtual base Array base class usage. For implementation details you should look inside the class files, found at src/pmc/{Fixed,Resizable}{PMC,Integer,Float,String,Boolean}Array.pmc in the parrot source code.

Creation

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

  $S0 = 'ResizablePMCArray' # or any other array type
  new $P0, $S0

The virtual 'Array' class itself cannot be instantiated.

Array sizes

You can retrieve the size of the array using

  set $I0, $P0
  # or
  $I0 = $P0

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

  new $P0, 'FixedPMCArray'
  set $P0, 2

  # or faster

  new $P0, 'FixedPMCArray', 2

creates a new fixed size array for PMCs (with default size 0) and then expands the size of the array to two, or with the second integer argument initializes the size immediately.

Fixed arrays do not automatically resize themselves when you access out-of-bounds elements. This means that you must remember to size a fixed array appropriately before storing anything in it, or use a resiable array instead.

Accessing elements

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

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

  new $P0, 'FixedPMCArray', 2

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

You can also assign indirectly via registers; for instance:

  new $P0, 'FixedPMCArray', 2

  set $I0, -8
  set $N0, 3.1415

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

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

To retrieve elements, we use the same syntax:

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

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:

  set $P0[1], "A string"

Accessing an out-of-bounds array element raises an exception; if you want an array that will automatically resize use a resizable array.

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

  defined $I0, $P0[1]

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 exists op instead:

  exists $I0, $P0[0]

With exists you are safe to check even out of bounds indices.

Resizable vs Fixed

There exist two array types, Resizable and Fixed size for all base types: PMC, Integer, String, Float and Boolean. With resizable arrays you can explicitly or implicitly grow an array by setting a value at an index >= size, but not with fixed arrays.

All methods throw an out of bounds exception on invalid index or size arguments, just not on exists.

Using negative indices is supported to count the index from the back. E.g index -1 accesses the last element of an array.

Common non-vtable array methods are sort and reverse, which are destructive. They do not return a copy.

Resizable arrays additionally support the shift, unshift, push, pull methods.

Copyright © 2002-2014, Parrot Foundation.