HDF5 C++ API Reference Manual

- Main Page
- Namespaces
- Classes
- Files
- Examples

- Class List
- Class Hierarchy
- Class Members

# H5::DataType Class Reference

`#include <H5DataType.h>`

Inheritance diagram for H5::DataType:

List of all members.

## Public Member Functions
| DataType (const H5T_class_t type_class, size_t size)
| Creates a object given its class and size.
| DataType (const DataType &original)
| Copy constructor: makes a copy of the original DataType object.
| DataType (H5Object &obj, void *ref, H5R_type_t ref_type=H5R_OBJECT)
| Given a reference, ref, to an hdf5 group, creates a DataType object.
| DataType (H5File &h5file, void *ref, H5R_type_t ref_type=H5R_OBJECT)
| Given a reference, ref, to an hdf5 group, creates a DataType object.
| DataType (Attribute &attr, void *ref, H5R_type_t ref_type=H5R_OBJECT)
| Given a reference, ref, to an hdf5 group, creates a DataType object.
virtual void | close ()
| Closes the datatype if it is not a predefined type.
void | copy (const DataType &like_type)
| Copies an existing datatype to this datatype object.
void | copy (const DataSet &dset)
| Copies the datatype of the given dataset to this datatype object.
H5T_class_t | getClass () const
| Returns the datatype class identifier.
void | commit (H5File &loc, const char *name)
| Commits a transient datatype to a file, creating a new named datatype.
void | commit (H5File &loc, const H5std_string &name)
| This is an overloaded member function, provided for convenience. It differs from the above function only in the type of the argument name.
void | commit (H5Object &loc, const char *name)
| Commits a transient datatype to a file, creating a new named datatype.
void | commit (H5Object &loc, const H5std_string &name)
| This is an overloaded member function, provided for convenience. It differs from the above function only in the type of the argument name.
bool | committed () const
| Determines whether a datatype is a named type or a transient type.
H5T_conv_t | find (const DataType &dest, H5T_cdata_t **pcdata) const
| Finds a conversion function that can handle a conversion from this datatype to the specified datatype, dest.
void | convert (const DataType &dest, size_t nelmts, void *buf, void *background, const PropList &plist=PropList::DEFAULT) const
| Converts data from this datatype to the specified datatypes.
DataType & | operator= (const DataType &rhs)
| Assignment operator.
bool | operator== (const DataType &compared_type) const
| Compares this DataType against the given one to determines whether the two objects refer to the same actual datatype.
void | lock () const
| Locks a datatype, making it read-only and non-destructible.
H5T_overflow_t | getOverflow (void) const
| Returns a pointer to the current global overflow function.
void | setOverflow (H5T_overflow_t func) const
| Sets the overflow handler to a specified function.
size_t | getSize () const
| Returns the size of a datatype.
DataType | getSuper () const
| Returns the base datatype from which a datatype is derived.
void | registerFunc (H5T_pers_t pers, const char *name, const DataType &dest, H5T_conv_t func) const
| Registers the specified conversion function.
void | registerFunc (H5T_pers_t pers, const H5std_string &name, const DataType &dest, H5T_conv_t func) const
| This is an overloaded member function, provided for convenience. It differs from the above function only in the type of the argument name.
void | unregister (H5T_pers_t pers, const char *name, const DataType &dest, H5T_conv_t func) const
| Removes a conversion function from all conversion paths.
void | unregister (H5T_pers_t pers, const H5std_string &name, const DataType &dest, H5T_conv_t func) const
| This is an overloaded member function, provided for convenience. It differs from the above function only in the type of the argument name.
void | setTag (const char *tag) const
| Tags an opaque datatype.
void | setTag (const H5std_string &tag) const
| This is an overloaded member function, provided for convenience. It differs from the above function only in the type of the argument name.
H5std_string | getTag () const
| Gets the tag associated with an opaque datatype.
bool | detectClass (H5T_class_t cls) const
| Checks whether a datatype contains (or is) a certain type of datatype.
bool | isVariableStr () const
| Check whether this datatype is a variable-length string.
H5G_obj_t | getObjType (void *ref, H5R_type_t ref_type=H5R_OBJECT) const
| This function was misnamed and will be deprecated in favor of H5Object::getRefObjType; please use getRefObjType instead.
DataSpace | getRegion (void *ref, H5R_type_t ref_type=H5R_DATASET_REGION) const
| Retrieves a dataspace with the region pointed to selected.
virtual H5std_string | fromClass () const
| DataType (const hid_t type_id)
| Creates a datatype using an existing datatype's id.
| DataType ()
| Default constructor: Creates a stub datatype.
virtual hid_t | getId () const
virtual | ~DataType ()
| Properly terminates access to this datatype.
## Protected Member Functions
virtual void | p_setId (const hid_t new_id)
| Sets the identifier of this datatype to a new value.
## Protected Attributes
hid_t | id

