Datatype (HDFView 2.14)

Object
- hdf.object.HObject
- - hdf.object.Datatype

All Implemented Interfaces:

DataFormat, Serializable

Direct Known Subclasses:

H4Datatype, H5Datatype
```
public abstract class Datatype
extends HObject
```
Datatype is an abstract class that defines datatype characteristics and APIs for a data type.
A datatype has four basic characteristics: class, size, byte order and sign. These characteristics are defined in the HDF5 User's Guide.
These characteristics apply to all the sub-classes. The sub-classes may have different ways to describe a datatype. We here define the native datatype to the datatype used by the sub-class. For example, H5Datatype uses a datatype identifier (hid_t) to specify a datatype. NC2Datatype uses ucar.nc2.DataType object to describe its datatype. "Native" here is different from the "native" definition in the HDF5 library.
Two functions, toNative() and fromNative(), are defined to convert the general characteristics to/from the native datatype. Sub-classes must implement these functions so that the conversion will be done correctly. The values of the CLASS member are not identical to HDF5 values for a datatype class.

Version:

1.1 9/4/2007

Author:

Peter X. Cao

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`protected Datatype`	`baseType` The base datatype of every element of the array (for CLASS_ARRAY datatype).
`static int`	`CLASS_ARRAY` See HDF5 User's Guide
`static int`	`CLASS_BITFIELD` See HDF5 User's Guide
`static int`	`CLASS_CHAR` See HDF5 User's Guide
`static int`	`CLASS_COMPOUND` See HDF5 User's Guide
`static int`	`CLASS_ENUM` See HDF5 User's Guide
`static int`	`CLASS_FLOAT` See HDF5 User's Guide
`static int`	`CLASS_INTEGER` See HDF5 User's Guide
`static int`	`CLASS_NO_CLASS` See HDF5 User's Guide
`static int`	`CLASS_OPAQUE` See HDF5 User's Guide
`static int`	`CLASS_REFERENCE` See HDF5 User's Guide
`static int`	`CLASS_STRING` See HDF5 User's Guide
`static int`	`CLASS_TIME` See HDF5 User's Guide
`static int`	`CLASS_VLEN` See HDF5 User's Guide
`protected List<Integer>`	`compoundMemberFieldIDs` The list of field IDs of members of a compound Datatype.
`protected List<String>`	`compoundMemberNames` The list of names of members of a compound Datatype.
`protected List<Long>`	`compoundMemberOffsets` The list of offsets of members of a compound Datatype.
`protected List<Datatype>`	`compoundMemberTypes` The list of types of members of a compound Datatype
`protected int`	`datatypeClass` The class of the datatype.
`protected int`	`datatypeOrder` The byte order of the datatype.
`protected int`	`datatypeSign` The sign of the datatype.
`protected int`	`datatypeSize` The size (in bytes) of the datatype.
`protected long[]`	`dims` The dimensions of the ARRAY element of an ARRAY datatype.
`protected String`	`enumMembers` The (name, value) pairs of enum members.
`protected boolean`	`isVLEN` Determines whether this datatype is a variable-length type.
`static int`	`NATIVE` The default definition for datatype size, order, and sign.
`static int`	`NSGN` See HDF5 User's Guide
`static int`	`ORDER_BE` See HDF5 User's Guide
`static int`	`ORDER_LE` See HDF5 User's Guide
`static int`	`ORDER_NONE` See HDF5 User's Guide
`static int`	`ORDER_VAX` See HDF5 User's Guide
`static int`	`SIGN_2` See HDF5 User's Guide
`static int`	`SIGN_NONE` See HDF5 User's Guide

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

Constructor Summary

