# -*- cperl -*- # =head1 NAME Array base class =head1 ABSTRACT 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. =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 =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 =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