view release on metacpan or  search on metacpan

share/Synopsis/S09-data.pod  view on Meta::CPAN

    my @array is PDL(:shape(2;2;2;2)) of int8;

PDLs are allowed to assume a type of C<num> by default rather than
the usual simple scalar.  (And in general, the type info is merely
made available to the "tie" implementation to do with what it will.
Some data structures may ignore the "of" type and just store everything
as general scalars.  Too bad...)

Arrays by default are one dimensional, but may be declared to have any
dimensionality supported by the implementation.  You may use arrays
just like scalars -- the main caveat is that you have to use
binding rather than assignment to set one without copying:

    @b := @a[0,2,4 ... *]

With PDLs in particular, this might alias each of the individual
elements rather than the array as a whole.  So modifications to @b
are likely to be reflected back into @a.  (But maybe the PDLers will
prefer a different notation for that.)

The dimensionality of an array may be declared on the variable, but
the actual dimensionality of the array depends on how it was created.
Reconciling these views is a job for the particular array implementation.
It's not necessarily the case that the declared dimensionality must match
the actual dimensionality.  It's quite possible that the array variable
is deliberately declared with a different dimensionality to provide a
different "view" on the actual value:

    my int @array[2;2] is Puddle .= new(:shape(4) <== 0,1,2,3);

Again, reconciling those ideas is up to the implementation, C<Puddle>
in this case.  The traits system is flexible enough to pass any
metadata required, including ideas about sparseness, raggedness,
and various forms of non-rectangleness such as triangleness.
The implementation should probably carp about any metadata it doesn't
recognize though.  The implementation is certainly free to reject
any object that doesn't conform to the variable's shape requirements.

=head1 Subscript and slice notation

A subscript indicates a "slice" of an array.  Each dimension of an
array is sliced separately, so a multidimensional slice subscript
may be supplied as a semicolon-separated list of slice sublists.
A three-dimensional slice might look like this:

    @x[0..10; 1,0; 1,*+2...*]

It is up to the implementation of C<@x> to decide how aggressively
or lazily this subscript is evaluated, and whether the slice entails
copying.  (The PDL folks will generally want it to merely produce a
virtual PDL where the new array aliases its values back into the
old one.)

Of course, a single element can be selected merely by providing a single
index value to each slice list:

    @x[0;1;42]

=head1 Cascaded subscripting of multidimensional arrays

For all multidimensional array types, it is expected that cascaded subscripts:

    @x[0][1][42]
    @x[0..10][1,0][1,*+2...*]

will either fail or produce the same results as the equivalent
semicolon subscripts:

    @x[0;1;42]
    @x[0..10; 1,0; 1,*+2...*]

Built-in array types are expected to succeed either way, even if
the cascaded subscript form must be implemented inefficiently by
constructing temporary slice objects for later subscripts to use.
(User-defined types may choose not to support the cascaded form, but
if so, they should fail rather than providing different semantics.)
As a consequence, for built-in types of declared shape, the appropriate
number of cascaded subscripts may always be optimized into the
semicolon form.

=head1 The semicolon operator

At the statement level, a semicolon terminates the current expression.
Within any kind of bracketing construct, semicolon notionally separates
the sublists of a multidimensional slice, the interpretation of
which depends on the context.  Such a semicolon list puts each of its
sublists into a C<Parcel>, deferring the context of the sublist until
it is bound somewhere.  The storage of these sublists is hidden in
the inner workings of the list.  It does not produce a list of lists
unless the list as a whole is bound into a slice context.

Single dimensional arrays expect simple slice subscripts, meaning
they will treat a list subscript as a slice in the single dimension of
the array.  Multi-dimensional arrays, on the other hand, know how to
handle a multidimensional slice, with one subslice for each dimension.  You need not specify
all the dimensions; if you don't, the unspecified dimensions are
"wildcarded".  Supposing you have:

    my num @nums[3;3;3];

Then

    @nums[0..2]

is the same as

    @nums[0..2;]

which is the same as

    @nums[0,1,2;*;*]

But you should maybe write the last form anyway just for good
documentation, unless you don't actually know how many more dimensions
there are.  For that case use C<**>:

    @nums[0,1,2;**]

If you wanted that C<0..2> range to mean

    @nums[0;1;2]

it is not good enough to use the C<|> prefix operator, because
that interpolates at the comma level, so:

    @nums[ |(0,1,2) ] 

just means

    @nums[ 0,1,2 ];

Instead, to interpolate at the semicolon level, you need to use the C<||> prefix operator:

    @nums[ ||(0..2) ]

The zero-dimensional slice:

    @x[]