.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "HDF5::Dataset 3pm"
.TH HDF5::Dataset 3pm 2024-01-10 "perl v5.38.2" "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::IO::HDF5::Dataset \- PDL::IO::HDF5 Helper Object representing HDF5 datasets.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This is a helper-object used by PDL::IO::HDF5 to interface with HDF5 format's dataset objects.
Information on the HDF5 Format can be found
at the HDF Group's web site at http://www.hdfgroup.org .
.SH SYNOPSIS
.IX Header "SYNOPSIS"
See PDL::IO::HDF5
.SH "MEMBER DATA"
.IX Header "MEMBER DATA"
.IP ID 1
.IX Item "ID"
ID number given to the dataset by the HDF5 library
.IP name 1
.IX Item "name"
Name of the dataset.
.IP parent 1
.IX Item "parent"
Ref to parent object (group) that owns this dateset.
.IP fileObj 1
.IX Item "fileObj"
Ref to the PDL::IO::HDF5 object that owns this object.
.SH METHODS
.IX Header "METHODS"
####\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.SS new
.IX Subsection "new"
PDL::IO::HDF5::Dataset Constructor \- creates new object
.PP
\&\fBUsage:\fR
.PP
This object will usually be created using the calling format detailed in the SYNOPSIS. The 
following syntax is used by the PDL::IO::HDF5 object to build the object.
.PP
.Vb 6
\&   $a = new PDL::IO::HDF5:Dataset( name => $name, parent => $parent, 
\&                                fileObj => $fileObj);
\&        Args:
\&        $name                           Name of the dataset
\&        $parent                         Parent Object that owns this dataset
\&        $fileObj                        PDL::HDF object that owns this dateset.
.Ve
.SS DESTROY
.IX Subsection "DESTROY"
PDL::IO::HDF5::Dataset Destructor \- Closes the dataset object
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   No Usage. Automatically called
.Ve
.SS set
.IX Subsection "set"
Write data to the HDF5 dataset
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\& $dataset\->set($pdl, unlimited => 1);     # Write the array data in the dataset
\&
\&     Options:
\&     unlimited     If present, the dataset is created with unlimited dimensions.
.Ve
.SS get
.IX Subsection "get"
Get data from a HDF5 dataset to a PDL
.PP
\&\fBUsage:\fR
.PP
.Vb 2
\& $pdl = $dataset\->get;     # Read the Array from the HDF5 dataset, create a PDL from it
\&                           #  and put in $pdl
\&
\&                           # Assuming $dataset is three dimensional
\&                           # with dimensions (20,100,90)
.Ve
.PP
The \fIget\fR method can also be used to obtain particular slices or hyperslabs
of the dataset array. For example, if \f(CW$dataset\fR is three dimensional with dimensions
(20,100,90) then we could do:
.PP
.Vb 3
\& $start=pdl([0,0,0]);      # We begin the slice at the very beginning
\& $end=pdl([19,0,0]);       # We take the first vector of the array,
\& $stride=pdl([2,1,1]);     # taking only every two values of the vector 
\&
\& $pdl = $dataset\->get($start,$end,[$stride]); # Read a slice or
\&                           # hyperslab from the HDF5 dataset.
\&                           # $start, $end and optionally $stride
\&                           # should be PDL vectors with length the
\&                           # number of dimensions of the dataset.
\&                           # $start gives the starting coordinates
\&                           # in the array.
\&                           # $end gives the ending coordinate
\&                           # in the array
\&                           # $stride gives the steps taken from one
\&                           # coordinate to the next of the slice
.Ve
.PP
The mapping of HDF5 datatypes in the file to PDL datatypes in memory will be according
to the following table.
.PP
.Vb 10
\& HDF5 File Type                         PDL Type
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-               \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& PDL::IO::HDF5::H5T_C_S1()      =>      PDL::Char Object    (Special Case for Char Strings)
\& PDL::IO::HDF5::H5T_STD_I8BE()  =>      $PDL::Types::PDL_B
\& PDL::IO::HDF5::H5T_STD_I8LE()  =>      $PDL::Types::PDL_B,
\& PDL::IO::HDF5::H5T_STD_U8BE()  =>      $PDL::Types::PDL_S,
\& PDL::IO::HDF5::H5T_STD_U8LE()  =>      $PDL::Types::PDL_S,
\& PDL::IO::HDF5::H5T_STD_I16BE() =>      $PDL::Types::PDL_S,
\& PDL::IO::HDF5::H5T_STD_I16LE() =>      $PDL::Types::PDL_S,
\& PDL::IO::HDF5::H5T_STD_U16BE() =>      $PDL::Types::PDL_L,
\& PDL::IO::HDF5::H5T_STD_U16LE() =>      $PDL::Types::PDL_L,
\& PDL::IO::HDF5::H5T_STD_I32BE() =>      $PDL::Types::PDL_L,
\& PDL::IO::HDF5::H5T_STD_I32LE() =>      $PDL::Types::PDL_L,
\& PDL::IO::HDF5::H5T_STD_U32LE() =>      $PDL::Types::PDL_LL,
\& PDL::IO::HDF5::H5T_STD_U32BE() =>      $PDL::Types::PDL_LL,
\& PDL::IO::HDF5::H5T_STD_I64LE() =>      $PDL::Types::PDL_LL,
\& PDL::IO::HDF5::H5T_STD_I64BE() =>      $PDL::Types::PDL_LL,
\& PDL::IO::HDF5::H5T_IEEE_F32BE()=>      $PDL::Types::PDL_F,
\& PDL::IO::HDF5::H5T_IEEE_F32LE()=>      $PDL::Types::PDL_F,
\& PDL::IO::HDF5::H5T_IEEE_F64BE()=>      $PDL::Types::PDL_D,
\& PDL::IO::HDF5::H5T_IEEE_F64LE()=>      $PDL::Types::PDL_D
.Ve
.PP
For HDF5 File types not in this table, this method will attempt to
map it to the default PDL type PDL_D.
.PP
If the dataset being read is a scalar reference, the referenced dataset region will be read instead.
.PP
\&\fBNote:\fR
.PP
Character arrays are returned as the special PDL::Char fixed-length string type. For fixed-length
HDF5 string arrays, this is a direct mapping to the PDL::Char datatype. For HDF5 variable-length string
arrays, the data is converted to a fixed-length character array, with a string size equal to the maximum
size of all the strings in the array.
.SS dims
.IX Subsection "dims"
Get the dims for a HDF5 dataset. For example, a 3 x 4 array would return a perl array
(3,4);
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\& @pdl = $dataset\->dims;    # Get an array of dims.
.Ve
.SS attrSet
.IX Subsection "attrSet"
Set the value of an attribute(s)
.PP
Attribute types supported are null-terminated strings and PDL matrices
.PP
\&\fBUsage:\fR
.PP
.Vb 7
\&   $dataset\->attrSet( \*(Aqattr1\*(Aq => \*(Aqattr1Value\*(Aq,
\&                    \*(Aqattr2\*(Aq => \*(Aqattr2 value\*(Aq, 
\&                    \*(Aqattr3\*(Aq => $pdl,
\&                    .
\&                    .
\&                    .
\&                   );
.Ve
.PP
Returns undef on failure, 1 on success.
.SS attrDel
.IX Subsection "attrDel"
Delete attribute(s)
.PP
\&\fBUsage:\fR
.PP
.Vb 6
\& $dataset\->attrDel( \*(Aqattr1\*(Aq, 
\&                    \*(Aqattr2\*(Aq,
\&                    .
\&                    .
\&                    .
\&                   );
.Ve
.PP
Returns undef on failure, 1 on success.
.SS attrs
.IX Subsection "attrs"
Get a list of all attribute names associated with a dataset
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   @attrs = $dataset\->attrs;
.Ve
.SS attrGet
.IX Subsection "attrGet"
Get the value of an attribute(s)
.PP
Currently the attribute types supported are null-terminated strings
and PDLs.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   my @attrs = $dataset\->attrGet( \*(Aqattr1\*(Aq, \*(Aqattr2\*(Aq);
.Ve
.SS IDget
.IX Subsection "IDget"
Returns the HDF5 library ID for this object
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\& my $ID = $dataSetObj\->IDget;
.Ve
.SS nameGet
.IX Subsection "nameGet"
Returns the HDF5 Dataset Name for this object.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\& my $name = $datasetObj\->nameGet;
.Ve