## ncsa.hdf.object.h5
Class H5Datatype

    java.lang.Object
      ncsa.hdf.object.HObject
          ncsa.hdf.object.Datatype
              ncsa.hdf.object.h5.H5Datatype

All Implemented Interfaces:
  java.io.Serializable, DataFormat

    public class H5Datatype

extends Datatype

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

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

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

Field Summary

Fields inherited from class ncsa.hdf.object.Datatype
`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_VLEN, datatypeClass, datatypeOrder, datatypeSign, datatypeSize, dims, enumMembers, NATIVE, NSGN, ORDER_BE, ORDER_LE, ORDER_NONE, ORDER_VAX, SIGN_2, SIGN_NONE`

Fields inherited from class ncsa.hdf.object.HObject
`linkTargetObjName, oid, separator`

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

Method Summary
`static java.lang.Object` `allocateArray(int tid, int size)` Allocates an one-dimensional array of byte, short, int, long, float, double, or String to store data in memory.
`void` `close(int tid)` Closes a datatype identifier.
`static int[]` `convertEnumNameToValue(int tid, java.lang.String[] in, int[] out)` Converts namess in an Enumeration Datatype to values.
`static java.lang.String[]` `convertEnumValueToName(int tid, java.lang.Object inValues, java.lang.String[] outNames)` Converts values in an Enumeration Datatype to names.
`void` `fromNative(int tid)` Set datatype characteristics (class, size, byte order and sign) from a given datatye identifier.
`java.lang.String` `getDatatypeDescription()` Returns a short text description of this datatype.
`static java.lang.String` `getDatatypeDescription(int tid)` Returns a short description of a given datatype ID.
`static int` `getDatatypeSize(int tid)` Returns the size (in bytes) of a given datatype identifier.
`java.util.List` `getMetadata()` Retrieves the metadata such as attributes from file.
`java.util.List` `getMetadata(int... attrPropList)`
`boolean` `hasAttribute()` Check if the object has any attributes attached.
`boolean` `isUnsigned()` Checks if this datatype is an unsigned integer.
`static boolean` `isUnsigned(int datatype)` Checks if a datatype specified by the identifier is an unsigned integer.
`int` `open()` Opens access to a named datatype.
`void` `removeMetadata(java.lang.Object info)` Deletes an existing metadata from this data object.
`void` `setName(java.lang.String newName)` Sets the name of the object.
`int` `toNative()` Converts the datatype object to a native datatype.
`static int` `toNative(int tid)` Deprecated. Not for public use in the future. Using `H5.H5Tget_native_type(int)` Return the HDF5 memory datatype identifier based on the HDF5 datatype identifier on disk
`void` `writeMetadata(java.lang.Object info)` Writes a specific metadata (such as attribute) into file.

Methods inherited from class ncsa.hdf.object.Datatype
`getBasetype, getDatatypeClass, getDatatypeOrder, getDatatypeSign, getDatatypeSize, getEnumMembers, setEnumMembers`

Methods inherited from class ncsa.hdf.object.HObject
`debug, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, setLinkTargetObjName, setPath, toString`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### H5Datatype

    public H5Datatype(FileFormat theFile,
                      java.lang.String name,
                      java.lang.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,
                                 java.lang.String name,
                                 java.lang.String path,
                                 long[] oid)

  Deprecated. Not for public use in the future.
  Using `H5Datatype(FileFormat, String, String)`

### 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 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(int nativeID)`

Method Detail

### hasAttribute

    public boolean hasAttribute()

  Description copied from interface: `DataFormat`
  Check if the object has any attributes attached.

  Returns:
    true if it has any attribute(s), false otherwise.

### convertEnumValueToName

    public static final java.lang.String[] convertEnumValueToName(int tid,
                                                                  java.lang.Object inValues,
                                                                  java.lang.String[] outNames)
                                                           throws 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 `null` 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, an `outNames` array with a different number of entries than the `inValues` array, or an invalid `tid` would all cause general failure.

  Parameters:
    `tid` - The identifier of the enumeration datatype.
    `inValues` - The array of enumerations values to be converted.
    `outNames` - The array of names to be populated. If null, the array will be created. If `outNames` is not null, the number of entries must be the same as the number of values in `inValues`.
  Returns:
    The string array of names if successful; otherwise return null.
  Throws:
    `HDF5Exception` - If there is an error at the HDF5 library level.

