Provided by: libpdl-io-hdf5-perl_0.73-3build2_amd64 bug

NAME

       PDL::IO::HDF5 - PDL Interface to the HDF5 Data Format.

DESCRIPTION

       This package provides an object-oriented interface for PDLs to the HDF5 data-format.
       Information on the HDF5 Format can be found at the HDF Group's web site at
       http://www.hdfgroup.org .

   LIMITATIONS
       Currently this interface only provides a subset of the total HDF5 library's capability.

       •
        Only HDF5 Simple datatypes are supported. No HDF5 Compound datatypes are supported since
        PDL doesn't support them.

       •
        Only HDF5 Simple dataspaces are supported.

SYNOPSIS

         use PDL::IO::HDF5;

         # Files #######
         my $newfile = new PDL::IO::HDF5("newfile.hdf");        # create new hdf5 or open existing file.
         my $attrValue = $existingFile->attrGet('AttrName');    # Get attribute value for file
         $existingFile->attSet('AttrName' => 'AttrValue');      # 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 '/'
                                                                # level.
         my @groups = $group->groups;                           # get a list of all the groups at the "mygroup"
                                                                # level.
         my $group2 = $group->group('newgroup');                # Create/open a new group in existing group "mygroup"

         $group->unlink('datasetName');                         # Delete a dataset from a group

         $group->reference($dataset,'refName',\@start,\@count); # Create a scalar reference to a subregion of a
                                                                # dataset, with specified start index and count.

         my $attrValue = $group->attrGet('AttrName');           # Get attribute value for a group
         $group->attrSet('AttrName' => 'AttrValue');            # Set attribute value(s) for a group
         $group->attrDel('AttrName1', 'AttrName2');             # Delete attribute(s) for a group
         @attrs = $group->attrs;                                # Get List of attributes for a group

         # Data Sets ########
         my $dataset = $group->dataset( 'datasetName');         # create a new or open existing dataset
                                                                #  in an existing group
         my $dataset = $newfile->dataset( 'datasetName');       # create a new or open existing dataset
                                                                #  in the root group of a file

         my $dataset2 = $newfile->dataset( 'datasetName');      # create a new or open existing dataset
                                                                # in the root group.
         my @datasets =  $existingFile->datasets;               # get a list of all datasets in the root '/' 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('AttrName');         # Get attribute value for a dataset
         $dataset->attSet('AttrName' => 'AttrValue');           # Set attribute value(s) for a dataset

MEMBER DATA

       ID
        ID number given to the file by the HDF5 library

       filename
        Name of the file.

       accessMode
        Access Mode?? ( read /write etc????)

       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.

        The index is of this form:

          {
            groupName1  =>  { attr1 => value, attr2 => value }.
            groupName2  =>  { attr1 => value, attr3 => value }.
           .
           .
           .
          }

        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.

       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.

        The index is of this form:

          { "attr1\0attt2" => { "value1\0value2' => [ group1, group2, ...],
                                "value3\0value3' => [ groupA ],
                                .
                                .
                                .
                              },

             "att1"        => { "value1' =>         [ group1, group2, ...],
                                "value3' =>         [ groupA ]
                                .
                                .
                                .
                              },
               .
               .
               .
          }

        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.

            groupName1  =>  { attr1 => value, attr2 => value }.
            groupName2  =>  { attr1 => value, attr3 => value }.
           .
           .
           .
          }

        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.

