NAME

PDL::Util

SYNOPSIS

use PDL;
use PDL::Util 'export2d';

my $pdl = rvals(6,4);

open my $fh, '>', 'file.dat';
export2d($pdl, $fh);

DESCRIPTION

Convenient utility functions/methods for use with PDL.

IMPORT

use PDL:Util 'export2d', ['unroll'] 
# imports 'export2d', adds 'unroll' as a PDL method

PDL::Util does not export anything by default. A list of symbols may be imported as usual. The exportable symbols come in two types, functions (tag :function) and methods (tag :methods). The word methods here is a strange word. When importing symbols one does not import methods. In this context a 'method' is a function which expects a piddle as its first argument. However, there is a reason ...

If an array reference or hash reference is passed as the last item in the import list, the reference will be passed to the add_pdl_method function below, in which case these functions are imported into the PDL namespace and may be used as method calls. Note, when doing this for symbols from the PDL::Util module, only those listed in the :methods tag may be added as a method (this is the origin of the confusing terminology). Read about the add_pdl_method function carefully before using this functionality.

TAG :functions

add_pdl_method

add_pdl_method({'my_method' => sub { my $self = shift; ... });
$pdl->my_method         # calls the anonymous sub on $pdl

add_pdl_method(['export2d']);
$pdl->export2d()        # calls 'export2d' on $pdl

add_pdl_method({'my_unroll' => 'unroll'});
$pdl->my_unroll()       # calls 'unroll' method on $pdl

add_pdl_method pushes subroutines into the PDL namespace. It takes a single argument, a reference either an array or hash. The keys of the hash reference are the method name that will be used in the call (e.g. $pdl->method_name, the values are either a reference to a subroutine or a string containing the name of a method provided by PDL::Util. The array reference form can only take names of PDL::Util methods.

When adding your own subroutine as a PDL method, be aware that the first argument passed will be a self (i.e. $self) reference, in the normal Perl OO manner.

TAG :methods

Again, the functions provided in the method tag are not automatically methods. They simply are function which are called with a PDL object (piddle) as their first argument. This function ARE available to be imported into the PDL namespace using the add_pdl_method function describe above.

unroll

$AoA = unroll($pdl);
  -- or --
$AoA = $pdl->unroll();

PDL provides a function for constructing a PDL object (piddle) from a Perl nested array, however it does not provide a tool to convert a piddle to a nested array structure. The closest function is the list function, which returns the elements of the piddle as a list, i.e. a 1D flattened array. unroll converts piddles to a native Perl data structure; it can be thought of as the logical inverse of the pdl function in that pdl(unroll($pdl)) should return the original data structure, although bad values and data types may be changed.

When called as a function unroll takes a single argument (the piddle to unroll). When used as a method it takes no arguments. It returns a reference to an array containing the Perl equivalent data structure.

export2d

export2d($pdl, $fh, ',');
  -- or --
$pdl->export2d($fh, ',');

export2d may take up to 2 optional arguments (neglecting the object reference), a lexical filehandle (or globref, e.g. \*FILE) to write to, and a string containing a column separator. The defaults, if arguments are not given are to print to STDOUT and use a single space as the column separator. The order does not matter, the method will determine whether an argument refers to a file or not. This is done so that one may call either

$pdl->export2d($fh);
$pdl->export2d(',');

and it will do what you mean. Unfortunately this means that unlike wcols one cannot use a filename rather than a filehandle; export2d would interpret the string as the column separator!

The method returns the number of columns that were written.

SEE ALSO

PDL Website

SOURCE REPOSITORY

http://github.com/jberger/PDL-Util

AUTHOR

Joel Berger, <joel.a.berger@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Joel Berger

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.