### convertEnumNameToValue

    public static final int[] convertEnumNameToValue(int tid,
                                                     java.lang.String[] in,
                                                     int[] out)
                                              throws HDF5Exception

  Converts namess 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:
    `tid` - The identifier of the enumeration datatype.
    `in` - The array of enumerations names to be converted.
    `out` - The array of values to be populated.
  Returns:
    The int array of values if successful; otherwise return null.
  Throws:
    `HDF5Exception` - If there is an error at the HDF5 library level.

### fromNative

    public void fromNative(int tid)

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

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

  For example, if the type identifier is a 32-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

    @Deprecated
    public static int toNative(int tid)

  Deprecated. Not for public use in the future.
  Using `H5.H5Tget_native_type(int)`

  Return the HDF5 memory datatype identifier based on the HDF5 datatype identifier on disk

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

### toNative

    public int toNative()

  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.toNative();

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

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

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

### allocateArray

    public static java.lang.Object allocateArray(int tid,
                                                 int size)
                                          throws java.lang.OutOfMemoryError

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

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

  returns a 32-bit integer array of size 100.

  Parameters:
    `tid` - the datatype id.
    `size` - the total number of data points of the array.
  Returns:
    the array object if successful; otherwise, return null.
  Throws:
    `java.lang.OutOfMemoryError`

### getDatatypeSize

    public static final int getDatatypeSize(int 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(int)`

### getDatatypeDescription

    public java.lang.String getDatatypeDescription()

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

  Overrides:
    `getDatatypeDescription` in class `Datatype`
  Returns:
    a short text description of this datatype

### getDatatypeDescription

    public static final java.lang.String getDatatypeDescription(int tid)

  Returns a short description of a given datatype ID.

  Parameters:
    `tid` - the HDF5 datatype identifier
  Returns:
    a string describing the data type.

### isUnsigned

    public boolean isUnsigned()

  Description copied from class: `Datatype`
  Checks if this datatype is an unsigned integer.

  Specified by:
    `isUnsigned` in class `Datatype`
  Returns:
    true if the datatype is an unsigned integer; otherwise, returns false.

### isUnsigned

    public static final boolean isUnsigned(int datatype)

  Checks if a datatype specified by the identifier is an unsigned integer.

  Parameters:
    `datatype` - the datatype ID to be checked.
  Returns:
    true is the datatype is an unsigned integer; otherwise returns false.

### open

    public int 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(int, String)`

### close

    public void close(int tid)

  Closes a datatype identifier.

  It calls H5.H5close(tid).

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

### getMetadata

    public java.util.List getMetadata()
                               throws HDF5Exception

  Description copied from interface: `DataFormat`
  Retrieves the metadata such as attributes from file.

  Metadata such as attributes are stored in a List.

  Specified by:
    `getMetadata` in interface `DataFormat`
  Overrides:
    `getMetadata` in class `Datatype`
  Returns:
    the list of metadata objects.
  Throws:
    `HDF5Exception`

### getMetadata

    public java.util.List getMetadata(int... attrPropList)
                               throws HDF5Exception

  Throws:
    `HDF5Exception`

### writeMetadata

    public void writeMetadata(java.lang.Object info)
                       throws java.lang.Exception

  Description copied from interface: `DataFormat`
  Writes a specific metadata (such as attribute) into file.

  If an HDF(4&5) attribute exists in file, the method updates its value. If the attribute does not exists in file, it creates the attribute in 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 file, one needs to get the instance of the attribute by getMetadata(), change its values, and use writeMetadata() to write the value.

  Specified by:
    `writeMetadata` in interface `DataFormat`
  Overrides:
    `writeMetadata` in class `Datatype`
  Parameters:
    `info` - the metadata to write.
  Throws:
    `java.lang.Exception`

### removeMetadata

    public void removeMetadata(java.lang.Object info)
                        throws HDF5Exception

  Description copied from interface: `DataFormat`
  Deletes an existing metadata from this data object.

  Specified by:
    `removeMetadata` in interface `DataFormat`
  Overrides:
    `removeMetadata` in class `Datatype`
  Parameters:
    `info` - the metadata to delete.
  Throws:
    `HDF5Exception`

### setName

    public void setName(java.lang.String newName)
                 throws java.lang.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:
    `java.lang.Exception`