HDF5 C++ API Reference Manual

- Main Page
- Namespaces
- Classes
- Files
- Examples

- Class List
- Class Hierarchy
- Class Members

# H5::DataSet Class Reference

`#include <H5DataSet.h>`

Inheritance diagram for H5::DataSet:

List of all members.

## Public Member Functions
virtual void | close ()
| Closes this dataset.
void | extend (const hsize_t *size) const
| Extends a dataset with unlimited dimension.
void | fillMemBuf (const void *fill, DataType &fill_type, void *buf, DataType &buf_type, DataSpace &space)
| Fills a selection in memory with a value.
void | fillMemBuf (void *buf, DataType &buf_type, DataSpace &space)
| This is an overloaded member function, provided for convenience. It differs from the above function in that it only takes the the last three arguments.
DSetCreatPropList | getCreatePlist () const
| Gets the dataset creation property list.
haddr_t | getOffset () const
| Returns the address of this dataset in the file.
virtual DataSpace | getSpace () const
| Gets a copy of the dataspace of this dataset.
void | getSpaceStatus (H5D_space_status_t &status) const
| Determines whether space has been allocated for a dataset.
virtual hsize_t | getStorageSize () const
| Returns the amount of storage required for a dataset.
virtual size_t | getInMemDataSize () const
| Gets the size in memory of the dataset's data.
hsize_t | getVlenBufSize (DataType &type, DataSpace &space) const
| Returns the number of bytes required to store VL data.
void | read (void *buf, const DataType &mem_type, const DataSpace &mem_space=DataSpace::ALL, const DataSpace &file_space=DataSpace::ALL, const DSetMemXferPropList &xfer_plist=DSetMemXferPropList::DEFAULT) const
| Reads raw data from the specified dataset.
void | read (H5std_string &buf, const DataType &mem_type, const DataSpace &mem_space=DataSpace::ALL, const DataSpace &file_space=DataSpace::ALL, const DSetMemXferPropList &xfer_plist=DSetMemXferPropList::DEFAULT) const
| This is an overloaded member function, provided for convenience. It takes a reference to a `H5std_string` for the buffer.
void | write (const void *buf, const DataType &mem_type, const DataSpace &mem_space=DataSpace::ALL, const DataSpace &file_space=DataSpace::ALL, const DSetMemXferPropList &xfer_plist=DSetMemXferPropList::DEFAULT) const
| Writes raw data from an application buffer to a dataset.
void | write (const H5std_string &buf, const DataType &mem_type, const DataSpace &mem_space=DataSpace::ALL, const DataSpace &file_space=DataSpace::ALL, const DSetMemXferPropList &xfer_plist=DSetMemXferPropList::DEFAULT) const
| This is an overloaded member function, provided for convenience. It takes a reference to a `H5std_string` for the buffer.
int | iterateElems (void *buf, const DataType &type, const DataSpace &space, H5D_operator_t op, void *op_data=NULL)
| Iterates over all selected elements in a dataspace.
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
| DataSet (H5Object &obj, void *ref, H5R_type_t ref_type=H5R_OBJECT)
| Given a reference, ref, to an hdf5 dataset, creates a DataSet object.
| DataSet (H5File &h5file, void *ref, H5R_type_t ref_type=H5R_OBJECT)
| Given a reference, ref, to an hdf5 dataset, creates a DataSet object.
| DataSet (Attribute &attr, void *ref, H5R_type_t ref_type=H5R_OBJECT)
| Given a reference, ref, to an hdf5 dataset, creates a DataSet object.
| DataSet ()
| Default constructor: creates a stub DataSet.
| DataSet (const DataSet &original)
| Copy constructor: makes a copy of the original DataSet object.
| DataSet (const hid_t existing_id)
| Creates an DataSet object using the id of an existing dataset.
virtual hid_t | getId () const
virtual | ~DataSet ()
| Properly terminates access to this dataset.
## Static Public Member Functions
static void | vlenReclaim (const DataType &type, const DataSpace &space, const DSetMemXferPropList &xfer_plist, void *buf)
| Reclaims VL datatype memory buffers.
static void | vlenReclaim (void *buf, const DataType &type, const DataSpace &space=DataSpace::ALL, const DSetMemXferPropList &xfer_plist=DSetMemXferPropList::DEFAULT)
| Reclaims VL datatype memory buffers.
## Protected Member Functions
virtual void | p_setId (const hid_t new_id)
| Sets the identifier of this object to a new value.

## Detailed Description

Examples:

  chunks.cpp, compound.cpp, create.cpp, extend_ds.cpp, h5group.cpp, readdata.cpp, and writedata.cpp.

## Constructor & Destructor Documentation

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

Given a reference, ref, to an hdf5 dataset, creates a DataSet object.

Parameters:

  | obj | - IN: Dataset reference object is in or location of object that the dataset is located within.
  | ref | - IN: Reference pointer
  | ref_type | - IN: Reference type - default to H5R_OBJECT

Exceptions:

  | H5::DataSetIException |

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

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

