Object
hdf.object.HObject
hdf.object.Datatype
hdf.object.h5.H5Datatype
- All Implemented Interfaces:
MetaDataContainer
,Serializable
- Direct Known Subclasses:
H5ReferenceType
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:
-
Field Summary
Modifier and TypeFieldDescriptionprotected long[]
The dimension sizes of the reference objectFields 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, datatypeNATIVE, 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 theName, String thePath) Constructs an named HDF5 data type object for a given file, dataset name and group path.H5Datatype
(FileFormat theFile, String theName, String thePath, long[] oid) Deprecated.Not for public use in the future. -
Method Summary
Modifier and TypeMethodDescriptionstatic final Object
allocateArray
(H5Datatype dtype, int numPoints) 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
clear()
Removes all of the elements from metadata list.void
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 String
descReferenceObject
(long container, byte[] refarr) Describes the dataset object description for a 1.10 reference.static String
descRegionDataset
(long container, byte[] refarr) Describes the dataset region description for a 1.10 reference.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 final 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) Retrieves the object's metadata, such as attributes, from the file.int
Gets the string padding.long
If the datatype is a reference, then return the type.long[]
getToken()
Get the token for this object.boolean
Check if the object has any attributes attached.boolean
isRefObj()
Checks if this datatype is an object reference type.boolean
isRegRef()
Checks if this datatype is a region reference type.boolean
isStdRef()
Checks if this datatype is a standard reference type.boolean
isText()
Checks if this datatype is a boolean type.static final 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) Sets the full name of the object.void
Sets the name of the object.static long
toNative
(long tid) static int
typeObjectRef
(long container, int obj_type, byte[] refarr) Gets the dataset reference type for a 1.10 reference.void
updateMetadata
(Object info) Updates an existing piece of metadata attached to this object.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, getCompoundMemberOffsets, getCompoundMemberTypes, getDatatypeBase, getDatatypeClass, getDatatypeOrder, getDatatypeSign, getDatatypeSize, getEnumMembers, getEnumMembersAsString, isArray, isBitField, isChar, isCompound, isEnum, isFloat, isInteger, isNamed, isOpaque, isRef, isString, isUnsigned, isVarStr, isVLEN, setEnumMembers, toString
Methods inherited from class hdf.object.HObject
createFullname, debug, equals, equals, equalsOID, getFID, getFile, getFileFormat, getFullName, getLinkTargetObjName, getName, getOID, getPath, hashCode, setLinkTargetObjName, setPath
-
Field Details
-
refdims
The dimension sizes of the reference object
-
-
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.theName
- the name of the dataset such as "dset1".thePath
- 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.theName
- the name of the dataset such as "dset1".thePath
- 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 Exception 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 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:
-
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:
-
-
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). -
getToken
Get the token for this object.- Returns:
- true if it has any attributes, false otherwise.
-
hasAttribute
Check if the object has any attributes attached.- Returns:
- true if it has any attributes, false otherwise.
-
convertEnumValueToName
Converts values in an Enumeration Datatype to names. This method searches the identified enumeration datatype for the values appearing ininValues
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 emptyinValues
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 ininValues
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:
data
- The input Floatstart
- The position in the input array of BigDecimal to start- 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:
data
- The input array of bytesstart
- The position in the input array of bytes to start- 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.numPoints
- 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.
-
clear
Removes all of the elements from metadata list. The list should be empty after this call returns.- Specified by:
clear
in interfaceMetaDataContainer
- Overrides:
clear
in classDatatype
-
getMetadata
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
- if the metadata can not be retrieved
-
getMetadata
Retrieves the object's metadata, such as attributes, from the file. Metadata, such as attributes, is stored in a List.- Parameters:
attrPropList
- the list of properties to get- Returns:
- the list of metadata objects.
- Throws:
hdf.hdf5lib.exceptions.HDF5Exception
- if the metadata can not be retrieved
-
writeMetadata
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
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
- if the metadata can not be removed
-
updateMetadata
Updates an existing piece of metadata attached to this object.- Specified by:
updateMetadata
in interfaceMetaDataContainer
- Overrides:
updateMetadata
in classDatatype
- Parameters:
info
- the metadata to update.- Throws:
hdf.hdf5lib.exceptions.HDF5Exception
- if the metadata can not be updated
-
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
Description copied from class:HObject
Sets the full name of the object.- Overrides:
setFullname
in classHObject
- Parameters:
newPath
- The path of the object.newName
- The name of the object.- Throws:
Exception
- if a failure occurred
-
isText
Description copied from class:Datatype
Checks if this datatype is a boolean type. -
isRefObj
Checks if this datatype is an object reference type.- Returns:
- true if the datatype is an object reference; false otherwise
-
isRegRef
Checks if this datatype is a region reference type.- Returns:
- true if the datatype is a region reference; false otherwise
-
isStdRef
Checks if this datatype is a standard reference type.- Returns:
- true if the datatype is a standard reference; false otherwise
-
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
-
descReferenceObject
Describes the dataset object description for a 1.10 reference.- Parameters:
container
- the dataset/attribute with the referencerefarr
- the reference datatype data to be checked.- Returns:
- the dataset reference object description.
-
descRegionDataset
Describes the dataset region description for a 1.10 reference.- Parameters:
container
- the dataset/attribute with the referencerefarr
- the reference datatype data to be checked.- Returns:
- the dataset region description.
-
typeObjectRef
Gets the dataset reference type for a 1.10 reference.- Parameters:
container
- the dataset/attribute with the referencerefarr
- the reference datatype data to be checked.- Returns:
- the dataset reference type.
-
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
Gets the string padding.- Returns:
- the string padding value
-
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 asnest.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.
-