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

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, isNamed, isVariableStr, isVLEN, 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	Description
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(FileFormat theFile, long nativeID)	Constructs a Datatype with a given native datatype identifier.
H5Datatype(FileFormat theFile, long nativeID, Datatype pbase)	Constructs a Datatype with a given native datatype identifier.
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.

Method Summary

Modifier and Type	Method	Description
static Object	allocateArray(H5Datatype dtype, int nPoints)	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 memberName)	Creates a datatype of a compound with one field.
long	createNative()	Converts the datatype object to a native datatype.
static void	extractCompoundInfo(H5Datatype dtype, 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	setFullname(String newPath, String newName)
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, isNamed, isOpaque, isRef, isString, isUnsigned, isVarStr, isVLEN, setEnumMembers, toString, updateMetadata

Methods inherited from class hdf.object.HObject

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

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details

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 datatype.

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 datatype.

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)
           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:

fromNative(long nativeID)

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:

fromNative(long nativeID)

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

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 static final Object allocateArray(H5Datatype dtype,
int nPoints)
                                  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.

nPoints - 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

setFullname

public void setFullname(String newPath,
String newName)
                 throws Exception

Overrides:

setFullname in class HObject

Throws:

Exception

isText

public boolean isText()

Specified by:

isText in class Datatype

isRefObj

public boolean isRefObj()

isRegRef

public boolean isRegRef()

getNativeStrPad

public int getNativeStrPad()

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.