Constructors
Constructor and Description
`Datatype(FileFormat theFile, String name, String path)` Constructs a named datatype with a given file, name and path.
`Datatype(FileFormat theFile, String name, String path, long[] oid)` Deprecated. Not for public use in the future. Using `Datatype(FileFormat, String, String)`
`Datatype(int tid)` Constructs a Datatype with a given native datatype identifier.
`Datatype(int tclass, int tsize, int torder, int tsign)` Constructs a Datatype with specified class, size, byte order and sign.
`Datatype(int tclass, int tsize, int torder, int tsign, Datatype tbase)` Constructs a Datatype with specified class, size, byte order and sign.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract void`	`close(int id)` Closes a datatype identifier.
`abstract void`	`fromNative(int nativeID)` Set datatype characteristics (class, size, byte order and sign) from a given datatype identifier.
`long[]`	`getArrayDims()` Returns the dimensions of an Array Datatype.
`Datatype`	`getBasetype()` Returns the datatype of array elements for an ARRAY datatype.
`List<String>`	`getCompoundMemberNames()`
`List<Datatype>`	`getCompoundMemberTypes()`
`int`	`getDatatypeClass()` Returns the class of the datatype.
`String`	`getDatatypeDescription()` Returns a short text description of this datatype.
`int`	`getDatatypeOrder()` Returns the byte order of the datatype.
`int`	`getDatatypeSign()` Returns the sign (SIGN_NONE, SIGN_2 or NSGN) of an integer datatype.
`int`	`getDatatypeSize()` Returns the size of the datatype in bytes.
`String`	`getEnumMembers()` Returns the "name=value" pairs of enum members for enum datatype.
`List`	`getMetadata()` Retrieves the metadata such as attributes from file.
`abstract boolean`	`isUnsigned()` Checks if this datatype is an unsigned integer.
`boolean`	`isVLEN()` Checks if this datatype is a variable-length type.
`int`	`open()` Opens access to this named datatype.
`void`	`removeMetadata(Object info)` Deletes an existing metadata from this data object.
`void`	`setEnumMembers(String enumStr)` Sets the (name, value) pairs of enum members for enum datatype.
`abstract int`	`toNative()` Converts the datatype object to a native datatype.
`void`	`updateMetadata(Object info)` Updates an existing metadata from this data object.
`void`	`writeMetadata(Object info)` Writes a specific metadata (such as attribute) into file.

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

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface hdf.object.DataFormat
hasAttribute

- Field Detail
  - NATIVE
```
public static final int NATIVE
```
    The default definition for datatype size, order, and sign.
    
    See Also:
    
    Constant Field Values
  - CLASS_NO_CLASS
```
public static final int CLASS_NO_CLASS
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - CLASS_INTEGER
```
public static final int CLASS_INTEGER
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - CLASS_FLOAT
```
public static final int CLASS_FLOAT
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - CLASS_CHAR
```
public static final int CLASS_CHAR
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - CLASS_STRING
```
public static final int CLASS_STRING
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - CLASS_BITFIELD
```
public static final int CLASS_BITFIELD
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - CLASS_OPAQUE
```
public static final int CLASS_OPAQUE
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - CLASS_COMPOUND
```
public static final int CLASS_COMPOUND
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - CLASS_REFERENCE
```
public static final int CLASS_REFERENCE
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - CLASS_ENUM
```
public static final int CLASS_ENUM
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - CLASS_VLEN
```
public static final int CLASS_VLEN
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - CLASS_ARRAY
```
public static final int CLASS_ARRAY
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - CLASS_TIME
```
public static final int CLASS_TIME
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - ORDER_LE
```
public static final int ORDER_LE
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - ORDER_BE
```
public static final int ORDER_BE
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - ORDER_VAX
```
public static final int ORDER_VAX
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - ORDER_NONE
```
public static final int ORDER_NONE
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - SIGN_NONE
```
public static final int SIGN_NONE
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - SIGN_2
```
public static final int SIGN_2
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - NSGN
```
public static final int NSGN
```
    See HDF5 User's Guide
    
    See Also:
    
    Constant Field Values
  - datatypeClass
```
protected int datatypeClass
```
    The class of the datatype.
  - datatypeSize
```
protected int datatypeSize
```
    The size (in bytes) of the datatype.
  - datatypeOrder
```
protected int datatypeOrder
```
    The byte order of the datatype. Valid values are ORDER_LE, ORDER_BE, and ORDER_VAX.
  - datatypeSign
```
protected int datatypeSign
```
    The sign of the datatype.
  - enumMembers
```
protected String enumMembers
```
    The (name, value) pairs of enum members.
  - compoundMemberNames
```
protected List<String> compoundMemberNames
```
    The list of names of members of a compound Datatype.
  - compoundMemberTypes
```
protected List<Datatype> compoundMemberTypes
```
    The list of types of members of a compound Datatype
  - compoundMemberOffsets
```
protected List<Long> compoundMemberOffsets
```
    The list of offsets of members of a compound Datatype.
  - compoundMemberFieldIDs
```
protected List<Integer> compoundMemberFieldIDs
```
    The list of field IDs of members of a compound Datatype.
  - baseType