Given a reference, ref, to an hdf5 dataset, creates a DataSet object.

Parameters:

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

Exceptions:

  | H5::DataSetIException |

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

Given a reference, ref, to an hdf5 dataset, creates a DataSet 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::DataSet::DataSet | ( |  | ) |

Default constructor: creates a stub DataSet.

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

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

Parameters:

  | original | - IN: DataSet instance to copy

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

Creates an DataSet object using the id of an existing dataset.

Parameters:

  | existing_id | - IN: Id of an existing dataset

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

Properly terminates access to this dataset.

## Member Function Documentation

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

Closes this dataset.

Exceptions:

  | H5::DataSetIException |

void H5::DataSet::extend | ( | const hsize_t * | size | ) | const

Extends a dataset with unlimited dimension.

Parameters:

  | size | - IN: Array containing the new magnitude of each dimension

Exceptions:

  | H5::DataSetIException |

Description
  For more information, please see the Description section in C layer Reference Manual at:

  ../RM_H5D.html::Dataset-Extend

Examples:
  extend_ds.cpp.

void H5::DataSet::fillMemBuf | ( | const void * | fill,
|  | DataType & | fill_type,
|  | void * | buf,
|  | DataType & | buf_type,
|  | DataSpace & | space |
| ) |  |  |

Fills a selection in memory with a value.

Parameters:

  | fill | - IN: Pointer to fill value to use - default NULL
  | fill_type | - IN: Datatype of the fill value
  | buf | - IN/OUT: Memory buffer to fill selection within
  | buf_type | - IN: Datatype of the elements in buffer
  | space | - IN: Dataspace describing memory buffer & containing selection to use

Exceptions:

  | H5::DataSetIException |

void H5::DataSet::fillMemBuf | ( | void * | buf,
|  | DataType & | buf_type,
|  | DataSpace & | space |
| ) |  |  |

This is an overloaded member function, provided for convenience. It differs from the above function in that it only takes the the last three arguments.

Parameters:

  | buf | - IN/OUT: Memory buffer to fill selection within
  | buf_type | - IN: Datatype of the elements in buffer
  | space | - IN: Dataspace describing memory buffer & containing selection to use

Exceptions:

  | H5::DataSetIException |

DSetCreatPropList H5::DataSet::getCreatePlist | ( |  | ) | const

Gets the dataset creation property list.

Returns:
  DSetCreatPropList instance

Exceptions:

  | H5::DataSetIException |

Examples:
  chunks.cpp.

haddr_t H5::DataSet::getOffset | ( |  | ) | const

Returns the address of this dataset in the file.

Returns:
  Address of dataset

Exceptions:

  | H5::DataSetIException |

DataSpace H5::DataSet::getSpace | ( |  | ) | const`[virtual]`

Gets a copy of the dataspace of this dataset.

Returns:
  DataSpace instance

Exceptions:

  | H5::DataSetIException |

Implements H5::AbstractDs.

Examples:
  chunks.cpp, extend_ds.cpp, and readdata.cpp.

void H5::DataSet::getSpaceStatus | ( | H5D_space_status_t & | status | ) | const

Determines whether space has been allocated for a dataset.

Parameters:

  | status | - OUT: Space allocation status

Exceptions:

  | H5::DataSetIException |

hsize_t H5::DataSet::getStorageSize | ( |  | ) | const`[virtual]`

Returns the amount of storage required for a dataset.

Returns:
  Size of the storage or 0, for no data

Exceptions:

  | H5::DataSetIException |

Implements H5::AbstractDs.

size_t H5::DataSet::getInMemDataSize | ( |  | ) | const`[virtual]`

Gets the size in memory of the dataset's data.

Returns:
  Size of data (in memory)

Exceptions:

  | H5::DataSetIException |

Implements H5::AbstractDs.

hsize_t H5::DataSet::getVlenBufSize | ( | DataType & | type,
|  | DataSpace & | space |
| ) |  |  | const

Returns the number of bytes required to store VL data.

Returns:
  Amount of storage

Exceptions:

  | H5::DataSetIException |

void H5::DataSet::vlenReclaim | ( | const DataType & | type,
|  | const DataSpace & | space,
|  | const DSetMemXferPropList & | xfer_plist,
|  | void * | buf |
| ) |  |  | `[static]`

Reclaims VL datatype memory buffers.

Parameters:

  | type | - IN: Datatype, which is the datatype stored in the buffer
  | space | - IN: Selection for the memory buffer to free the VL datatypes within
  | xfer_plist | - IN: Property list used to create the buffer
  | buf | - IN: Pointer to the buffer to be reclaimed

Exceptions:

  | H5::DataSetIException |

void H5::DataSet::vlenReclaim | ( | void * | buf,
|  | const DataType & | type,
|  | const DataSpace & | space = `DataSpace::ALL`,
|  | const DSetMemXferPropList & | xfer_plist = `DSetMemXferPropList::DEFAULT` |
| ) |  |  | `[static]`