## Constructor & Destructor Documentation

H5::DataType::DataType | ( | const H5T_class_t | type_class,
|  | size_t | size |
| ) |  |  |

Creates a object given its class and size.

Parameters:

  | type_class | - IN: Class of datatype to create
  | size | - IN: Number of bytes in the datatype to create

Exceptions:

  | H5::DataTypeIException |

H5::DataType::DataType | ( | const DataType & | original | ) |

Copy constructor: makes a copy of the original DataType object.

H5::DataType::DataType | ( | H5Object & | obj,
|  | void * | ref,
|  | H5R_type_t | ref_type = `H5R_OBJECT` |
| ) |  |  |

Given a reference, ref, to an hdf5 group, creates a DataType object.

Parameters:

  | obj | - IN: Specifying location referenced object is in
  | ref | - IN: Reference pointer
  | ref_type | - IN: Reference type - default to H5R_OBJECT

Exceptions:

  | H5::ReferenceException |

Description
  `obj` can be DataSet, Group, or named DataType, that is a datatype that has been named by DataType::commit.

H5::DataType::DataType | ( | H5File & | h5file,
|  | void * | ref,
|  | H5R_type_t | ref_type = `H5R_OBJECT` |
| ) |  |  |

Given a reference, ref, to an hdf5 group, creates a DataType object.

Parameters:

  | h5file | - IN: Location referenced object is in
  | ref | - IN: Reference pointer
  | ref_type | - IN: Reference type - default to H5R_OBJECT

Exceptions:

  | H5::ReferenceException |

H5::DataType::DataType | ( | Attribute & | attr,
|  | void * | ref,
|  | H5R_type_t | ref_type = `H5R_OBJECT` |
| ) |  |  |

Given a reference, ref, to an hdf5 group, creates a DataType object.

Parameters:

  | attr | - IN: Specifying location where the referenced object is in
  | ref | - IN: Reference pointer
  | ref_type | - IN: Reference type - default to H5R_OBJECT

Exceptions:

  | H5::ReferenceException |

H5::DataType::DataType | ( | const hid_t | existing_id | ) |

Creates a datatype using an existing datatype's id.

Parameters:

  | existing_id | - IN: Id of the existing datatype

H5::DataType::DataType | ( |  | ) |

Default constructor: Creates a stub datatype.

H5::DataType::~DataType | ( |  | ) | `[virtual]`

Properly terminates access to this datatype.

## Member Function Documentation

void H5::DataType::close | ( |  | ) | `[virtual]`

Closes the datatype if it is not a predefined type.

Exceptions:

  | H5::DataTypeIException |

void H5::DataType::copy | ( | const DataType & | like_type | ) |

Copies an existing datatype to this datatype object.

Parameters:

  | like_type | - IN: Datatype to be copied

Exceptions:

  | H5::DataTypeIException |

void H5::DataType::copy | ( | const DataSet & | dset | ) |

Copies the datatype of the given dataset to this datatype object.

Description
  The resulted dataset will be transient and modifiable.

H5T_class_t H5::DataType::getClass | ( |  | ) | const

Returns the datatype class identifier.

Returns:
  Datatype class identifier

Exceptions:

  | H5::DataTypeIException |

void H5::DataType::commit | ( | H5File & | loc,
|  | const char * | name |
| ) |  |  |

Commits a transient datatype to a file, creating a new named datatype.

Parameters:

  | loc | - IN: A file
  | name | - IN: Name of the datatype

Exceptions:

  | H5::DataTypeIException |

void H5::DataType::commit | ( | H5File & | loc,
|  | const H5std_string & | name |
| ) |  |  |