```
protected Datatype baseType
```
    The base datatype of every element of the array (for CLASS_ARRAY datatype).
  - dims
```
protected long[] dims
```
    The dimensions of the ARRAY element of an ARRAY datatype.
  - isVLEN
```
protected boolean isVLEN
```
    Determines whether this datatype is a variable-length type.
- Constructor Detail
  - Datatype
```
public Datatype(FileFormat theFile,
                String name,
                String path)
```
    Constructs a named datatype with a given file, name and path.
    
    Parameters:
    
    theFile - the HDF file.
    
    name - the name of the datatype, e.g "12-bit Integer".
    
    path - the full group path of the datatype, e.g. "/datatypes/".
  - Datatype
```
@Deprecated
public Datatype(FileFormat theFile,
                            String name,
                            String path,
                            long[] oid)
```
    Deprecated. Not for public use in the future.
    Using Datatype(FileFormat, String, String)
    
    Parameters:
    
    theFile - the HDF file.
    
    name - the name of the datatype, e.g "12-bit Integer".
    
    path - the full group path of the datatype, e.g. "/datatypes/".
    
    oid - the oidof the datatype.
  - Datatype
```
public Datatype(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
  - Datatype
```
public Datatype(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
  - Datatype
```
public Datatype(int tid)
```
    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:
    
    tid - the native datatype identifier.
    
    See Also:
    
    fromNative(int tid)
- Method Detail
  - getDatatypeClass
```
public int getDatatypeClass()
```
    Returns the class of the datatype. Valid values are:
    - CLASS_NO_CLASS
    - CLASS_INTEGER
    - CLASS_FLOAT
    - CLASS_CHAR
    - CLASS_STRING
    - CLASS_BITFIELD
    - CLASS_OPAQUE
    - CLASS_COMPOUND
    - CLASS_REFERENCE
    - CLASS_ENUM
    - CLASS_VLEN
    - CLASS_ARRAY
    Returns:
    
    the class of the datatype.
  - getDatatypeSize
```
public int getDatatypeSize()
```
    Returns the size of the datatype in bytes. For example, for a 32-bit integer, the size is 4 (bytes).
    
    Returns:
    
    the size of the datatype.
  - getDatatypeOrder
```
public int getDatatypeOrder()
```
    Returns the byte order of the datatype. Valid values are
    - ORDER_LE
    - ORDER_BE
    - ORDER_VAX
    - ORDER_NONE
    Returns:
    
    the byte order of the datatype.
  - getDatatypeSign
```
public int getDatatypeSign()
```
    Returns the sign (SIGN_NONE, SIGN_2 or NSGN) of an integer datatype.
    
    Returns:
    
    the sign of the datatype.
  - getBasetype
```
public Datatype getBasetype()
```
    Returns the datatype of array elements for an ARRAY datatype.
    For example, in a dataset of type ARRAY of integer, the datatype of the dataset is ARRAY. The datatype of the base type is integer.
    
    Returns:
    
    the datatype of array elements for an ARRAY datatype.
  - setEnumMembers
```
public final void setEnumMembers(String enumStr)
```
    Sets the (name, value) pairs of enum members for enum datatype.
    For Example,
    
    setEnumMembers("lowTemp=-40, highTemp=90")
    
    sets the value of enum member lowTemp to -40 and highTemp to 90.
    
    setEnumMembers("lowTemp, highTemp")
    
    sets enum members to defaults, i.e. lowTemp=0 and highTemp=1
    
    setEnumMembers("lowTemp=10, highTemp")
    
    sets enum member lowTemp to 10 and highTemp to 11.
    
    Parameters:
    
    enumStr - the (name, value) pairs of enum members
  - getEnumMembers
```
public final String getEnumMembers()
```
    Returns the "name=value" pairs of enum members for enum datatype.
    For Example,
    
    setEnumMembers("lowTemp=-40, highTemp=90")
    
    sets the value of enum member lowTemp to -40 and highTemp to 90.
    
    setEnumMembers("lowTemp, highTemp")
    
    sets enum members to defaults, i.e. lowTemp=0 and highTemp=1
    
    setEnumMembers("lowTemp=10, highTemp")
    
    sets enum member lowTemp to 10 and highTemp to 11.
    
    Returns:
    
    enumStr the (name, value) pairs of enum members
  - getArrayDims
```
public final long[] getArrayDims()
```
    Returns the dimensions of an Array Datatype.
    
    Returns:
    
    dims the dimensions of the Array Datatype
  - getCompoundMemberNames
```
public final List<String> getCompoundMemberNames()
```
  - getCompoundMemberTypes
```
public final List<Datatype> getCompoundMemberTypes()
```
  - toNative
```
public abstract int toNative()
```
    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);
 
