NAME

       PDL::Objects -- Object-orientation, what it is and how to exploit it

DESCRIPTION

       This describes how to subclass PDL objects for fun and profit.

   Why subclass?
       There are basically two reasons for subclassing ndarrays.  The first is simply that you want to be able
       to use your own routines like

         $ndarray->something

       but don't want to mess up the PDL namespace (a worthy goal, indeed!).  The other is that you wish to
       provide special handling of some functions or more information about the data the ndarray contains.  The
       first case you can do with

         package BAR;
         our @ISA=qw/PDL/;
         sub foo {my($this) = @_; fiddle;}

         package main;
         $x = BAR->pdl(5);
         $x->foo;

       However, because a PDL object is an opaque reference to a C struct, it is not instantly possible to
       extend the PDL class by e.g. extra data via subclassing.

   Perl values into underlying C values
       "typemap"s turns Perl values into the C entities needed by the C code. PDL's one uses "SvPDLV" to extract
       a "pdl*" from a Perl value. That knows how to deal with:

       •   "simple" blessed scalars that have a C pointer

       •   blessed hash-refs that have a "PDL" member that's a C pointer as above

       •   blessed  hash-refs  that  have  a  "PDL"  member  that's  a Perl code-ref.  It will be called, and is
           expected to return an ndarray that conforms to one of cases 1-2  or  4-5  above.  As  of  2.094,  the
           original  hash-ref  will  be  passed as the first argument. This means you can give a method as shown
           below, rather than needing to make a closure each time.  Example from t/subclass.t:

             package PDL::Derived2;
             # This is a array of ones of dim 'Coeff'
             # All that is stored initially is "Coeff", the
             # PDL array is only realised when a boring PDL
             # function is called on it. One can imagine methods
             # in PDL::Derived2 doing manipulation on the Coeffs
             # rather than actualizing the data.
             our @ISA = qw/PDL/;
             sub new {
               my $class = shift;
               bless {
                 Coeff=>shift,
                 PDL=>\&cache,
                 SomethingElse=>42,
               }, $class;
             }
             # Actualize the value (demonstrating cacheing)
             # One can imagine expiring the cache if say, Coeffs change
             sub cache {
               my $self = shift;
               return $self->{Cache} if exists $self->{Cache};
               $self->{Cache} = PDL->ones(@$self{qw(Coeff Coeff)})+2;
             }

       •   "simple" Perl data, either a scalar or an array-reference

       •   blessed hash-refs that are a Math::Complex (or subclass) object - special case of the "scalar" above

       The rest of this document deals with the second case above.

   Inheritance
       To enable subclassing, make a package and bless a hash-ref into it with a "PDL" member. Make that package
       inherit from "PDL", and redefine the method "initialize".

         package FOO;
         our ISA = qw(PDL::Hash);
         sub initialize {
           my $class = shift;
           my $self = $class->SUPER::initialize(@_);
           $self->{creation_time} = time(); # necessary extension :-)
           $self;
         }

       All PDL constructors will call initialize() to make sure that  your  extensions  are  added  by  all  PDL
       constructors automatically.

       Do  remember  that  if  you  subclass  a  class  that  is  subclassed  from  an ndarray, you need to call
       "SUPER::initialize". Make sure it is callable as an instance method, e.g. by copying data from $class  if
       ref $class is true.

   Examples
       You  can  find  some  simple examples of PDL subclassing in the PDL distribution test-case files. Look in
       t/subclass.t.

   Output Auto-Creation and Subclassed Objects
       For PDL Functions where the output is created  and  returned,  PDL  will  call  the  subclassed  object's
       "initialize"  method  on  either  instance or class to create the output object. (See PDL::Indexing for a
       discussion on Output Auto-Creation.) This behavior is summarized as follows:

       PDL will call "initialize" on the first input argument if it is an object, else on "PDL"  to  create  the
       output  object.   In  the spirit of the Perl philosophy of making Easy Things Easy, this behavior enables
       PDL-subclassed objects to be written without having to overload the many simple  PDL  functions  in  this
       category.

AUTHOR

       Copyright  (C)  Karl  Glazebrook  (kgb@aaoepp.aao.gov.au),  Tuomas J. Lukka, (lukka@husc.harvard.edu) and
       Christian Soeller (c.soeller@auckland.ac.nz) 2000.  All rights reserved. There is no  warranty.  You  are
       allowed to copy this on the same terms as Perl itself.

perl v5.40.0                                       2025-02-04                                  PDL::Objects(3pm)