.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "OBJECTS 1p"
.TH OBJECTS 1p "2023-06-17" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDL::Objects \-\- Object\-Orientation, what is it and how to exploit it
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This still needs to be written properly.  [Also, is there a good reason
we don't recommend storing extra object data in the header hash?]
.SS "Inheritance"
.IX Subsection "Inheritance"
There are basically two reasons for subclassing ndarrays.
The first is simply that you want to be able to use your own routines
like
.PP
.Vb 1
\&        $ndarray\->something()
.Ve
.PP
but don't want to mess up the \s-1PDL\s0 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.
In the first case, you can do with
.PP
.Vb 3
\&        package BAR;
\&        @ISA=qw/PDL/;
\&        sub foo {my($this) = @_; fiddle;}
\&
\&        package main;
\&        $x = PDL::pdl(BAR,5);
\&        $x\->foo();
.Ve
.PP
However, because a \s-1PDL\s0 object is an opaque reference to a C struct,
it is not possible to
extend the \s-1PDL\s0 class by e.g. extra data via subclassing.
To circumvent this problem
PerlDL has built-in support to extent the \s-1PDL\s0 class via the \fIhas-a\fR
relation for blessed hashes.  You can get the \fIHAS-A\fR behave like
\&\fIIS-A\fR simply in that you assign the \f(CW\*(C`PDL\*(C'\fR object to the attribute
named \s-1PDL\s0 and redefine the method \fBinitialize()\fR.
.PP
.Vb 1
\&    package FOO;
\&
\&    @FOO::ISA = qw(PDL);
\&    sub initialize {
\&        my $class = shift;
\&        my $self = {
\&                creation_time => time(),  # necessary extension :\-)
\&                PDL => null,             # used to store PDL object
\&                };
\&        bless $self, $class;
\&    }
.Ve
.PP
All \s-1PDL\s0 constructors will call \fBinitialize()\fR to make sure that your
extensions are added by \fIall\fR \s-1PDL\s0 constructors automatically.   The
\&\f(CW\*(C`PDL\*(C'\fR attribute is used by perlDL to store the \s-1PDL\s0 object and
all \s-1PDL\s0 methods use this attribute automatically if they are called
with a blessed hash reference instead of a \s-1PDL\s0 object (a blessed scalar).
.PP
Do remember that if you subclass a class that is subclassed from an ndarray,
you need to call SUPER::initialize.
.PP
\&\s-1NEED STUFF ABOUT CODE\s0 REFs!!
.SS "Examples"
.IX Subsection "Examples"
You can find some simple examples of \s-1PDL\s0 subclassing in the \s-1PDL\s0 distribution
test-case files. Look in \f(CW\*(C`t/subclass2.t\*(C'\fR, \f(CW\*(C`t/subclass3.t\*(C'\fR, etc.
.SS "Output Auto-Creation and Subclassed Objects"
.IX Subsection "Output Auto-Creation and Subclassed Objects"
For \s-1PDL\s0 Functions where the output is created and returned, \s-1PDL\s0 will either
call the subclassed object's \f(CW\*(C`initialize\*(C'\fR or \f(CW\*(C`copy\*(C'\fR method to create the
output object. (See PDL::Indexing 
for a discussion on Output Auto-Creation.) This behavior is summarized as follows:
.IP "\(bu" 1
For \fISimple\fR functions, defined as having a signature of
.Sp
.Vb 1
\& func( a(), [o]b() )
.Ve
.Sp
\&\s-1PDL\s0 will call \f(CW$a\fR\->copy to create the output object.
.Sp
In the spirit of the Perl philosophy of making \fIEasy Things Easy\fR,
This behavior enables PDL-subclassed objects to be written without having to
overload the many simple \s-1PDL\s0 functions in this category.
.Sp
The file t/subclass4.t in the \s-1PDL\s0 Distribution tests for this behavior.
See that file for an example.
.IP "\(bu" 1
For other functions, \s-1PDL\s0 will call \f(CW$class\fR\->initialize to create the output object.
Where \f(CW$class\fR is the class name of the first argument supplied to the function.
.Sp
For these more complex cases, it is difficult to second-guess the subclassed object's 
designer to know if a \f(CW\*(C`copy\*(C'\fR or a \f(CW\*(C`initialize\*(C'\fR is appropriate. So for these cases,
\&\f(CW$class\fR\->initialize is called by default. If this is not appropriate for you,
overload the function in your subclass and do whatever is appropriate is the overloaded
function's code.
.SH "AUTHOR"
.IX Header "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.