```
    Returns:
    
    the identifier of the native datatype.
  - fromNative
```
public abstract void fromNative(int nativeID)
```
    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 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);
    Parameters:
    
    nativeID - the datatype identifier.
  - getDatatypeDescription
```
public String getDatatypeDescription()
```
    Returns a short text description of this datatype.
    
    Returns:
    
    a short text description of this datatype
  - isUnsigned
```
public abstract boolean isUnsigned()
```
    Checks if this datatype is an unsigned integer.
    
    Returns:
    
    true if the datatype is an unsigned integer; otherwise, returns false.
  - isVLEN
```
public boolean isVLEN()
```
    Checks if this datatype is a variable-length type.
    
    Returns:
    
    true if the datatype is variable-length; false otherwise
  - open
```
public int open()
```
    Opens access to this named datatype. Sub-classes must replace this default implementation. For example, in H5Datatype, open() function H5.H5Topen(loc_id, name) to get the datatype identifier.
    
    Specified by:
    
    open in class HObject
    
    Returns:
    
    the datatype identifier if successful; otherwise returns negative value.
    
    See Also:
    
    HObject.close(int)
  - close
```
public abstract void close(int id)
```
    Closes a datatype identifier.
    Sub-classes must replace this default implementation.
    
    Specified by:
    
    close in class HObject
    
    Parameters:
    
    id - the datatype identifier to close.
  - getMetadata
```
public List getMetadata()
                 throws Exception
```
    Description copied from interface: DataFormat
    
    Retrieves the metadata such as attributes from file.
    Metadata such as attributes are stored in a List.
    
    Returns:
    
    the list of metadata objects.
    
    Throws:
    
    Exception - if the metadata can not be retrieved
  - writeMetadata
```
public void writeMetadata(Object info)
                   throws 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.
    
    Parameters:
    
    info - the metadata to write.
    
    Throws:
    
    Exception - if the metadata can not be written
  - removeMetadata
```
public void removeMetadata(Object info)
                    throws Exception
```
    Description copied from interface: DataFormat
    
    Deletes an existing metadata from this data object.
    
    Parameters:
    
    info - the metadata to delete.
    
    Throws:
    
    Exception - if the metadata can not be removed
  - updateMetadata
```
public void updateMetadata(Object info)
                    throws Exception
```
    Description copied from interface: DataFormat
    
    Updates an existing metadata from this data object.
    
    Parameters:
    
    info - the metadata to update.
    
    Throws:
    
    Exception - if the metadata can not be updated

Class Datatype

Field Summary

Fields inherited from class hdf.object.HObject

Constructor Summary

Method Summary

Methods inherited from class hdf.object.HObject

Methods inherited from class Object

Methods inherited from interface hdf.object.DataFormat

Field Detail

NATIVE

CLASS_NO_CLASS

CLASS_INTEGER

CLASS_FLOAT

CLASS_CHAR

CLASS_STRING

CLASS_BITFIELD

CLASS_OPAQUE

CLASS_COMPOUND

CLASS_REFERENCE

CLASS_ENUM

CLASS_VLEN

CLASS_ARRAY

CLASS_TIME

ORDER_LE

ORDER_BE

ORDER_VAX

ORDER_NONE

SIGN_NONE

SIGN_2

NSGN

datatypeClass

datatypeSize

datatypeOrder

datatypeSign

enumMembers

compoundMemberNames

compoundMemberTypes

compoundMemberOffsets

compoundMemberFieldIDs

baseType

dims

isVLEN

Constructor Detail

Datatype

Datatype

Datatype

Datatype

Datatype

Method Detail

getDatatypeClass

getDatatypeSize

getDatatypeOrder

getDatatypeSign

getBasetype

setEnumMembers

getEnumMembers

getArrayDims

getCompoundMemberNames

getCompoundMemberTypes

toNative

fromNative

getDatatypeDescription

isUnsigned

isVLEN

open

close

getMetadata

writeMetadata

removeMetadata

updateMetadata