- All Implemented Interfaces:
MetaDataContainer
,Serializable
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
ConstructorDescriptionH5Datatype(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 TypeMethodDescriptionstatic 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.byte[]
bigDecimalToByte(int start, int len, BigDecimal[] data)
Convert from an array of BigDecimal into an array of bytesbyte[]
bigDecimalToByte(BigDecimal[] data, int start)
Convert from a single BigDecimal object from an array of BigDecimal into an array of bytesbyteToBigDecimal(byte[] data, int start)
Convert 4 bytes from an array of bytes into a single BigDecimalbyteToBigDecimal(int start, int len, byte[] data)
Convert a range from an array of bytes into an array of BigDecimalvoid
close(long tid)
Closes a datatype identifier.byte[]
Convert a BigDecimal to a byte array .convertByteToBigDecimal(byte[] raw)
Convert byte array data to a BigDecimal.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
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.Returns a short text description of this datatype.Retrieves the object's metadata, such as attributes, from the file.getMetadata(int... attrPropList)
int
long
If the datatype is a reference, then return the type.boolean
Check if the object has any attributes attached.boolean
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
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.static boolean
zeroArrayCheck(byte[] refarr)
Checks if a reference datatype is all zero.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
-
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: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.HDF5ExceptionConverts 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
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
Convert from an array of BigDecimal into an array of bytes- Parameters:
start
- The position in the input array of BigDecimal to startlen
- The number of 'BigDecimal' to convertdata
- The input array of BigDecimal- Returns:
- an array of bytes
-
bigDecimalToByte
Convert from a single BigDecimal object from an array of BigDecimal into an array of bytes- Parameters:
start
- The position in the input array of BigDecimal to startdata
- The input Float- Returns:
- an array of bytes
-
convertBigDecimalToByte
Convert a BigDecimal to a byte array .- Parameters:
num
- The BigDecimal number to convert- Returns:
- A byte array representing the BigDecimal.
-
byteToBigDecimal
Convert a range from an array of bytes into an array of BigDecimal- Parameters:
start
- The position in the input array of bytes to startlen
- The number of 'BigDecimal' to convertdata
- The input array of bytes- Returns:
- an array of 'len' BigDecimal
-
byteToBigDecimal
Convert 4 bytes from an array of bytes into a single BigDecimal- Parameters:
start
- The position in the input array of bytes to startdata
- The input array of bytes- Returns:
- The BigDecimal value of the bytes.
-
convertByteToBigDecimal
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
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 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: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 toint tid = H5.H5Tcopy(HDF5Constants.H5T_NATIVE_UNINT32);
- Specified by:
createNative
in 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:Datatype
Returns a short text description of this datatype.- Overrides:
getDescription
in 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: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 interfaceMetaDataContainer
- Overrides:
getMetadata
in 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: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 interfaceMetaDataContainer
- Overrides:
writeMetadata
in classDatatype
- Parameters:
info
- the metadata to write.- Throws:
Exception
- if the metadata can not be written
-
removeMetadata
Description copied from interface:MetaDataContainer
Deletes an existing piece of metadata from this object.- Specified by:
removeMetadata
in interfaceMetaDataContainer
- Overrides:
removeMetadata
in classDatatype
- Parameters:
info
- the metadata to delete.- Throws:
hdf.hdf5lib.exceptions.HDF5Exception
-
setName
Description copied from class:HObject
Sets the name of the object. setName (String newName) changes the name of the object in the file. -
setFullname
- Overrides:
setFullname
in classHObject
- Throws:
Exception
-
isText
-
isRefObj
-
isRegRef
-
isReference
-
getReferenceType
Description copied from class:Datatype
If the datatype is a reference, then return the type.- Overrides:
getReferenceType
in classDatatype
- Returns:
- the datatype reference type if successful; otherwise returns negative value.
- Throws:
hdf.hdf5lib.exceptions.HDF5Exception
-
zeroArrayCheck
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
-
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.
-