hdf.object.h5

## Class H5Datatype

- Object
- - hdf.object.HObject
  - - hdf.object.Datatype
    - - hdf.object.h5.H5Datatype

- All Implemented Interfaces:
    MetaDataContainer, Serializable

      public class H5Datatype
      extends Datatype

  This class defines HDF5 datatype characteristics and APIs for a data type.

  This class provides several methods to convert an HDF5 datatype identifier to a datatype object, and vice versa. A datatype object is described by four basic fields: datatype class, size, byte order, and sign, while an HDF5 datatype is presented by a datatype identifier.

  Version:
    1.1 9/4/2007
  Author:
    Peter X. Cao
  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from class hdf.object.Datatype

      `arrayDims, baseType, CLASS_ARRAY, CLASS_BITFIELD, CLASS_CHAR, CLASS_COMPOUND, CLASS_ENUM, CLASS_FLOAT, CLASS_INTEGER, CLASS_NO_CLASS, CLASS_OPAQUE, CLASS_REFERENCE, CLASS_STRING, CLASS_TIME, CLASS_VLEN, compoundMemberNames, compoundMemberOffsets, compoundMemberTypes, datatypeClass, datatypeDescription, datatypeOrder, datatypeSign, datatypeSize, enumMembers, is_variable_str, is_VLEN, NATIVE, NSGN, ORDER_BE, ORDER_LE, ORDER_NONE, ORDER_VAX, SIGN_2, SIGN_NONE`

    - ### Fields inherited from class hdf.object.HObject

      `fileFormat, linkTargetObjName, oid, separator`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `H5Datatype(FileFormat theFile, String name, String path)` Constructs an named HDF5 data type object for a given file, dataset name and group path.
    `H5Datatype(FileFormat theFile, String name, String path, long[] oid)` Deprecated. Not for public use in the future. Using `H5Datatype(FileFormat, String, String)`
    `H5Datatype(int tclass, int tsize, int torder, int tsign)` Constructs a Datatype with specified class, size, byte order and sign.
    `H5Datatype(int tclass, int tsize, int torder, int tsign, Datatype tbase)` Constructs a Datatype with specified class, size, byte order and sign.
    `H5Datatype(int tclass, int tsize, int torder, int tsign, Datatype tbase, Datatype pbase)` Constructs a Datatype with specified class, size, byte order and sign.
    `H5Datatype(int tclass, int tsize, int torder, int tsign, Datatype tbase, Datatype pbase, List<H5Datatype> members)` Constructs a Datatype with specified class, size, byte order and sign.
    `H5Datatype(long nativeID)` Constructs a Datatype with a given native datatype identifier.
    `H5Datatype(long nativeID, Datatype pbase)` Constructs a Datatype with a given native datatype identifier.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `allocateArray(int spaceSize)` Allocates a one-dimensional array of byte, short, int, long, float, double, or String to store data in memory.
    `void` | `close(long tid)` Closes a datatype identifier.
    `Object[]` | `convertEnumNameToValue(String[] in)` Converts names in an Enumeration Datatype to values.
    `String[]` | `convertEnumValueToName(Object inValues)` Converts values in an Enumeration Datatype to names.
    `long` | `createCompoundFieldType(String member_name)` Creates a datatype of a compound with one field.
    `long` | `createNative()` Converts the datatype object to a native datatype.
    `void` | `extractCompoundInfo(String name, List<String> names, List<Datatype> flatListTypes)` Extracts compound information into flat structure.
    `void` | `fromNative(long tid)` Set datatype characteristics (class, size, byte order and sign) from a given datatype identifier.
    `static long` | `getDatatypeSize(long tid)` Returns the size (in bytes) of a given datatype identifier.
    `String` | `getDescription()` Returns a short text description of this datatype.
    `List<Attribute>` | `getMetadata()` Retrieves the object's metadata, such as attributes, from the file.
    `List<Attribute>` | `getMetadata(int... attrPropList)`
    `int` | `getNativeStrPad()`
    `boolean` | `hasAttribute()` Check if the object has any attributes attached.
    `boolean` | `isRefObj()`
    `boolean` | `isRegRef()`
    `boolean` | `isText()`
    `static boolean` | `isUnsigned(long tid)` Checks if a datatype specified by the identifier is an unsigned integer.
    `long` | `open()` Opens access to a named datatype.
    `void` | `removeMetadata(Object info)` Deletes an existing piece of metadata from this object.
    `void` | `setName(String newName)` Sets the name of the object.
    `static long` | `toNative(long tid)`
    `void` | `writeMetadata(Object info)` Writes a specific piece of metadata (such as an attribute) into the file.

    - ### Methods inherited from class hdf.object.Datatype

      `getArrayDims, getCompoundMemberNames, getCompoundMemberTypes, getDatatypeBase, getDatatypeClass, getDatatypeOrder, getDatatypeSign, getDatatypeSize, getEnumMembers, getEnumMembersAsString, isArray, isBitField, isChar, isCompound, isEnum, isFloat, isInteger, isOpaque, isRef, isString, isUnsigned, isVarStr, isVLEN, setEnumMembers, toString, updateMetadata`

    - ### Methods inherited from class hdf.object.HObject

      `debug, equals, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, setLinkTargetObjName, setPath`

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### H5Datatype

          public H5Datatype(FileFormat theFile,
                            String name,
                            String path)

      Constructs an named HDF5 data type object for a given file, dataset name and group path.

      The datatype object represents an existing named datatype in file. For example,

           new H5Datatype(file, "dtype1", "/g0")

      constructs a datatype object that corresponds to the dataset,"dset1", at group "/g0".
      Parameters:
        `theFile` - the file that contains the dataset.
        `name` - the name of the dataset such as "dset1".
        `path` - the group path to the dataset such as "/g0/".

    - #### H5Datatype

          @Deprecated
          public H5Datatype(FileFormat theFile,
                                        String name,
                                        String path,
                                        long[] oid)

      Deprecated. Not for public use in the future.
      Using `H5Datatype(FileFormat, String, String)`
      Parameters:
        `theFile` - the file that contains the dataset.
        `name` - the name of the dataset such as "dset1".
        `path` - the group path to the dataset such as "/g0/".
        `oid` - the oid of the dataset.

    - #### H5Datatype

          public H5Datatype(int tclass,
                            int tsize,
                            int torder,
                            int tsign)

      Constructs a Datatype with specified class, size, byte order and sign.

      The following is a list of a few example of H5Datatype.

      1. to create unsigned native integer
         H5Datatype type = new H5Dataype(CLASS_INTEGER, NATIVE, NATIVE, SIGN_NONE);
      2. to create 16-bit signed integer with big endian
         H5Datatype type = new H5Dataype(CLASS_INTEGER, 2, ORDER_BE, NATIVE);
      3. to create native float
         H5Datatype type = new H5Dataype(CLASS_FLOAT, NATIVE, NATIVE, -1);
      4. to create 64-bit double
         H5Datatype type = new H5Dataype(CLASS_FLOAT, 8, NATIVE, -1);
      Parameters:
        `tclass` - the class of the datatype, e.g. CLASS_INTEGER, CLASS_FLOAT and etc.
        `tsize` - the size of the datatype in bytes, e.g. for a 32-bit integer, the size is 4.
        `torder` - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX and ORDER_NONE
        `tsign` - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and MSGN

    - #### H5Datatype

          public H5Datatype(int tclass,
                            int tsize,
                            int torder,
                            int tsign,
                            Datatype tbase)

      Constructs a Datatype with specified class, size, byte order and sign.

      The following is a list of a few example of H5Datatype.

      1. to create unsigned native integer
         H5Datatype type = new H5Dataype(CLASS_INTEGER, NATIVE, NATIVE, SIGN_NONE);
      2. to create 16-bit signed integer with big endian
         H5Datatype type = new H5Dataype(CLASS_INTEGER, 2, ORDER_BE, NATIVE);
      3. to create native float
         H5Datatype type = new H5Dataype(CLASS_FLOAT, NATIVE, NATIVE, -1);
      4. to create 64-bit double
         H5Datatype type = new H5Dataype(CLASS_FLOAT, 8, NATIVE, -1);
      Parameters:
        `tclass` - the class of the datatype, e.g. CLASS_INTEGER, CLASS_FLOAT and etc.
        `tsize` - the size of the datatype in bytes, e.g. for a 32-bit integer, the size is 4.
        `torder` - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX and ORDER_NONE
        `tsign` - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and MSGN
        `tbase` - the base datatype of the new datatype

    - #### H5Datatype

          public H5Datatype(int tclass,
                            int tsize,
                            int torder,
                            int tsign,
                            Datatype tbase,
                            Datatype pbase)

      Constructs a Datatype with specified class, size, byte order and sign.

      The following is a list of a few example of H5Datatype.

      1. to create unsigned native integer
         H5Datatype type = new H5Dataype(CLASS_INTEGER, NATIVE, NATIVE, SIGN_NONE);
      2. to create 16-bit signed integer with big endian
         H5Datatype type = new H5Dataype(CLASS_INTEGER, 2, ORDER_BE, NATIVE);
      3. to create native float
         H5Datatype type = new H5Dataype(CLASS_FLOAT, NATIVE, NATIVE, -1);
      4. to create 64-bit double
         H5Datatype type = new H5Dataype(CLASS_FLOAT, 8, NATIVE, -1);
      Parameters:
        `tclass` - the class of the datatype, e.g. CLASS_INTEGER, CLASS_FLOAT and etc.
        `tsize` - the size of the datatype in bytes, e.g. for a 32-bit integer, the size is 4.
        `torder` - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX and ORDER_NONE
        `tsign` - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and MSGN
        `tbase` - the base datatype of the new datatype
        `pbase` - the parent datatype of the new datatype

    - #### H5Datatype

          public H5Datatype(int tclass,
                            int tsize,
                            int torder,
                            int tsign,
                            Datatype tbase,
                            Datatype pbase,
                            List<H5Datatype> members)

      Constructs a Datatype with specified class, size, byte order and sign.

      The following is a list of a few example of H5Datatype.

      1. to create unsigned native integer
         H5Datatype type = new H5Dataype(CLASS_INTEGER, NATIVE, NATIVE, SIGN_NONE);
      2. to create 16-bit signed integer with big endian
         H5Datatype type = new H5Dataype(CLASS_INTEGER, 2, ORDER_BE, NATIVE);
      3. to create native float
         H5Datatype type = new H5Dataype(CLASS_FLOAT, NATIVE, NATIVE, -1);
      4. to create 64-bit double
         H5Datatype type = new H5Dataype(CLASS_FLOAT, 8, NATIVE, -1);
      Parameters:
        `tclass` - the class of the datatype, e.g. CLASS_INTEGER, CLASS_FLOAT and etc.
        `tsize` - the size of the datatype in bytes, e.g. for a 32-bit integer, the size is 4.
        `torder` - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX and ORDER_NONE
        `tsign` - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and MSGN
        `tbase` - the base datatype of the new datatype
        `pbase` - the parent datatype of the new datatype
        `members` - the list of member datatypes

    - #### H5Datatype

          public H5Datatype(long nativeID)

      Constructs a Datatype with a given native datatype identifier.

      For example, if the datatype identifier is a 32-bit unsigned integer created from HDF5,

           int tid = H5.H5Tcopy(HDF5Constants.H5T_NATIVE_UNINT32);
           Datatype dtype = new Datatype(tid);

      will construct a datatype equivalent to new Datatype(CLASS_INTEGER, 4, NATIVE, SIGN_NONE);
      Parameters:
        `nativeID` - the native datatype identifier.
      See Also:
        `fromNative(long nativeID)`

    - #### H5Datatype

          public H5Datatype(long nativeID,
                            Datatype pbase)

      Constructs a Datatype with a given native datatype identifier.

      For example, if the datatype identifier is a 32-bit unsigned integer created from HDF5,

           int tid = H5.H5Tcopy(HDF5Constants.H5T_NATIVE_UNINT32);
           Datatype dtype = new Datatype(tid);

      will construct a datatype equivalent to new Datatype(CLASS_INTEGER, 4, NATIVE, SIGN_NONE);
      Parameters:
        `nativeID` - the native datatype identifier.
        `pbase` - the parent datatype of the new datatype
      See Also:
        `fromNative(long nativeID)`

  - ### Method Detail

    - #### open

          public long open()

      Opens access to a named datatype.

      It calls H5.H5Topen(loc, name).

      Overrides:
        `open` in class `Datatype`
      Returns:
        the datatype identifier if successful; otherwise returns negative value.
      See Also:
        `H5.H5Topen(long, String, long)`

    - #### close

          public void close(long tid)

      Closes a datatype identifier.

      It calls H5.H5close(tid).

      Specified by:
        `close` in class `Datatype`
      Parameters:
        `tid` - the datatype ID to close

    - #### hasAttribute

          public boolean hasAttribute()

      Description copied from interface: `MetaDataContainer`
      Check if the object has any attributes attached.
      Returns:
        true if it has any attributes, false otherwise.

    - #### convertEnumValueToName

          public String[] convertEnumValueToName(Object inValues)
                                          throws hdf.hdf5lib.exceptions.HDF5Exception

      Converts values in an Enumeration Datatype to names.

      This method searches the identified enumeration datatype for the values appearing in `inValues` and returns the names corresponding to those values. If a given value is not found in the enumeration datatype, the name corresponding to that value will be set to `"ENUM ERR value"` in the string array that is returned.

      If the method fails in general, null will be returned instead of a String array. An empty `inValues` parameter would cause general failure.

      Parameters:
        `inValues` - The array of enumerations values to be converted.
      Returns:
        The string array of names if successful; otherwise return null.
      Throws:
        `hdf.hdf5lib.exceptions.HDF5Exception` - If there is an error at the HDF5 library level.

    - #### convertEnumNameToValue

          public Object[] convertEnumNameToValue(String[] in)
                                          throws hdf.hdf5lib.exceptions.HDF5Exception

      Converts names in an Enumeration Datatype to values.

      This method searches the identified enumeration datatype for the names appearing in `inValues` and returns the values corresponding to those names.

      Parameters:
        `in` - The array of enumerations names to be converted.
      Returns:
        The int array of values if successful; otherwise return null.
      Throws:
        `hdf.hdf5lib.exceptions.HDF5Exception` - If there is an error at the HDF5 library level.

    - #### fromNative

          public void fromNative(long tid)

      Description copied from class: `Datatype`
      Set datatype characteristics (class, size, byte order and sign) from a given datatype identifier.

      Sub-classes must implement it so that this datatype will be converted accordingly.

      For example, if the type identifier is a 64-bit unsigned integer created from HDF5,

           H5Datatype dtype = new H5Datatype();
           dtype.fromNative(HDF5Constants.H5T_NATIVE_UNINT32);

      Where dtype is equivalent to
      new H5Datatype(CLASS_INTEGER, 4, NATIVE, SIGN_NONE);
      Specified by:
        `fromNative` in class `Datatype`
      Parameters:
        `tid` - the datatype identifier.

    - #### toNative

          public static long toNative(long tid)

      Parameters:
        `tid` - the datatype identification disk.
      Returns:
        the memory datatype identifier if successful, and negative otherwise.

    - #### createNative

          public long createNative()

      Description copied from class: `Datatype`
      Converts the datatype object to a native datatype. Subclasses must implement it so that this datatype will be converted accordingly. Use close() to close the native identifier; otherwise, the datatype will be left open.

      For example, a HDF5 datatype created from

           H5Dataype dtype = new H5Datatype(CLASS_INTEGER, 4, NATIVE, SIGN_NONE);
           int tid = dtype.createNative();

      The "tid" will be the HDF5 datatype id of a 64-bit unsigned integer, which is equivalent to

           int tid = H5.H5Tcopy(HDF5Constants.H5T_NATIVE_UNINT32);

      Specified by:
        `createNative` in class `Datatype`
      Returns:
        the identifier of the native datatype.

    - #### allocateArray

          public Object allocateArray(int spaceSize)
                               throws OutOfMemoryError

      Allocates a one-dimensional array of byte, short, int, long, float, double, or String to store data in memory. For example,

           long tid = H5.H5Tcopy(HDF5Constants.H5T_NATIVE_INT32);
           int[] data = (int[]) allocateArray(100);

      returns a 32-bit integer array of size 100.
      Parameters:
        `spaceSize` - the total number of data points of the array.
      Returns:
        the array object if successful; otherwise, return null.
      Throws:
        `OutOfMemoryError` - If there is a failure.

    - #### getDatatypeSize

          public static final long getDatatypeSize(long tid)

      Returns the size (in bytes) of a given datatype identifier.

      It basically just calls H5Tget_size(tid).

      Parameters:
        `tid` - The datatype identifier.
      Returns:
        The size of the datatype in bytes.
      See Also:
        `H5.H5Tget_size(long)`

    - #### getDescription

          public String getDescription()

      Description copied from class: `Datatype`
      Returns a short text description of this datatype.
      Overrides:
        `getDescription` in class `Datatype`
      Returns:
        a short text description of this datatype

    - #### isUnsigned

          public static final boolean isUnsigned(long tid)

      Checks if a datatype specified by the identifier is an unsigned integer.
      Parameters:
        `tid` - the datatype ID to be checked.
      Returns:
        true is the datatype is an unsigned integer; otherwise returns false.

    - #### getMetadata

          public List<Attribute> getMetadata()
                                      throws hdf.hdf5lib.exceptions.HDF5Exception

      Description copied from interface: `MetaDataContainer`
      Retrieves the object's metadata, such as attributes, from the file.

      Metadata, such as attributes, is stored in a List.

      Specified by:
        `getMetadata` in interface `MetaDataContainer`
      Overrides:
        `getMetadata` in class `Datatype`
      Returns:
        the list of metadata objects.
      Throws:
        `hdf.hdf5lib.exceptions.HDF5Exception`

    - #### getMetadata

          public List<Attribute> getMetadata(int... attrPropList)
                                      throws hdf.hdf5lib.exceptions.HDF5Exception

      Throws:
        `hdf.hdf5lib.exceptions.HDF5Exception`

    - #### writeMetadata

          public void writeMetadata(Object info)
                             throws Exception

      Description copied from interface: `MetaDataContainer`
      Writes a specific piece of metadata (such as an attribute) into the file. If an HDF(4&5) attribute exists in the file, this method updates its value. If the attribute does not exist in the file, it creates the attribute in the file and attaches it to the object. It will fail to write a new attribute to the object where an attribute with the same name already exists. To update the value of an existing attribute in the file, one needs to get the instance of the attribute by getMetadata(), change its values, then use writeMetadata() to write the value.
      Specified by:
        `writeMetadata` in interface `MetaDataContainer`
      Overrides:
        `writeMetadata` in class `Datatype`
      Parameters:
        `info` - the metadata to write.
      Throws:
        `Exception` - if the metadata can not be written

    - #### removeMetadata

          public void removeMetadata(Object info)
                              throws hdf.hdf5lib.exceptions.HDF5Exception

      Description copied from interface: `MetaDataContainer`
      Deletes an existing piece of metadata from this object.
      Specified by:
        `removeMetadata` in interface `MetaDataContainer`
      Overrides:
        `removeMetadata` in class `Datatype`
      Parameters:
        `info` - the metadata to delete.
      Throws:
        `hdf.hdf5lib.exceptions.HDF5Exception`

    - #### setName

          public void setName(String newName)
                       throws Exception

      Description copied from class: `HObject`
      Sets the name of the object. setName (String newName) changes the name of the object in the file.
      Overrides:
        `setName` in class `HObject`
      Parameters:
        `newName` - The new name of the object.
      Throws:
        `Exception` - if name is root or contains separator

    - #### isText

          public boolean isText()

      Specified by:
        `isText` in class `Datatype`

    - #### isRefObj

          public boolean isRefObj()

    - #### isRegRef

          public boolean isRegRef()

    - #### getNativeStrPad

          public int getNativeStrPad()

    - #### extractCompoundInfo

          public void extractCompoundInfo(String name,
                                          List<String> names,
                                          List<Datatype> flatListTypes)

      Extracts compound information into flat structure.

      For example, compound datatype "nest" has {nest1{a, b, c}, d, e} then extractCompoundInfo() will put the names of nested compound fields into a flat list as

           nest.nest1.a
           nest.nest1.b
           nest.nest1.c
           nest.d
           nest.e

      Parameters:
        `name` - the name of the compound datatype
        `names` - the list to store the member names of the compound datatype
        `flatListTypes` - the list to store the nested member names of the compound datatype

    - #### createCompoundFieldType

          public long createCompoundFieldType(String member_name)
                                       throws hdf.hdf5lib.exceptions.HDF5Exception

      Creates a datatype of a compound with one field.

      This function is needed to read/write data field by field.

      Parameters:
        `member_name` - The name of the datatype
      Returns:
        the identifier of the compound datatype.
      Throws:
        `hdf.hdf5lib.exceptions.HDF5Exception` - If there is an error at the HDF5 library level.

Copyright © 2018. All Rights Reserved.