This is an overloaded member function, provided for convenience. It differs from the above function only in the type of the argument name.

void H5::DataType::commit | ( | H5Object & | loc,
|  | const char * | name |
| ) |  |  |

Commits a transient datatype to a file, creating a new named datatype.

Parameters:

  | loc | - IN: Either a group, dataset, named datatype, or attribute.
  | name | - IN: Name of the datatype

Exceptions:

  | H5::DataTypeIException |

void H5::DataType::commit | ( | H5Object & | loc,
|  | const H5std_string & | name |
| ) |  |  |

This is an overloaded member function, provided for convenience. It differs from the above function only in the type of the argument name.

bool H5::DataType::committed | ( |  | ) | const

Determines whether a datatype is a named type or a transient type.

Returns:
  `true` if the datatype is a named type, and `false`, otherwise.

Exceptions:

  | H5::DataTypeIException |

H5T_conv_t H5::DataType::find | ( | const DataType & | dest,
|  | H5T_cdata_t ** | pcdata |
| ) |  |  | const

Finds a conversion function that can handle a conversion from this datatype to the specified datatype, dest.

Parameters:

  | dest | - IN: Destination datatype
  | pcdata | - IN: Pointer to type conversion data

Returns:
  Pointer to a suitable conversion function

Exceptions:

  | H5::DataTypeIException |

void H5::DataType::convert | ( | const DataType & | dest,
|  | size_t | nelmts,
|  | void * | buf,
|  | void * | background,
|  | const PropList & | plist = `PropList::DEFAULT` |
| ) |  |  | const

Converts data from this datatype to the specified datatypes.

Parameters:

  | dest | - IN: Destination datatype
  | nelmts | - IN: Size of array buf
  | buf | - IN/OUT: Array containing pre- and post-conversion values
  | background | - IN: Optional backgroud buffer
  | plist | - IN: Dataset transfer property list

Returns:
  Pointer to a suitable conversion function

Exceptions:

  | H5::DataTypeIException |

DataType & H5::DataType::operator= | ( | const DataType & | rhs | ) |

Assignment operator.

Parameters:

  | rhs | - IN: Reference to the existing datatype

Returns:
  Reference to DataType instance

Exceptions:

  | H5::DataTypeIException |

bool H5::DataType::operator== | ( | const DataType & | compared_type | ) | const

Compares this DataType against the given one to determines whether the two objects refer to the same actual datatype.

Parameters:

  | compared_type | - IN: Reference to the datatype to compare

Returns:
  true if the datatypes are equal, and false, otherwise.

Exceptions:

  | H5::DataTypeIException |

void H5::DataType::lock | ( |  | ) | const

Locks a datatype, making it read-only and non-destructible.

Exceptions:

  | H5::DataTypeIException |

Descrition
  This is normally done by the library for predefined data types so the application doesn't inadvertently change or delete a predefined type.

Once a data type is locked it can never be unlocked unless the entire library is closed.

H5T_overflow_t H5::DataType::getOverflow | ( | void |  | ) | const

Returns a pointer to the current global overflow function.

Returns:
  Pointer to an application-defined function if successful; otherwise returns NULL; this can happen if no overflow handling function is registered.

Exceptions:

  | H5::DataTypeIException |

void H5::DataType::setOverflow | ( | H5T_overflow_t | func | ) | const

Sets the overflow handler to a specified function.

Parameters:

  | func | - IN: Function to be called when overflow occurs

Returns:
  Pointer to a suitable conversion function

Exceptions:

  | H5::DataTypeIException |

Description
  The function specified by func will be called for all data type conversions that result in an overflow. For more information, please see: ../RM_H5T.html::Datatype-SetOverflow

size_t H5::DataType::getSize | ( |  | ) | const

Returns the size of a datatype.

Returns:
  Datatype size in bytes

Exceptions:

  | H5::DataTypeIException |

Examples:
  readdata.cpp.

DataType H5::DataType::getSuper | ( |  | ) | const

Returns the base datatype from which a datatype is derived.

Returns:
  DataType object

Exceptions:

  | H5::DataTypeIException |

void H5::DataType::registerFunc | ( | H5T_pers_t | pers,
|  | const char * | name,
|  | const DataType & | dest,
|  | H5T_conv_t | func |
| ) |  |  | const

