NAME

Types::PDL - PDL types using Type::Tiny

VERSION

version 0.04

SYNOPSIS

use Types::PDL -types;
use Type::Params qw[ validate ];
use PDL;

validate( [ pdl ], Piddle );

DESCRIPTION

This module provides Type::Tiny compatible types for PDL.

Types

Types which accept parameters (see "Parameters") will list them.

Piddle

Allows an object blessed into the class PDL, e.g.

validate( [pdl], Piddle );

It accepts the following parameters:

null
empty
ndims
ndims_min
ndims_max
shape
type

Piddle0D

Allows an object blessed into the class PDL with ndims = 0. It accepts the following parameters:

null
type

Piddle1D

Allows an object blessed into the class PDL with ndims = 1. It accepts the following parameters:

null
empty
shape
type

Piddle2D

Allows an object blessed into the class PDL with ndims = 2. It accepts the following parameters:

null
empty
shape
type

Piddle3D

Allows an object blessed into the class PDL with ndims = 3. It accepts the following parameters:

null
empty
shape
type

Coercions

The following coercions are provided, and may be applied via a type object's "plus_coercions" in Type::Tiny or "plus_fallback_coercions" in Type::Tiny methods, e.g.

Piddle->plus_coercions( PiddleFromAny );

PiddleFromAny

Uses "topdl" in PDL::Core to coerce the value into a piddle.

Parameters

Some types take optional parameters which add additional constraints on the object. For example, to indicate that only empty piddles are accepted:

validate( [pdl], Piddle[ empty => 1 ] );

The available parameters are:

empty

This accepts a boolean value; if true the piddle must be empty (i.e. the isempty method returns true), if false, it must not be empty.

null

This accepts a boolean value; if true the piddle must be a null piddle, if false, it must not be null.

ndims

This specifies a fixed number of dimensions which the piddle must have. Don't mix use this with ndims_min or ndims_max.

ndims_min

The minimum number of dimensions the piddle may have. Don't specify this with ndims.

ndims_max

The maximum number of dimensions the piddle may have. Don't specify this with ndims.

shape

The shape of the piddle.

The value is a list of specifications for dimensions, expressed either as elements in a Perl array or as comma-delimited fields in a string.

The specifications are reminiscent of regular expressions. A specification is composed of an extent size followed by an optional quantifier indicating the number of dimensions it should match.

Extent sizes may be

1. A non-zero positive integer representing the extent of the dimension.
2. The strings X or : indicating that any extent is accepted for that dimension

Quantifiers may be

*           Match 0 or more times
+           Match 1 or more times
?           Match 1 or 0 times
{n}         Match exactly n times
{n,}        Match at least n times
{n,m}       Match at least n but not more than m times

Here are some example specifications and the shapes they might match (in the match, X means any extent):

2,2     => (2,2)
3,3,3   => (3,3,3)
3{3}    => (3,3,3)
3{2,3}  => (3,3),  (3,3,3)
1,X     => (1,X)
1,X+    => (1,X), (1,X,X),  (1,X,X,X), ...
1,X{1,} => (1,X), (1,X,X),  (1,X,X,X), ...
1,X?,3   => (1,X,3), (1,3)
1,2,X*   => (1,2), (1,2,X),  (1,2,X,X), ...
1,2,3*,5   => (1,2,5), (1,2,3,5),  (1,2,3,3,5), ...

type

The type of the piddle. The value may be a PDL::Type object or a string containing the name of a type (e.g., double). For a complete list of types, run this command:

perl -MPDL::Types=mapfld,ppdefs \
  -E 'say mapfld( $_ => 'ppsym' => 'ioname' )  for ppdefs'

BUGS AND LIMITATIONS

You can make new bug reports, and view existing ones, through the web interface at https://rt.cpan.org/Public/Dist/Display.html?Name=Types-PDL.

AUTHOR

Diab Jerius djerius@cpan.org

COPYRIGHT AND LICENSE

This software is Copyright (c) 2017 by Smithsonian Astrophysical Observatory.

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007