.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 "HDF5 3pm"
.TH HDF5 3pm "2021-08-10" "perl v5.32.1" "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 \- PDL Interface to the HDF5 Data Format.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package provides an object-oriented interface for \s-1PDL\s0s to
the \s-1HDF5\s0 data-format. Information on the \s-1HDF5\s0 Format can be found
at the \s-1HDF\s0 Group's web site at http://www.hdfgroup.org .
.SS "\s-1LIMITATIONS\s0"
.IX Subsection "LIMITATIONS"
Currently this interface only provides a subset of the total \s-1HDF5\s0 library's
capability.
.IP "\(bu" 1
Only \s-1HDF5\s0 Simple datatypes are supported. No \s-1HDF5\s0 Compound datatypes are supported since \s-1PDL\s0 doesn't
support them.
.IP "\(bu" 1
Only \s-1HDF5\s0 Simple dataspaces are supported.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use PDL::IO::HDF5;
\&
\&  # Files #######
\&  my $newfile = new PDL::IO::HDF5("newfile.hdf");        # create new hdf5 or open existing file.
\&  my $attrValue = $existingFile\->attrGet(\*(AqAttrName\*(Aq);    # Get attribute value for file
\&  $existingFile\->attSet(\*(AqAttrName\*(Aq => \*(AqAttrValue\*(Aq);      # Set attribute value(s) for file
\&
\&  # Groups ######
\&  my $group = $newfile\->group("/mygroup");               # create a new or open existing group
\&  my @groups = $existingFile\->groups;                    # get a list of all the groups at the root \*(Aq/\*(Aq
\&                                                         # level.
\&  my @groups = $group\->groups;                           # get a list of all the groups at the "mygroup"
\&                                                         # level.
\&  my $group2 = $group\->group(\*(Aqnewgroup\*(Aq);                # Create/open a new group in existing group "mygroup"
\&
\&  $group\->unlink(\*(AqdatasetName\*(Aq);                         # Delete a dataset from a group
\&
\&  $group\->reference($dataset,\*(AqrefName\*(Aq,\e@start,\e@count); # Create a scalar reference to a subregion of a
\&                                                         # dataset, with specified start index and count.
\&
\&  my $attrValue = $group\->attrGet(\*(AqAttrName\*(Aq);           # Get attribute value for a group
\&  $group\->attrSet(\*(AqAttrName\*(Aq => \*(AqAttrValue\*(Aq);            # Set attribute value(s) for a group
\&  $group\->attrDel(\*(AqAttrName1\*(Aq, \*(AqAttrName2\*(Aq);             # Delete attribute(s) for a group
\&  @attrs = $group\->attrs;                                # Get List of attributes for a group
\&
\&  # Data Sets ########
\&  my $dataset = $group\->dataset( \*(AqdatasetName\*(Aq);         # create a new or open existing dataset
\&                                                         #  in an existing group
\&  my $dataset = $newfile\->dataset( \*(AqdatasetName\*(Aq);       # create a new or open existing dataset
\&                                                         #  in the root group of a file
\&
\&  my $dataset2 = $newfile\->dataset( \*(AqdatasetName\*(Aq);      # create a new or open existing dataset
\&                                                         # in the root group.
\&  my @datasets =  $existingFile\->datasets;               # get a list of all datasets in the root \*(Aq/\*(Aq group
\&  my @datasets =  $group\->datasets;                      # get a list of all datasets in a group
\&  @dims = $dataset\->dims;                                # get a list of dimensions for the dataset
\&  $pdl = $dataset\->get();                                # Get the array data in the dataset
\&  $pdl = $dataset\->get($start,$length,$stride);          # Get a slice or hyperslab of the array data in the dataset
\&  $dataset\->set($pdl, unlimited => 1);                   # Set the array data in the dataset
\&  my $attrValue = $dataset\->attrGet(\*(AqAttrName\*(Aq);         # Get attribute value for a dataset
\&  $dataset\->attSet(\*(AqAttrName\*(Aq => \*(AqAttrValue\*(Aq);           # Set attribute value(s) for a dataset
.Ve
.SH "MEMBER DATA"
.IX Header "MEMBER DATA"
.IP "\s-1ID\s0" 1
.IX Item "ID"
\&\s-1ID\s0 number given to the file by the \s-1HDF5\s0 library
.IP "filename" 1
.IX Item "filename"
Name of the file.
.IP "accessMode" 1
.IX Item "accessMode"
Access Mode?? ( read /write etc????)
.IP "attrIndex" 1
.IX Item "attrIndex"
Quick lookup index of group names to attribute values. Autogenerated as-needed by the 
allAttrValues, allAttrNames, getGroupByAttr methods. Any attribute writes or group
creations will delete this data member, because it will no longer be valid.
.Sp
The index is of this form:
.Sp
.Vb 7
\&  {
\&    groupName1  =>  { attr1 => value, attr2 => value }.
\&    groupName2  =>  { attr1 => value, attr3 => value }.
\&   .
\&   .
\&   .
\&  }
.Ve
.Sp
For the purposes of indexing groups by their attributes, the attributes are 
applied hierarchically. i.e. any attributes of the higher level groups are assumed to be 
apply for the lower level groups.
.IP "groupIndex" 1
.IX Item "groupIndex"
Quick lookup index of attribute names/values group names. This index is used by the 
getGroupByAttr method to quickly find any group(s) that have attribute that match a 
desired set.
.Sp
The index is of this form:
.Sp
.Vb 6
\&  { "attr1\e0attt2" => { "value1\e0value2\*(Aq => [ group1, group2, ...],
\&                        "value3\e0value3\*(Aq => [ groupA ],
\&                        .
\&                        .
\&                        .
\&                      },
\&                      
\&     "att1"        => { "value1\*(Aq =>         [ group1, group2, ...],
\&                        "value3\*(Aq =>         [ groupA ]
\&                        .
\&                        .
\&                        .
\&                      },
\&       .
\&       .
\&       .
\&  }
.Ve
.Sp
The first level of the index maps the attribute name combinations that have
indexes built to their index. The second level maps the corresponding attribute values
with the group(s) where these attributes take on these values.
.Sp
.Vb 6
\&    groupName1  =>  { attr1 => value, attr2 => value }.
\&    groupName2  =>  { attr1 => value, attr3 => value }.
\&   .
\&   .
\&   .
\&  }
.Ve
.Sp
For the purposes of indexing groups by their attributes, the attributes are 
applied hierarchically. i.e. any attributes of the higher level groups are assumed to be 
apply for the lower level groups.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
\&\s-1PDL::IO::HDF5\s0 constructor \- creates \s-1PDL::IO::HDF5\s0 object for reading or 
writing data.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   $a = new PDL::IO::HDF5( $filename );
.Ve
.PP
Arguments:  
1) The name of the file.
.PP
If this file exists and you want to write to it, 
prepend the name with the '>' character:  \*(L">name.nc\*(R"
.PP
Returns undef on failure.
.PP
\&\fBExample:\fR
.PP
.Vb 1
\&        $hdf5obj = new PDL::IO::HDF5( "file.hdf" );
.Ve
.SS "filename"
.IX Subsection "filename"
Get the filename for the \s-1HDF5\s0 file
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   my $filename = $HDFfile\->filename;
.Ve
.SS "group"
.IX Subsection "group"
Open or create a group in the root \*(L"/\*(R" group (i.e. top level)
of the \s-1HDF5\s0 file.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   $HDFfile\->group("groupName");
.Ve
.PP
Returns undef on failure, 1 on success.
.SS "groups"
.IX Subsection "groups"
Get a list of groups in the root \*(L"/\*(R" group (i.e. top level)
of the \s-1HDF5\s0 file.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   @groups = $HDFfile\->groups;
.Ve
.SS "unlink"
.IX Subsection "unlink"
Unlink an object from the root \*(L"/\*(R" group (i.e. top level)
of the \s-1HDF5\s0 file.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   $HDFfile\->unlink($name);
.Ve
.SS "dataset"
.IX Subsection "dataset"
Open or create a dataset in the root \*(L"/\*(R" group (i.e. top level)
of the \s-1HDF5\s0 file.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   $HDFfile\->dataset("groupName");
.Ve
.PP
Returns undef on failure, 1 on success.
.PP
Note: This is a convenience method that is equivalent to:
.PP
.Vb 1
\&  $HDFfile\->group("/")\->dataset("groupName");
.Ve
.SS "datasets"
.IX Subsection "datasets"
Get a list of all dataset names in the root \*(L"/\*(R" group.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   @datasets = $HDF5file\->datasets;
.Ve
.PP
Note: This is a convenience method that is equivalent to:
.PP
.Vb 1
\&  $HDFfile\->group("/")\->datasets;
.Ve
.SS "attrSet"
.IX Subsection "attrSet"
Set the value of an attribute(s) in the root '/' group of the file.
.PP
Currently attribute types supported are null-terminated strings and
any \s-1PDL\s0 type.
.PP
\&\fBUsage:\fR
.PP
.Vb 7
\&   $HDFfile\->attrSet( \*(Aqattr1\*(Aq => \*(Aqattr1Value\*(Aq,
\&                    \*(Aqattr2\*(Aq => \*(Aqattr2 value\*(Aq, 
\&                    \*(Aqattr3\*(Aq => $pdl,
\&                    .
\&                    .
\&                    .
\&                   );
.Ve
.PP
Returns undef on failure, 1 on success.
.PP
Note: This is a convenience method that is equivalent to:
.PP
.Vb 7
\&  $HDFfile\->group("/")\->attrSet( \*(Aqattr1\*(Aq => \*(Aqattr1Value\*(Aq,
\&                                 \*(Aqattr2\*(Aq => \*(Aqattr2 value\*(Aq, 
\&                                 \*(Aqattr3\*(Aq => $pdl,
\&                                 .
\&                                 .
\&                                 .
\&                                );
.Ve
.SS "attrGet"
.IX Subsection "attrGet"
Get the value of an attribute(s) in the root '/' group of the file.
.PP
Currently the attribute types supported are null-terminated strings
and PDLs.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   @attrValues = $HDFfile\->attrGet( \*(Aqattr1\*(Aq, \*(Aqattr2\*(Aq );
.Ve
.SS "attrDel"
.IX Subsection "attrDel"
Delete attribute(s) in the root \*(L"/\*(R" group of the file.
.PP
\&\fBUsage:\fR
.PP
.Vb 6
\& $HDFfile\->attrDel( \*(Aqattr1\*(Aq, 
\&                    \*(Aqattr2\*(Aq,
\&                    .
\&                    .
\&                    .
\&                   );
.Ve
.PP
Returns undef on failure, 1 on success.
.PP
Note: This is a convenience method that is equivalent to:
.PP
.Vb 6
\&  $HDFfile\->group("/")\->attrDel( \*(Aqattr1\*(Aq, 
\&                                 \*(Aqattr2\*(Aq,
\&                                 .
\&                                 .
\&                                 .
\&                                );
.Ve
.SS "attrs"
.IX Subsection "attrs"
Get a list of all attribute names in the root \*(L"/\*(R" group of the file.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   @attrs = $HDFfile\->attrs;
.Ve
.PP
Note: This is a convenience method that is equivalent to:
.PP
.Vb 1
\&  $HDFfile\->group("/")\->attrs
.Ve
.SS "reference"
.IX Subsection "reference"
Create a reference to part of a dataset in the root \*(L"/\*(R" group of the file.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   $HDFfile\->reference;
.Ve
.PP
Note: This is a convenience method that is equivalent to:
.PP
.Vb 1
\&  $HDFfile\->group("/")\->reference($referenceName,$datasetObj,@regionStart,@regionCount);
.Ve
.PP
Create a reference named \f(CW$referenceName\fR within the root group \*(L"/\*(R" to a subroutine of
the dataset \f(CW$datasetObj\fR. The region to be referenced is defined by the \f(CW@regionStart\fR
and \f(CW@regionCount\fR arrays.
.SS "_buildAttrIndex"
.IX Subsection "_buildAttrIndex"
Internal Method to build the attribute index hash
for the object
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   $hdf5obj\->_buildAttrIndex;
\&
\&
\& Output:
\&    Updated attrIndex data member
.Ve
.SS "clearAttrIndex"
.IX Subsection "clearAttrIndex"
Method to clear the attribute index hash
for the object. This is a mostly internal method that is
called whenever some part of the \s-1HDF5\s0 file has changed and the
attrIndex index is no longer valid.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   $hdf5obj\->clearAttrIndex;
.Ve
.SS "_buildGroupIndex"
.IX Subsection "_buildGroupIndex"
Internal Method to build the groupIndex hash
for the object
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   $hdf5obj\->_buildGroupIndex(@attrs);
\&   
\&   where:
\&     @attrs   List of attribute names to build
\&              a group index on.
\&              
\& Output:
\&    Updated groupIndex data member
.Ve
.SS "clearGroupIndex"
.IX Subsection "clearGroupIndex"
Method to clear the group index hash
for the object. This is a mostly internal method that is
called whenever some part of the \s-1HDF5\s0 file has changed and the
groupIndex index is no longer valid.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   $hdf5obj\->clearGroupIndex;
.Ve
.SS "getGroupsByAttr"
.IX Subsection "getGroupsByAttr"
Get the group names which attributes match a given set of values. This method
enables database-like queries to be made. I.e. you can get answers to 
questions like 'Which groups have attr1 = value1, and attr3 = value2?'.
.PP
\&\fBUsage:\fR
.PP
.Vb 2
\& @groupNames = $hdf5Obj\->getGroupsByAttr( \*(Aqattr1\*(Aq => \*(Aqvalue1\*(Aq, 
\&                                          \*(Aqattr2\*(Aq => \*(Aqvalue2\*(Aq );
.Ve
.SS "allAttrValues"
.IX Subsection "allAttrValues"
Returns information about group attributes defined in the \s-1HDF5\s0 datafile.
.PP
\&\fBUsage:\fR
.PP
.Vb 3
\& # Single Attr Usage. Returns an array of all 
\& #   values of attribute \*(AqattrName\*(Aq in the file.
\& $hdf5obj\->allAttrValues(\*(AqattrName\*(Aq);
\& 
\& # Multiple Attr Usage. Returns an 2D array of all 
\& #   values of attributes \*(Aqattr1\*(Aq, \*(Aqattr2\*(Aq in the file.
\& #   Higher\-Level
\& $hdf5obj\->allAttrValues(\*(Aqattr1\*(Aq, \*(Aqattr2\*(Aq);
.Ve
.SS "allAttrNames"
.IX Subsection "allAttrNames"
Returns a sorted list of all the group attribute names that are defined
in the file.
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\& my @attrNames = $hdf5obj\->allAttrNames;
.Ve
.SS "IDget"
.IX Subsection "IDget"
Returns the \s-1HDF5\s0 library \s-1ID\s0 for this object
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\& my $ID = $hdf5obj\->IDget;
.Ve
.SS "nameGet"
.IX Subsection "nameGet"
Returns the \s-1HDF5\s0 Group Name for this object. (Always '/', i.e. the
root group for this top-level object)
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\& my $name = $hdf5obj\->nameGet;
.Ve
.SS "\s-1DESTROY\s0"
.IX Subsection "DESTROY"
\&\s-1PDL::IO::HDF5\s0 Destructor \- Closes the \s-1HDF5\s0 file
.PP
\&\fBUsage:\fR
.PP
.Vb 1
\&   No Usage. Automatically called
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
John Cerney, j\-cerney1@raytheon.com
.PP
Andrew Benson, abenson@obs.carnegiescience.edu