Registers the specified conversion function.

Parameters:

  | pers | - IN: Conversion option `H5T_PERS_HARD` for hard conversion functions `H5T_PERS_SOFT` for soft conversion functions.
  | name | - IN: Name displayed in diagnostic output.
  | dest | - IN: Destination datatype.
  | func | - IN: Function to convert between source and destination datatypes.

Exceptions:

  | H5::DataTypeIException |

Description
  For more information, please see: ../RM_H5T.html::Datatype-Register

void H5::DataType::registerFunc | ( | H5T_pers_t | pers,
|  | const H5std_string & | name,
|  | const DataType & | dest,
|  | H5T_conv_t | func |
| ) |  |  | const

This is an overloaded member function, provided for convenience. It differs from the above function only in the type of the argument name.

void H5::DataType::unregister | ( | H5T_pers_t | pers,
|  | const char * | name,
|  | const DataType & | dest,
|  | H5T_conv_t | func |
| ) |  |  | const

Removes a conversion function from all conversion paths.

Parameters:

  | pers | - IN: Conversion option `H5T_PERS_HARD` for hard conversion functions `H5T_PERS_SOFT` for soft conversion functions.
  | name | - IN: Name displayed in diagnostic output.
  | dest | - IN: Destination datatype.
  | func | - IN: Function to convert between source and destination datatypes.

Exceptions:

  | H5::DataTypeIException |

void H5::DataType::unregister | ( | H5T_pers_t | pers,
|  | const H5std_string & | name,
|  | const DataType & | dest,
|  | H5T_conv_t | func |
| ) |  |  | const

This is an overloaded member function, provided for convenience. It differs from the above function only in the type of the argument name.

void H5::DataType::setTag | ( | const char * | tag | ) | const

Tags an opaque datatype.

Parameters:

  | tag | - IN: Descriptive ASCII string with which the opaque datatype is to be tagged.

Exceptions:

  | H5::DataTypeIException |

void H5::DataType::setTag | ( | const H5std_string & | tag | ) | const

This is an overloaded member function, provided for convenience. It differs from the above function only in the type of the argument name.

H5std_string H5::DataType::getTag | ( |  | ) | const

Gets the tag associated with an opaque datatype.

Returns:
  Tag associated with the opaque datatype

Exceptions:

  | H5::DataTypeIException |

bool H5::DataType::detectClass | ( | H5T_class_t | cls | ) | const

Checks whether a datatype contains (or is) a certain type of datatype.

Returns:
  true if this datatype contains or is the specified type, and false, otherwise.

Exceptions:

  | H5::DataTypeIException |

bool H5::DataType::isVariableStr | ( |  | ) | const

Check whether this datatype is a variable-length string.

Returns:
  true if this datatype is a variable-length string, and false, otherwise.

Exceptions:

  | H5::DataTypeIException |

H5G_obj_t H5::DataType::getObjType | ( | void * | ref,
|  | H5R_type_t | ref_type = `H5R_OBJECT` |
| ) |  |  | const

This function was misnamed and will be deprecated in favor of H5Object::getRefObjType; please use getRefObjType instead.

DataSpace H5::DataType::getRegion | ( | void * | ref,
|  | H5R_type_t | ref_type = `H5R_DATASET_REGION` |
| ) |  |  | const

Retrieves a dataspace with the region pointed to selected.

Parameters:

  | ref | - IN: Reference to get region of
  | ref_type | - IN: Type of reference to get region of - default

Returns:
  DataSpace instance

Exceptions:

  | H5::DataTypeIException |

virtual H5std_string H5::DataType::fromClass | ( |  | ) | const`[inline, virtual]`

Reimplemented in H5::ArrayType, H5::AtomType, H5::CompType, H5::EnumType, H5::FloatType, H5::IntType, H5::PredType, H5::StrType, and H5::VarLenType.

hid_t H5::DataType::getId | ( |  | ) | const`[virtual]`

Implements H5::IdComponent.

void H5::DataType::p_setId | ( | const hid_t | new_id | ) | `[protected, virtual]`

Sets the identifier of this datatype to a new value.

Exceptions:

  | H5::IdComponentException | when the attempt to close the currently open datatype fails

## Member Data Documentation

hid_t H5::DataType::id`[protected]`