Reclaims VL datatype memory buffers.

Parameters:

  | type | - IN: Datatype, which is the datatype stored in the buffer
  | space | - IN: Selection for the memory buffer to free the VL datatypes within
  | xfer_plist | - IN: Property list used to create the buffer
  | buf | - IN: Pointer to the buffer to be reclaimed

Exceptions:

  | H5::DataSetIException |

void H5::DataSet::read | ( | void * | buf,
|  | const DataType & | mem_type,
|  | const DataSpace & | mem_space = `DataSpace::ALL`,
|  | const DataSpace & | file_space = `DataSpace::ALL`,
|  | const DSetMemXferPropList & | xfer_plist = `DSetMemXferPropList::DEFAULT` |
| ) |  |  | const

Reads raw data from the specified dataset.

Parameters:

  | buf | - IN: Buffer for read data
  | mem_type | - IN: Memory datatype
  | mem_space | - IN: Memory dataspace
  | file_space | - IN: Dataset's dataspace in the file
  | xfer_plist | - IN: Transfer property list for this I/O operation

Exceptions:

  | H5::DataSetIException |

Description
  This function reads raw data from this dataset into the buffer buf, converting from file datatype and dataspace to memory datatype mem_type and dataspace mem_space.

Examples:
  chunks.cpp, compound.cpp, extend_ds.cpp, readdata.cpp, and writedata.cpp.

void H5::DataSet::read | ( | H5std_string & | strg,
|  | const DataType & | mem_type,
|  | const DataSpace & | mem_space = `DataSpace::ALL`,
|  | const DataSpace & | file_space = `DataSpace::ALL`,
|  | const DSetMemXferPropList & | xfer_plist = `DSetMemXferPropList::DEFAULT` |
| ) |  |  | const

This is an overloaded member function, provided for convenience. It takes a reference to a `H5std_string` for the buffer.

Parameters:

  | buf | - IN: Buffer for read data
  | mem_type | - IN: Memory datatype
  | mem_space | - IN: Memory dataspace
  | file_space | - IN: Dataset's dataspace in the file
  | xfer_plist | - IN: Transfer property list for this I/O operation

Exceptions:

  | H5::DataSetIException |

void H5::DataSet::write | ( | const void * | buf,
|  | const DataType & | mem_type,
|  | const DataSpace & | mem_space = `DataSpace::ALL`,
|  | const DataSpace & | file_space = `DataSpace::ALL`,
|  | const DSetMemXferPropList & | xfer_plist = `DSetMemXferPropList::DEFAULT` |
| ) |  |  | const

Writes raw data from an application buffer to a dataset.

Parameters:

  | buf | - IN: Buffer containing data to be written
  | mem_type | - IN: Memory datatype
  | mem_space | - IN: Memory dataspace
  | file_space | - IN: Dataset's dataspace in the file
  | xfer_plist | - IN: Transfer property list for this I/O operation

Exceptions:

  | H5::DataSetIException |

Description
  This function writes raw data from an application buffer buf to a dataset, converting from memory datatype mem_type and dataspace mem_space to file datatype and dataspace.

Examples:
  compound.cpp, create.cpp, extend_ds.cpp, and writedata.cpp.

void H5::DataSet::write | ( | const H5std_string & | buf,
|  | const DataType & | mem_type,
|  | const DataSpace & | mem_space = `DataSpace::ALL`,
|  | const DataSpace & | file_space = `DataSpace::ALL`,
|  | const DSetMemXferPropList & | xfer_plist = `DSetMemXferPropList::DEFAULT` |
| ) |  |  | const

This is an overloaded member function, provided for convenience. It takes a reference to a `H5std_string` for the buffer.

int H5::DataSet::iterateElems | ( | void * | buf,
|  | const DataType & | type,
|  | const DataSpace & | space,
|  | H5D_operator_t | op,
|  | void * | op_data = `NULL` |
| ) |  |  |

Iterates over all selected elements in a dataspace.

Parameters:

  | buf | - IN/OUT: Pointer to the buffer in memory containing the elements to iterate over
  | type | - IN: Datatype for the elements stored in buf
  | space | - IN: Dataspace for buf. Also contains the selection to iterate over.
  | op | - IN: Function pointer to the routine to be called for each element in buf iterated over
  | op_data | - IN/OUT: Pointer to any user-defined data associated with the operation

Exceptions:

  | H5::DataSetIException |

Note:
  This function may not work correctly yet - it's still under development.

H5G_obj_t H5::DataSet::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::DataSet::getRegion | ( | void * | ref,
|  | H5R_type_t | ref_type = `H5R_DATASET_REGION` |
| ) |  |  | const

Retrieves a dataspace with the region pointed to selected.

Parameters:

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

Returns:
  DataSpace instance

Exceptions:

  | H5::DataSetIException |

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

Implements H5::AbstractDs.

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

Implements H5::IdComponent.

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

Sets the identifier of this object to a new value.

Exceptions:

  | H5::DataSetIException | when the attempt to close the currently open dataset fails