<html><head><title>Array::APX</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
<link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://search.cpan.org/s/style.css">
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.19,
using Pod::Simple::PullParser v3.19,
under Perl v5.008009 at Sun Mar 11 15:55:30 2012 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<div class='indexgroup'>
<ul class='indexList indexList1'>
<li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
<li class='indexItem indexItem1'><a href='#VERSION'>VERSION</a>
<li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
<li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
<li class='indexItem indexItem1'><a href='#Overloaded_unary_operators'>Overloaded unary operators</a>
<li class='indexItem indexItem1'><a href='#Overloaded_binary_operators'>Overloaded binary operators</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#%2B%2C_-%2C_*%2C_%2F%2C_%25%2C_**%2C_%7C%2C_%26%2C_%5E%2C_%3D%3D%2C_!%3D'>+, -, *, /, %, **, |, &, ^, ==, !=</a>
<li class='indexItem indexItem2'><a href='#Generalized_outer_products'>Generalized outer products</a>
<li class='indexItem indexItem2'><a href='#The_reduce_operator_%2F'>The reduce operator /</a>
<li class='indexItem indexItem2'><a href='#The_scan_operator_x'>The scan operator x</a>
</ul>
<li class='indexItem indexItem1'><a href='#Exported_functions'>Exported functions</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#dress'>dress</a>
<li class='indexItem indexItem2'><a href='#iota'>iota</a>
</ul>
<li class='indexItem indexItem1'><a href='#APX-methods'>APX-methods</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#collapse'>collapse</a>
<li class='indexItem indexItem2'><a href='#grade'>grade</a>
<li class='indexItem indexItem2'><a href='#in'>in</a>
<li class='indexItem indexItem2'><a href='#index'>index</a>
<li class='indexItem indexItem2'><a href='#remove'>remove</a>
<li class='indexItem indexItem2'><a href='#reverse'>reverse</a>
<li class='indexItem indexItem2'><a href='#rho'>rho</a>
<li class='indexItem indexItem2'><a href='#rotate'>rotate</a>
<li class='indexItem indexItem2'><a href='#scatter'>scatter</a>
<li class='indexItem indexItem2'><a href='#select'>select</a>
<li class='indexItem indexItem2'><a href='#slice'>slice</a>
<li class='indexItem indexItem2'><a href='#strip'>strip</a>
<li class='indexItem indexItem2'><a href='#subscript'>subscript</a>
<li class='indexItem indexItem2'><a href='#transpose'>transpose</a>
</ul>
<li class='indexItem indexItem1'><a href='#SEE_ALSO'>SEE ALSO</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#Links'>Links</a>
</ul>
<li class='indexItem indexItem1'><a href='#AUTHOR'>AUTHOR</a>
<li class='indexItem indexItem1'><a href='#COPYRIGHT'>COPYRIGHT</a>
</ul>
</div>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>Array::APX - Array Programming eXtensions</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="VERSION"
>VERSION</a></h1>
<p>This document refers to version 0.1 of Array::APX</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre> use strict;
use warnings;
use Array::APX qw(:all);
# Create two vectors [0 1 2] and [3 4 5]:
my $x = iota(3);
my $y = iota(3) + 3;
print "The first vector is $x";
print "The second vector is $y\n";
# Add these vectors and print the result:
print 'The sum of these two vectors is ', $x + $y, "\n";
# Create a function to multiply two values:
my $f = sub { $_[0] * $_[1] };
# Create an outer product and print it:
print "The outer product of these two vectors is\n", $x |$f| $y;</pre>
<p>yields</p>
<pre> The first vector is [ 0 1 2 ]
The second vector is [ 3 4 5 ]
The sum of these two vectors is [ 3 5 7 ]
The outer product of these two vectors is
[
[ 0 0 0 ]
[ 3 4 5 ]
[ 6 8 10 ]
]</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>This module extends Perl-5 with some basic functionality commonly found in array programming languages like APL, Lang5 etc. It is basically a wrapper of Array::Deeputils and overloads quite some basic Perl operators in a way that allows easy manipulation of nested data structures. These data structures are basically blessed n-dimensional arrays that can be handled in a way similar to APL or Lang5.</p>
<p>A nice example is the computation of a list of prime numbers using an archetypical APL solution. The basic idea is this: Create an outer product of two vectors [2 3 4 ... ]. The resulting matrix does not contain any primes since every number is the product of at least two integers. Then check for every number in the original vector [2 3 4 ... ] if it is a member of this matrix. If not, it must be a prime number. The set theoretic method 'in' returns a selection vector consisting of 0 and 1 values which can be used in a second step to select only the prime values from the original vector. Using Array::APX this can be written in Perl like this:</p>
<pre> use strict;
use warnings;
use Array::APX qw(:all);
my $f = sub { $_[0] * $_[1] }; # We need an outer product
my $x;
print $x->select(!($x = iota(199) + 2)->in($x |$f| $x));</pre>
<p>How does this work? First a vector [2 3 4 ... 100] is created:</p>
<pre> $x = iota(99) + 2</pre>
<p>This vector is then used to create an outer product (basically a multiplication table without the 1-column/row:</p>
<pre> my $f = sub { $_[0] * $_[1] }; # We need an outer product
... $x |$f| $x ...</pre>
<p>The |-operator is used here as the generalized outer-'product'-operator (if applied to two APX data structures it would act as the bitwise binary or) - it expects a function reference like $f in the example above. Thus it is possible to create any outer 'products' - not necessarily based on multiplication only. Using the vector stored in $x and this two dimensional matrix, the in-method is used to derive a boolean vector that contains a 1 at every place corresponding to an element on the left hand operand that is contained in the right hand operand. This boolean vector is then inverted using the overloaded !-operator:</p>
<pre> !($x = iota(99) + 2)->in($x |$f| $x)</pre>
<p>Using the select-method this boolean vector is used to select the elements corresponding to places marked with 1 from the original vector $x thus yielding a vector of prime numbers between 2 and 100:</p>
<pre> print $x->select(!($x = iota(199) + 2)->in($x |$f| $x));</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="Overloaded_unary_operators"
>Overloaded unary operators</a></h1>
<p>Overloaded unary operators are automatically applied to all elements of a (nested) APX data structure. The following operators are currently available: !</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="Overloaded_binary_operators"
>Overloaded binary operators</a></h1>
<p>In general all overloaded binary operators are automatically applied in an element wise fashion to all (corresponding) elements of APX data structures.</p>
<p>The following operators are currently available and do what one would expect:</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="+,_-,_*,_/,_%,_**,_|,_&,_^,_==,_!="
>+, -, *, /, %, **, |, &, ^, ==, !=</a></h2>
<p>These operators implement addition, subtraction, multiplication, division, modulus, power, bitwise or / and /xor, numerical equal/not equal</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Generalized_outer_products"
>Generalized outer products</a></h2>
<p>A basic function in every array programming language is an operator to create generalized outer products of two vectors. This generalized outer product operator consists of a function pointer that is enclosed in two '|' (cf. the prime number example at the beginning of this documentation). Given two APX vectors a traditional outer product can be created like this:</p>
<pre> use strict;
use warnings;
use Array::APX qw(:all);
my $f = sub { $_[0] * $_[1] };
my $x = iota(10) + 1;
print $x |$f| $x;</pre>
<p>This short program yields the following output:</p>
<pre> [
[ 1 2 3 4 5 6 7 8 9 10 ]
[ 2 4 6 8 10 12 14 16 18 20 ]
[ 3 6 9 12 15 18 21 24 27 30 ]
[ 4 8 12 16 20 24 28 32 36 40 ]
[ 5 10 15 20 25 30 35 40 45 50 ]
[ 6 12 18 24 30 36 42 48 54 60 ]
[ 7 14 21 28 35 42 49 56 63 70 ]
[ 8 16 24 32 40 48 56 64 72 80 ]
[ 9 18 27 36 45 54 63 72 81 90 ]
[ 10 20 30 40 50 60 70 80 90 100 ]
]</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="The_reduce_operator_/"
>The reduce operator /</a></h2>
<p>The operator / acts as the reduce operator if applied to a reference to a subroutine as its left argument and an APX structure as its right element:</p>
<pre> use strict;
use warnings;
use Array::APX qw(:all);
my $x = iota(100) + 1;
my $f = sub { $_[0] + $_[1] };
print $f/ $x, "\n";</pre>
<p>calculates the sum of all integers between 1 and 100 (without using Gauss' summation formula just by repeated addition). The combined operator</p>
<pre> $f/</pre>
<p>applies the function referenced by $f between each two successive elements of the APX structure on the right hand side of the operator.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="The_scan_operator_x"
>The scan operator x</a></h2>
<p>The scan-operator works like the \-operator in APL - it applies a binary function to all successive elements of an array but accumulates the results gathered along the way. The following example creates a vector of the partial sums of 0, 0 and 1, 0 and 1 and 2, 0 and 1 and 2 and 3 etc.:</p>
<pre> $f = sub { $_[0] + $_[1] };
$x = $f x iota(10);
print $x;</pre>
<p>This code snippet yields the following result:</p>
<pre> [ 0 1 3 6 10 15 21 28 36 45 ]</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="Exported_functions"
>Exported functions</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="dress"
>dress</a></h2>
<p>This function expects an array reference and converts it into an APX objects. This is useful if nested data structures that have been created outside of the APX framework are to be processed using the APX array processing capabilities.</p>
<pre> use strict;
use warnings;
use Array::APX qw(:all);
my $array = [[1, 2], [3, 4]];
my $x = dress($array);
print "Structure:\n$x";</pre>
<p>yields the following output:</p>
<pre> Structure:
[
[ 1 2 ]
[ 3 4 ]
]</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="iota"
>iota</a></h2>
<p>This function expects a positive integer value as its argument and returns an APX vector with unit stride, starting with 0 and containing as many elements as specified by the argument:</p>
<pre> use strict;
use warnings;
use Array::APX qw(:all);
my $x = iota(10);
print "Structure:\n$x";</pre>
<p>yields</p>
<pre> Structure:
[ 0 1 2 3 4 5 6 7 8 9 ]</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="APX-methods"
>APX-methods</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="collapse"
>collapse</a></h2>
<p>To convert an n-dimensional APX-structure into a one dimensional structure, the collapse-method is used:</p>
<pre> use strict;
use warnings;
use Array::APX qw(:all);
print dress([[1, 2], [3, 4]])->collapse();</pre>
<p>yields</p>
<pre> [ 1 2 3 4 ]</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="grade"
>grade</a></h2>
<p>The grade-method returns an index vector that can be used to sort the elements of the object, grade was applied to. For example</p>
<pre> print dress([3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5])->grade();</pre>
<p>yields</p>
<pre> [ 3 1 6 9 0 2 8 4 10 7 5 ]</pre>
<p>So to sort the elements of the original object, the subscript-method could be applied with this vector as its argument.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="in"
>in</a></h2>
<p>This implements the set theoretic 'in'-function. It checks which elements of its left operand data structure are elements of the right hand data structure and returns a boolean vector that contains a 1 at corresponding locations of the left side operand that are elements of the right side operand.</p>
<pre> use strict;
use warnings;
use Array::APX qw(:all);
my $x = iota(10);
my $y = dress([5, 11, 3, 17, 2]);
print "Boolean vector:\n", $y->in($x);</pre>
<p>yields</p>
<pre> Boolean vector:
[ 1 0 1 0 1 ]</pre>
<p>Please note that the in-method operates on a one dimensional APX-object while its argument can be of any dimension >= 1.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="index"
>index</a></h2>
<p>The index-method returns an index vector containing the indices of the elements of the object it was applied to with respect to its argument which must be an APX-object, too. Thus</p>
<pre> print dress([[1, 3], [4, 5]])->index(dress([[1, 2, 3], [4, 5, 6], [7, 8, 9]]));</pre>
<p>yields</p>
<pre> [
[
[ 0 0 ]
[ 0 2 ]
]
[
[ 1 0 ]
[ 1 1 ]
]
]</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="remove"
>remove</a></h2>
<p>The remove-method removes elements from an APX-object controlled by an index vector supplied as its argument (which must be an APX-object, too):</p>
<pre> print iota(10)->remove(dress([1, 3, 5]));</pre>
<p>yields</p>
<pre> [ 0 2 4 6 7 8 9 ]</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="reverse"
>reverse</a></h2>
<p>The reverse-method reverses the sequence of elements in an APX-object, thus</p>
<pre> print iota(5)->reverse();</pre>
<p>yields</p>
<pre> [ 4 3 2 1 0 ]</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="rho"
>rho</a></h2>
<p>The reshape-method has fulfills a twofold function: If called without any argument it returns an APX-object describing the structure of the object it was applied to. If called with an APX-object as its parameter, the rho-method restructures the object it was applied to according to the dimension values specified in the parameter (please note that rho will reread values from the object it was applied to if there are not enough to fill the destination structure). The following code example shows both usages of rho:</p>
<pre> use strict;
use warnings;
use Array::APX qw(:all);
my $x = iota(9);
my $y = dress([3, 3]);
print "Data rearranged as 3-times-3-matrix:\n", my $z = $x->rho($y);
print 'Dimensionvector of this result: ', $z->rho();</pre>
<p>This test program yields the following output:</p>
<pre> Data rearranged as 3-times-3-matrix:
[
[ 0 1 2 ]
[ 3 4 5 ]
[ 6 7 8 ]
]
Dimensionvector of this result: [ 3 3 ]</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="rotate"
>rotate</a></h2>
<p>rotate rotates an APX-structure along several axes. The following example shows the rotation of a two dimensional data structure along its x- and y-axes by +1 and -1 positions respecitively:</p>
<pre> print dress([[1, 2, 3], [4, 5, 6], [7, 8, 9]])->rotate(dress([1, -1]));</pre>
<p>The result of this rotation is thus</p>
<pre> [
[ 8 9 7 ]
[ 2 3 1 ]
[ 5 6 4 ]
]</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="scatter"
>scatter</a></h2>
<p>The scatter-method is the inverse of subscript. While subscript selects values from an APX-object, controlled by an index vector, scatter creates a new data structure with elements read from the APX-object it was applied to and their positions controlled by an index vector. The following example shows the use of scatter:</p>
<pre> print (iota(7) + 1)->scatter(dress([[0, ,0], [0, 1], [1, 0], [1, 1]]));</pre>
<p>yields</p>
<pre> [
[ 1 2 ]
[ 3 4 ]
]</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="select"
>select</a></h2>
<p>The select-method is applied to a boolean vector and selects those elements from its argument vector that correspond to places containing a true value in the boolean vector. Thus</p>
<pre> use strict;
use warnings;
use Array::APX qw(:all);
my $x = iota(10) + 1;
my $s = dress([0, 1, 1, 0, 1, 0, 1]);
print $x->select($s);</pre>
<p>yields</p>
<pre> [ 2 3 5 7 ]</pre>
<p>Please note that select works along the first dimension of the APX-object it is applied to and expects a one dimensional APX-objects as its argument.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="slice"
>slice</a></h2>
<p>slice extracts part of a nested data structure controlled by a coordinate vector as the following example shows:</p>
<pre> print (iota(9) + 1)->rho(dress([3, 3]))->slice(dress([[1, 0], [2, 1]]));</pre>
<p>yields</p>
<pre> [
[ 4 5 ]
[ 7 8 ]
]</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="strip"
>strip</a></h2>
<p>strip is the inverse function to dress() - it is applied to an APX data structure and returns a plain vanilla Perl array:</p>
<pre> use strict;
use warnings;
use Array::APX qw(:all);
use Data::Dumper;
my $x = iota(3);
print Dumper($x->strip);</pre>
<p>yields</p>
<pre> $VAR1 = [
0,
1,
2
];</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="subscript"
>subscript</a></h2>
<p>The subscript-method retrieves values from a nested APX-data structure controlled by an index vector (an APX-object, too) as the following simple example shows:</p>
<pre> print (iota(9) + 1)->rho(dress([3, 3]))->subscript(dress([1]));</pre>
<p>returns the element with the index 1 from a two dimensional data structure that contains the values 1 to 9 yielding:</p>
<pre> [
[ 4 5 6 ]
]</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="transpose"
>transpose</a></h2>
<p>transpose is used to transpose a nested APX-structure along any of its axes. In the easiest two dimensional case this corresponds to the traditional matrix transposition, thus</p>
<pre> print (iota(9) + 1)->rho(dress([3, 3]))->transpose(1);</pre>
<p>yields</p>
<pre> [
[ 1 4 7 ]
[ 2 5 8 ]
[ 3 6 9 ]
]</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SEE_ALSO"
>SEE ALSO</a></h1>
<p>Array::APX relies mainly on Array::Deeputils which, in turn, was developed for the interpreter of the array programming language Lang5. The source of Array::Deeputils is maintained in the source repository of Lang. In addition to that Array::APX borrows some basic functions of the Lang5 interpreter itself, too.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="Links"
>Links</a></h2>
<ul>
<li><a href="http://lang5.sf.net/" class="podlinkurl"
>The lang5 Home Page</a>.</li>
</ul>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Bernd Ulmann <ulmann@vaxman.de></p>
<p>Thomas Kratz <tomk@cpan.org></p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT"
>COPYRIGHT</a></h1>
<p>Copyright (C) 2012 by Bernd Ulmann, Thomas Kratz</p>
<p>This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.</p>
<!-- end doc -->
</body></html>