METHODS

   new
       PDL::IO::HDF5 constructor - creates PDL::IO::HDF5 object for reading or writing data.

       Usage:

          $a = new PDL::IO::HDF5( $filename );

       Arguments: 1) The name of the file.

       If this file exists and you want to write to it, prepend the name with the '>' character:
       ">name.nc"

       Returns undef on failure.

       Example:

               $hdf5obj = new PDL::IO::HDF5( "file.hdf" );

   filename
       Get the filename for the HDF5 file

       Usage:

          my $filename = $HDFfile->filename;

   group
       Open or create a group in the root "/" group (i.e. top level) of the HDF5 file.

       Usage:

          $HDFfile->group("groupName");

       Returns undef on failure, 1 on success.

   groups
       Get a list of groups in the root "/" group (i.e. top level) of the HDF5 file.

       Usage:

          @groups = $HDFfile->groups;

   unlink
       Unlink an object from the root "/" group (i.e. top level) of the HDF5 file.

       Usage:

          $HDFfile->unlink($name);

   dataset
       Open or create a dataset in the root "/" group (i.e. top level) of the HDF5 file.

       Usage:

          $HDFfile->dataset("groupName");

       Returns undef on failure, 1 on success.

       Note: This is a convienence method that is equivalent to:

         $HDFfile->group("/")->dataset("groupName");

   datasets
       Get a list of all dataset names in the root "/" group.

       Usage:

          @datasets = $HDF5file->datasets;

       Note: This is a convienence method that is equivalent to:

         $HDFfile->group("/")->datasets;

   attrSet
       Set the value of an attribute(s) in the root '/' group of the file.

       Currently attribute types supported are null-terminated strings and any PDL type.

       Usage:

          $HDFfile->attrSet( 'attr1' => 'attr1Value',
                           'attr2' => 'attr2 value',
                           'attr3' => $pdl,
                           .
                           .
                           .
                          );

       Returns undef on failure, 1 on success.

       Note: This is a convienence method that is equivalent to:

         $HDFfile->group("/")->attrSet( 'attr1' => 'attr1Value',
                                        'attr2' => 'attr2 value',
                                        'attr3' => $pdl,
                                        .
                                        .
                                        .
                                       );

   attrGet
       Get the value of an attribute(s) in the root '/' group of the file.

       Currently the attribute types supported are null-terminated strings and PDLs.

       Usage:

          @attrValues = $HDFfile->attrGet( 'attr1', 'attr2' );

   attrDel
       Delete attribute(s) in the root "/" group of the file.

       Usage:

        $HDFfile->attrDel( 'attr1',
                           'attr2',
                           .
                           .
                           .
                          );

       Returns undef on failure, 1 on success.

       Note: This is a convienence method that is equivalent to:

         $HDFfile->group("/")->attrDel( 'attr1',
                                        'attr2',
                                        .
                                        .
                                        .
                                       );

   attrs
       Get a list of all attribute names in the root "/" group of the file.

       Usage:

          @attrs = $HDFfile->attrs;

       Note: This is a convienence method that is equivalent to:

         $HDFfile->group("/")->attrs

   reference
       Create a reference to part of a dataset in the root "/" group of the file.

       Usage:

          $HDFfile->reference;

       Note: This is a convienence method that is equivalent to:

         $HDFfile->group("/")->reference($referenceName,$datasetObj,@regionStart,@regionCount);

       Create a reference named $referenceName within the root group "/" to a subroutine of the
       dataset $datasetObj. The region to be referenced is defined by the @regionStart and
       @regionCount arrays.

   _buildAttrIndex
       Internal Method to build the attribute index hash for the object

       Usage:

          $hdf5obj->_buildAttrIndex;

        Output:
           Updated attrIndex data member

   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 HDF5 file has changed and the attrIndex index is
       no longer valid.

       Usage:

          $hdf5obj->clearAttrIndex;

   _buildGroupIndex
       Internal Method to build the groupIndex hash for the object

       Usage:

          $hdf5obj->_buildGroupIndex(@attrs);

          where:
            @attrs   List of attribute names to build
                     a group index on.

        Output:
           Updated groupIndex data member

   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 HDF5 file has changed and the groupIndex index is no
       longer valid.

       Usage:

          $hdf5obj->clearGroupIndex;

   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?'.

       Usage:

        @groupNames = $hdf5Obj->getGroupsByAttr( 'attr1' => 'value1',
                                                 'attr2' => 'value2' );

   allAttrValues
       Returns information about group attributes defined in the HDF5 datafile.

       Usage:

        # Single Attr Usage. Returns an array of all
        #   values of attribute 'attrName' in the file.
        $hdf5obj->allAttrValues('attrName');

        # Multiple Attr Usage. Returns an 2D array of all
        #   values of attributes 'attr1', 'attr2' in the file.
        #   Higher-Level
        $hdf5obj->allAttrValues('attr1', 'attr2');

   allAttrNames
       Returns a sorted list of all the group attribute names that are defined in the file.

       Usage:

        my @attrNames = $hdf5obj->allAttrNames;

   IDget
       Returns the HDF5 library ID for this object

       Usage:

        my $ID = $hdf5obj->IDget;

   nameGet
       Returns the HDF5 Group Name for this object. (Always '/', i.e. the root group for this
       top-level object)

       Usage:

        my $name = $hdf5obj->nameGet;

   DESTROY
       PDL::IO::HDF5 Desctructor - Closes the HDF5 file

       Usage:

          No Usage. Automatically called

AUTHORS

       John Cerney, j-cerney1@raytheon.com

       Andrew Benson, abenson@obs.carnegiescience.edu