Module org.hdfgroup.object
Package hdf.object.h5

Class H5Datatype

Object
hdf.object.HObject
hdf.object.Datatype
hdf.object.h5.H5Datatype
All Implemented Interfaces:
MetaDataContainer, Serializable
Direct Known Subclasses:
H5ReferenceType
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:

  • Field Details

    • refdims

      protected long[] refdims
      The dimension sizes of the reference object

  • Constructor Details

    • H5Datatype

      public H5Datatype(FileFormat theFile, String theName, String thePath)
      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 datatype.
      theName - the name of the dataset such as "dset1".
      thePath - the group path to the dataset such as "/g0/".

    • H5Datatype

      @Deprecated public H5Datatype(FileFormat theFile, String theName, String thePath, long[] oid)
      Deprecated.
      Not for public use in the future.
      Using H5Datatype(FileFormat, String, String)
      Parameters:
      theFile - the file that contains the datatype.
      theName - the name of the dataset such as "dset1".
      thePath - 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) throws Exception
      Constructs a Datatype with specified class, size, byte order and sign. The following is a list of a few examples of H5Datatype.
      1. to create unsigned native integer
        H5Datatype type = new H5Dataype(Datatype.CLASS_INTEGER, Datatype.NATIVE, Datatype.NATIVE, Datatype.SIGN_NONE);
      2. to create 16-bit signed integer with big endian
        H5Datatype type = new H5Dataype(Datatype.CLASS_INTEGER, 2, Datatype.ORDER_BE, Datatype.NATIVE);
      3. to create native float
        H5Datatype type = new H5Dataype(Datatype.CLASS_FLOAT, Datatype.NATIVE, Datatype.NATIVE, Datatype.NATIVE);
      4. to create 64-bit double
        H5Datatype type = new H5Dataype(Datatype.CLASS_FLOAT, 8, Datatype.NATIVE, Datatype.NATIVE);
      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. Valid values are NATIVE or a positive value. For string datatypes, -1 is also a valid value (to create a variable-length string).
      torder - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX, ORDER_NONE and NATIVE.
      tsign - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and NATIVE.
      Throws:
      Exception - if there is an error

    • H5Datatype

      public H5Datatype(int tclass, int tsize, int torder, int tsign, Datatype tbase) throws Exception
      Constructs a Datatype with specified class, size, byte order and sign. The following is a list of a few examples of H5Datatype.
      1. to create unsigned native integer
        H5Datatype type = new H5Dataype(Datatype.CLASS_INTEGER, Datatype.NATIVE, Datatype.NATIVE, Datatype.SIGN_NONE);
      2. to create 16-bit signed integer with big endian
        H5Datatype type = new H5Dataype(Datatype.CLASS_INTEGER, 2, Datatype.ORDER_BE, Datatype.NATIVE);
      3. to create native float
        H5Datatype type = new H5Dataype(Datatype.CLASS_FLOAT, Datatype.NATIVE, Datatype.NATIVE, Datatype.NATIVE);
      4. to create 64-bit double
        H5Datatype type = new H5Dataype(Datatype.CLASS_FLOAT, 8, Datatype.NATIVE, Datatype.NATIVE);
      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. Valid values are NATIVE or a positive value. For string datatypes, -1 is also a valid value (to create a variable-length string).
      torder - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX, ORDER_NONE and NATIVE.
      tsign - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and NATIVE.
      tbase - the base datatype of the new datatype
      Throws:
      Exception - if there is an error

    • H5Datatype

      public H5Datatype(int tclass, int tsize, int torder, int tsign, Datatype tbase, Datatype pbase) throws Exception
      Constructs a Datatype with specified class, size, byte order and sign. The following is a list of a few examples of H5Datatype.
      1. to create unsigned native integer
        H5Datatype type = new H5Dataype(Datatype.CLASS_INTEGER, Datatype.NATIVE, Datatype.NATIVE, Datatype.SIGN_NONE);
      2. to create 16-bit signed integer with big endian
        H5Datatype type = new H5Dataype(Datatype.CLASS_INTEGER, 2, Datatype.ORDER_BE, Datatype.NATIVE);
      3. to create native float
        H5Datatype type = new H5Dataype(Datatype.CLASS_FLOAT, Datatype.NATIVE, Datatype.NATIVE, Datatype.NATIVE);
      4. to create 64-bit double
        H5Datatype type = new H5Dataype(Datatype.CLASS_FLOAT, 8, Datatype.NATIVE, Datatype.NATIVE);
      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. Valid values are NATIVE or a positive value. For string datatypes, -1 is also a valid value (to create a variable-length string).
      torder - the byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, ORDER_VAX, ORDER_NONE and NATIVE.
      tsign - the sign of the datatype. Valid values are SIGN_NONE, SIGN_2 and NATIVE.
      tbase - the base datatype of the new datatype
      pbase - the parent datatype of the new datatype
      Throws:
      Exception - if there is an error

    • H5Datatype

      public H5Datatype(FileFormat theFile, long nativeID) throws Exception
      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(Datatype.CLASS_INTEGER, 4, Datatype.NATIVE, Datatype.SIGN_NONE);
      Parameters:
      theFile - the file that contains the datatype.
      nativeID - the native datatype identifier.
      Throws:
      Exception - if there is an error
      See Also:

    • H5Datatype

      public H5Datatype(FileFormat theFile, long nativeID, Datatype pbase) throws Exception
      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(Datatype.CLASS_INTEGER, 4, Datatype.NATIVE, Datatype.SIGN_NONE);
      Parameters:
      theFile - the file that contains the datatype.
      nativeID - the native datatype identifier.
      pbase - the parent datatype of the new datatype
      Throws:
      Exception - if there is an error
      See Also:

  • Method Details

    • 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

    • getToken

      public long[] getToken()
      Get the token for this object.
      Returns:
      true if it has any attributes, false otherwise.

    • hasAttribute

      public boolean hasAttribute()
      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.

    • bigDecimalToByte

      public byte[] bigDecimalToByte(int start, int len, BigDecimal[] data)
      Convert from an array of BigDecimal into an array of bytes
      Parameters:
      start - The position in the input array of BigDecimal to start
      len - The number of 'BigDecimal' to convert
      data - The input array of BigDecimal
      Returns:
      an array of bytes

    • bigDecimalToByte

      public byte[] bigDecimalToByte(BigDecimal[] data, int start)
      Convert from a single BigDecimal object from an array of BigDecimal into an array of bytes
      Parameters:
      data - The input Float
      start - The position in the input array of BigDecimal to start
      Returns:
      an array of bytes

    • convertBigDecimalToByte

      public byte[] convertBigDecimalToByte(BigDecimal num)
      Convert a BigDecimal to a byte array .
      Parameters:
      num - The BigDecimal number to convert
      Returns:
      A byte array representing the BigDecimal.

    • byteToBigDecimal

      public BigDecimal[] byteToBigDecimal(int start, int len, byte[] data)
      Convert a range from an array of bytes into an array of BigDecimal
      Parameters:
      start - The position in the input array of bytes to start
      len - The number of 'BigDecimal' to convert
      data - The input array of bytes
      Returns:
      an array of 'len' BigDecimal

    • byteToBigDecimal

      public BigDecimal byteToBigDecimal(byte[] data, int start)
      Convert 4 bytes from an array of bytes into a single BigDecimal
      Parameters:
      data - The input array of bytes
      start - The position in the input array of bytes to start
      Returns:
      The BigDecimal value of the bytes.

    • convertByteToBigDecimal

      public BigDecimal convertByteToBigDecimal(byte[] raw)
      Convert byte array data to a BigDecimal.
      Parameters:
      raw - The byte array to convert to a BigDecimal
      Returns:
      A BigDecimal representing the byte array.

    • 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 static final Object allocateArray(H5Datatype dtype, int numPoints) 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[]) H5Datatype.allocateArray(datatype, 100);
      returns a 32-bit integer array of size 100.
      Parameters:
      dtype - the type.
      numPoints - 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.

    • clear

      public void clear()
      Removes all of the elements from metadata list. The list should be empty after this call returns.
      Specified by:
      clear in interface MetaDataContainer
      Overrides:
      clear in class Datatype

    • getMetadata

      public List<Attribute> getMetadata() throws hdf.hdf5lib.exceptions.HDF5Exception
      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 - if the metadata can not be retrieved

    • getMetadata

      public List<Attribute> getMetadata(int... attrPropList) throws hdf.hdf5lib.exceptions.HDF5Exception
      Retrieves the object's metadata, such as attributes, from the file. Metadata, such as attributes, is stored in a List.
      Parameters:
      attrPropList - the list of properties to get
      Returns:
      the list of metadata objects.
      Throws:
      hdf.hdf5lib.exceptions.HDF5Exception - if the metadata can not be retrieved

    • writeMetadata

      public void writeMetadata(Object info) throws Exception
      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
      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 - if the metadata can not be removed

    • updateMetadata

      public void updateMetadata(Object info) throws hdf.hdf5lib.exceptions.HDF5Exception
      Updates an existing piece of metadata attached to this object.
      Specified by:
      updateMetadata in interface MetaDataContainer
      Overrides:
      updateMetadata in class Datatype
      Parameters:
      info - the metadata to update.
      Throws:
      hdf.hdf5lib.exceptions.HDF5Exception - if the metadata can not be updated

    • 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

    • setFullname

      public void setFullname(String newPath, String newName) throws Exception
      Description copied from class: HObject
      Sets the full name of the object.
      Overrides:
      setFullname in class HObject
      Parameters:
      newPath - The path of the object.
      newName - The name of the object.
      Throws:
      Exception - if a failure occurred

    • isText

      public boolean isText()
      Description copied from class: Datatype
      Checks if this datatype is a boolean type.
      Specified by:
      isText in class Datatype
      Returns:
      true if the datatype is boolean; false otherwise

    • isRefObj

      public boolean isRefObj()
      Checks if this datatype is an object reference type.
      Returns:
      true if the datatype is an object reference; false otherwise

    • isRegRef

      public boolean isRegRef()
      Checks if this datatype is a region reference type.
      Returns:
      true if the datatype is a region reference; false otherwise

    • isStdRef

      public boolean isStdRef()
      Checks if this datatype is a standard reference type.
      Returns:
      true if the datatype is a standard reference; false otherwise

    • getReferenceType

      public long getReferenceType() throws hdf.hdf5lib.exceptions.HDF5Exception
      Description copied from class: Datatype
      If the datatype is a reference, then return the type.
      Overrides:
      getReferenceType in class Datatype
      Returns:
      the datatype reference type if successful; otherwise returns negative value.
      Throws:
      hdf.hdf5lib.exceptions.HDF5Exception

    • descReferenceObject

      public static String descReferenceObject(long container, byte[] refarr)
      Describes the dataset object description for a 1.10 reference.
      Parameters:
      container - the dataset/attribute with the reference
      refarr - the reference datatype data to be checked.
      Returns:
      the dataset reference object description.

    • descRegionDataset

      public static String descRegionDataset(long container, byte[] refarr)
      Describes the dataset region description for a 1.10 reference.
      Parameters:
      container - the dataset/attribute with the reference
      refarr - the reference datatype data to be checked.
      Returns:
      the dataset region description.

    • typeObjectRef

      public static int typeObjectRef(long container, int obj_type, byte[] refarr)
      Gets the dataset reference type for a 1.10 reference.
      Parameters:
      container - the dataset/attribute with the reference
      refarr - the reference datatype data to be checked.
      Returns:
      the dataset reference type.

    • zeroArrayCheck

      public static boolean zeroArrayCheck(byte[] refarr)
      Checks if a reference datatype is all zero.
      Parameters:
      refarr - the reference datatype data to be checked.
      Returns:
      true is the reference datatype data is all zero; otherwise returns false.

    • getNativeStrPad

      public int getNativeStrPad()
      Gets the string padding.
      Returns:
      the string padding value

    • extractCompoundInfo

      public static void extractCompoundInfo(H5Datatype dtype, 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:
      dtype - the datatype to extract compound info from
      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 memberName) 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:
      memberName - 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.