- All Implemented Interfaces:
MetaDataContainer,Serializable
public class H5Datatype extends Datatype
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_NONEFields 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 ObjectallocateArray(H5Datatype dtype, int nPoints)Allocates a one-dimensional array of byte, short, int, long, float, double, or String to store data in memory.voidclose(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.longcreateCompoundFieldType(String memberName)Creates a datatype of a compound with one field.longcreateNative()Converts the datatype object to a native datatype.static voidextractCompoundInfo(H5Datatype dtype, String name, List<String> names, List<Datatype> flatListTypes)Extracts compound information into flat structure.voidfromNative(long tid)Set datatype characteristics (class, size, byte order and sign) from a given datatype identifier.static longgetDatatypeSize(long tid)Returns the size (in bytes) of a given datatype identifier.StringgetDescription()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)intgetNativeStrPad()booleanhasAttribute()Check if the object has any attributes attached.booleanisRefObj()booleanisRegRef()booleanisText()static booleanisUnsigned(long tid)Checks if a datatype specified by the identifier is an unsigned integer.longopen()Opens access to a named datatype.voidremoveMetadata(Object info)Deletes an existing piece of metadata from this object.voidsetFullname(String newPath, String newName)voidsetName(String newName)Sets the name of the object.static longtoNative(long tid)voidwriteMetadata(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, updateMetadataMethods inherited from class hdf.object.HObject
createFullname, debug, equals, equals, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, hashCode, setLinkTargetObjName, setPathMethods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
-
Constructor Details
-
H5Datatype
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.Not for public use in the future.
UsingH5Datatype(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
Constructs a Datatype with specified class, size, byte order and sign.The following is a list of a few examples of H5Datatype.
- to create unsigned native integer
H5Datatype type = new H5Dataype(Datatype.CLASS_INTEGER, Datatype.NATIVE, Datatype.NATIVE, Datatype.SIGN_NONE); - to create 16-bit signed integer with big endian
H5Datatype type = new H5Dataype(Datatype.CLASS_INTEGER, 2, Datatype.ORDER_BE, Datatype.NATIVE); - to create native float
H5Datatype type = new H5Dataype(Datatype.CLASS_FLOAT, Datatype.NATIVE, Datatype.NATIVE, Datatype.NATIVE); - 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
- to create unsigned native integer
-
H5Datatype
Constructs a Datatype with specified class, size, byte order and sign.The following is a list of a few examples of H5Datatype.
- to create unsigned native integer
H5Datatype type = new H5Dataype(Datatype.CLASS_INTEGER, Datatype.NATIVE, Datatype.NATIVE, Datatype.SIGN_NONE); - to create 16-bit signed integer with big endian
H5Datatype type = new H5Dataype(Datatype.CLASS_INTEGER, 2, Datatype.ORDER_BE, Datatype.NATIVE); - to create native float
H5Datatype type = new H5Dataype(Datatype.CLASS_FLOAT, Datatype.NATIVE, Datatype.NATIVE, Datatype.NATIVE); - 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
- to create unsigned native integer
-
H5Datatype
public H5Datatype(int tclass, int tsize, int torder, int tsign, Datatype tbase, Datatype pbase) throws ExceptionConstructs a Datatype with specified class, size, byte order and sign.The following is a list of a few examples of H5Datatype.
- to create unsigned native integer
H5Datatype type = new H5Dataype(Datatype.CLASS_INTEGER, Datatype.NATIVE, Datatype.NATIVE, Datatype.SIGN_NONE); - to create 16-bit signed integer with big endian
H5Datatype type = new H5Dataype(Datatype.CLASS_INTEGER, 2, Datatype.ORDER_BE, Datatype.NATIVE); - to create native float
H5Datatype type = new H5Dataype(Datatype.CLASS_FLOAT, Datatype.NATIVE, Datatype.NATIVE, Datatype.NATIVE); - 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 datatypepbase- the parent datatype of the new datatype- Throws:
Exception- if there is an error
- to create unsigned native integer
-
H5Datatype
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
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
Opens access to a named datatype.It calls H5.H5Topen(loc, name).
-
close
Closes a datatype identifier.It calls H5.H5close(tid).
-
hasAttribute
Description copied from interface:MetaDataContainerCheck 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.HDF5ExceptionConverts values in an Enumeration Datatype to names.This method searches the identified enumeration datatype for the values appearing in
inValuesand 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
inValuesparameter 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
Converts names in an Enumeration Datatype to values.This method searches the identified enumeration datatype for the names appearing in
inValuesand 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
Description copied from class:DatatypeSet 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:
fromNativein classDatatype- Parameters:
tid- the datatype identifier.
-
toNative
- Parameters:
tid- the datatype identification disk.- Returns:
- the memory datatype identifier if successful, and negative otherwise.
-
createNative
Description copied from class:DatatypeConverts 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 toint tid = H5.H5Tcopy(HDF5Constants.H5T_NATIVE_UNINT32);
- Specified by:
createNativein classDatatype- Returns:
- the identifier of the native datatype.
-
allocateArray
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
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
Description copied from class:DatatypeReturns a short text description of this datatype.- Overrides:
getDescriptionin classDatatype- Returns:
- a short text description of this datatype
-
isUnsigned
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
Description copied from interface:MetaDataContainerRetrieves the object's metadata, such as attributes, from the file.Metadata, such as attributes, is stored in a List.
- Specified by:
getMetadatain interfaceMetaDataContainer- Overrides:
getMetadatain classDatatype- 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
Description copied from interface:MetaDataContainerWrites 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:
writeMetadatain interfaceMetaDataContainer- Overrides:
writeMetadatain classDatatype- Parameters:
info- the metadata to write.- Throws:
Exception- if the metadata can not be written
-
removeMetadata
Description copied from interface:MetaDataContainerDeletes an existing piece of metadata from this object.- Specified by:
removeMetadatain interfaceMetaDataContainer- Overrides:
removeMetadatain classDatatype- Parameters:
info- the metadata to delete.- Throws:
hdf.hdf5lib.exceptions.HDF5Exception
-
setName
Description copied from class:HObjectSets the name of the object. setName (String newName) changes the name of the object in the file. -
setFullname
- Overrides:
setFullnamein classHObject- Throws:
Exception
-
isText
-
isRefObj
-
isRegRef
-
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 fromname- the name of the compound datatypenames- the list to store the member names of the compound datatypeflatListTypes- the list to store the nested member names of the compound datatype
-
createCompoundFieldType
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.
-