![]() |
HDF5
1.15.0.a6e610e
API Reference
|
Creating and manipulating HDF5 datasets intended to be interpreted as tables (H5TB)
The HDF5 Table API defines a standard storage for HDF5 datasets that are intended to be interpreted as tables. A table is defined as a collection of records whose values are stored in fixed-length fields. All records have the same structure, and all values in each field have the same data type.
|
|
Functions | |
H5_HLDLL herr_t | H5TBmake_table (const char *table_title, hid_t loc_id, const char *dset_name, hsize_t nfields, hsize_t nrecords, size_t type_size, const char *field_names[], const size_t *field_offset, const hid_t *field_types, hsize_t chunk_size, void *fill_data, int compress, const void *buf) |
Creates and writes a table. More... | |
H5_HLDLL herr_t | H5TBappend_records (hid_t loc_id, const char *dset_name, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf) |
Adds records to the end of the table. More... | |
H5_HLDLL herr_t | H5TBwrite_records (hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf) |
Overwrites records. More... | |
H5_HLDLL herr_t | H5TBwrite_fields_name (hid_t loc_id, const char *dset_name, const char *field_names, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf) |
Overwrites fields. More... | |
H5_HLDLL herr_t | H5TBwrite_fields_index (hid_t loc_id, const char *dset_name, hsize_t nfields, const int *field_index, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf) |
Overwrites fields. More... | |
H5_HLDLL herr_t | H5TBread_table (hid_t loc_id, const char *dset_name, size_t dst_size, const size_t *dst_offset, const size_t *dst_sizes, void *dst_buf) |
Reads a table. More... | |
H5_HLDLL herr_t | H5TBread_fields_name (hid_t loc_id, const char *dset_name, const char *field_names, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, void *buf) |
Reads one or several fields. The fields are identified by name. More... | |
H5_HLDLL herr_t | H5TBread_fields_index (hid_t loc_id, const char *dset_name, hsize_t nfields, const int *field_index, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, void *buf) |
Reads one or several fields. The fields are identified by index. More... | |
H5_HLDLL herr_t | H5TBread_records (hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *dst_offset, const size_t *dst_sizes, void *buf) |
Reads records. More... | |
H5_HLDLL herr_t | H5TBget_table_info (hid_t loc_id, const char *dset_name, hsize_t *nfields, hsize_t *nrecords) |
Gets the table dimensions. More... | |
H5_HLDLL herr_t | H5TBget_field_info (hid_t loc_id, const char *dset_name, char *field_names[], size_t *field_sizes, size_t *field_offsets, size_t *type_size) |
Gets information about a table. More... | |
H5_HLDLL herr_t | H5TBdelete_record (hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords) |
Delete records. More... | |
H5_HLDLL herr_t | H5TBinsert_record (hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t dst_size, const size_t *dst_offset, const size_t *dst_sizes, void *buf) |
Insert records. More... | |
H5_HLDLL herr_t | H5TBadd_records_from (hid_t loc_id, const char *dset_name1, hsize_t start1, hsize_t nrecords, const char *dset_name2, hsize_t start2) |
Add records from first table to second table. More... | |
H5_HLDLL herr_t | H5TBcombine_tables (hid_t loc_id1, const char *dset_name1, hid_t loc_id2, const char *dset_name2, const char *dset_name3) |
Combines records from two tables into a third. More... | |
H5_HLDLL herr_t | H5TBinsert_field (hid_t loc_id, const char *dset_name, const char *field_name, hid_t field_type, hsize_t position, const void *fill_data, const void *buf) |
Insert a new field into a table. More... | |
H5_HLDLL herr_t | H5TBdelete_field (hid_t loc_id, const char *dset_name, const char *field_name) |
Deletes a field from a table. More... | |
H5_HLDLL herr_t | H5TBAget_title (hid_t loc_id, char *table_title) |
Reads a table's title. More... | |
H5_HLDLL htri_t | H5TBAget_fill (hid_t loc_id, const char *dset_name, hid_t dset_id, unsigned char *dst_buf) |
Reads the table attribute fill values. More... | |
H5_HLDLL herr_t H5TBadd_records_from | ( | hid_t | loc_id, |
const char * | dset_name1, | ||
hsize_t | start1, | ||
hsize_t | nrecords, | ||
const char * | dset_name2, | ||
hsize_t | start2 | ||
) |
Add records from first table to second table.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name1 | The name of the dataset to read the records |
[in] | start1 | The position to read the records from the first table |
[in] | nrecords | The number of records to read from the first table |
[in] | dset_name2 | The name of the dataset to write the records |
[in] | start2 | The position to write the records on the second table |
H5TBadd_records_from() adds records from a dataset named dset_name1
to a dataset named dset_name2
. Both tables are attached to the object specified by the identifier loc_id.
H5_HLDLL htri_t H5TBAget_fill | ( | hid_t | loc_id, |
const char * | dset_name, | ||
hid_t | dset_id, | ||
unsigned char * | dst_buf | ||
) |
Reads the table attribute fill values.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | Name of table |
[in] | dset_id | Table identifier |
[out] | dst_buf | Buffer of fill values for table fields |
H5TBget_fill() reads the table attribute fill values into the buffer dst_buf
for the table specified by dset_id
and dset_name
located in loc_id
.
Reads a table's title.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[out] | table_title | Buffer for title name |
H5TBget_title() returns the title of the table identified by loc_id
in a buffer table_title
.
H5_HLDLL herr_t H5TBappend_records | ( | hid_t | loc_id, |
const char * | dset_name, | ||
hsize_t | nrecords, | ||
size_t | type_size, | ||
const size_t * | field_offset, | ||
const size_t * | dst_sizes, | ||
const void * | buf | ||
) |
Adds records to the end of the table.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset to overwrite |
[in] | nrecords | The number of records to append |
[in] | type_size | The size of the structure type, as calculated by sizeof() . |
[in] | field_offset | An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro |
[in] | dst_sizes | An array containing the sizes of the fields |
[in] | buf | Buffer with data |
H5TBappend_records() adds records to the end of the table named dset_name
attached to the object specified by the identifier loc_id
. The dataset is extended to hold the new records.
H5_HLDLL herr_t H5TBcombine_tables | ( | hid_t | loc_id1, |
const char * | dset_name1, | ||
hid_t | loc_id2, | ||
const char * | dset_name2, | ||
const char * | dset_name3 | ||
) |
Combines records from two tables into a third.
[in] | loc_id1 | Identifier of the file or group in which the first table is located |
[in] | dset_name1 | The name of the first table to combine |
[in] | loc_id2 | Identifier of the file or group in which the second table is located |
[in] | dset_name2 | The name of the second table to combine |
[in] | dset_name3 | The name of the new table |
H5TBcombine_tables() combines records from two datasets named dset_name1
and dset_name2
, to a new table named dset_name3
. These tables can be located on different files, identified by loc_id1
and loc_id2
(identifiers obtained with H5Fcreate()). They can also be located on the same file. In this case one uses the same identifier for both parameters loc_id1
and loc_id2
. If two files are used, the third table is written in the first file.
Deletes a field from a table.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the table |
[in] | field_name | The name of the field to delete |
H5TBdelete_field() deletes a field named field_name
from the table dset_name
. Note: this function requires the table to be re-created and rewritten in its entirety, and this can result in some unused space in the file, and can also take a great deal of time if the table is large.
H5_HLDLL herr_t H5TBdelete_record | ( | hid_t | loc_id, |
const char * | dset_name, | ||
hsize_t | start, | ||
hsize_t | nrecords | ||
) |
Delete records.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset |
[in] | start | The start record to delete from |
[in] | nrecords | The number of records to delete |
H5TBdelete_record() deletes nrecords number of records starting from start
from the middle of the table dset_name
("pulling up" all the records after it).
H5_HLDLL herr_t H5TBget_field_info | ( | hid_t | loc_id, |
const char * | dset_name, | ||
char * | field_names[], | ||
size_t * | field_sizes, | ||
size_t * | field_offsets, | ||
size_t * | type_size | ||
) |
Gets information about a table.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset to read |
[out] | field_names | An array containing the names of the fields |
[out] | field_sizes | An array containing the size of the fields |
[out] | field_offsets | An array containing the offsets of the fields |
[out] | type_size | The size of the HDF5 datatype associated with the table. (More specifically, the size in bytes of the HDF5 compound datatype used to define a row, or record, in the table) |
H5TBget_field_info() gets information about a dataset named dset_name
attached to the object specified by the identifier loc_id
.
H5_HLDLL herr_t H5TBget_table_info | ( | hid_t | loc_id, |
const char * | dset_name, | ||
hsize_t * | nfields, | ||
hsize_t * | nrecords | ||
) |
Gets the table dimensions.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset to read |
[out] | nfields | The number of fields |
[out] | nrecords | The number of records |
H5TBget_table_info() retrieves the table dimensions from a dataset named dset_name
attached to the object specified by the identifier loc_id
.
H5_HLDLL herr_t H5TBinsert_field | ( | hid_t | loc_id, |
const char * | dset_name, | ||
const char * | field_name, | ||
hid_t | field_type, | ||
hsize_t | position, | ||
const void * | fill_data, | ||
const void * | buf | ||
) |
Insert a new field into a table.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the table |
[in] | field_name | The name of the field to insert |
[in] | field_type | The data type of the field |
[in] | position | The zero based index position where to insert the field |
[in] | fill_data | Fill value data for the field. This parameter can be NULL |
[in] | buf | Buffer with data |
H5TBinsert_field() inserts a new field named field_name
into the table dset_name
. Note: this function requires the table to be re-created and rewritten in its entirety, and this can result in some unused space in the file, and can also take a great deal of time if the table is large.
H5_HLDLL herr_t H5TBinsert_record | ( | hid_t | loc_id, |
const char * | dset_name, | ||
hsize_t | start, | ||
hsize_t | nrecords, | ||
size_t | dst_size, | ||
const size_t * | dst_offset, | ||
const size_t * | dst_sizes, | ||
void * | buf | ||
) |
Insert records.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset |
[in] | start | The position to insert |
[in] | nrecords | The number of records to insert |
[in] | dst_size | The size in bytes of the structure associated with the table |
[in] | dst_offset | An array containing the offsets of the fields |
[in] | dst_sizes | An array containing the size in bytes of the fields |
[in] | buf | Buffer with data |
H5TBinsert_record() inserts records into the middle of the table ("pushing down" all the records after it)
H5_HLDLL herr_t H5TBmake_table | ( | const char * | table_title, |
hid_t | loc_id, | ||
const char * | dset_name, | ||
hsize_t | nfields, | ||
hsize_t | nrecords, | ||
size_t | type_size, | ||
const char * | field_names[], | ||
const size_t * | field_offset, | ||
const hid_t * | field_types, | ||
hsize_t | chunk_size, | ||
void * | fill_data, | ||
int | compress, | ||
const void * | buf | ||
) |
Creates and writes a table.
[in] | table_title | The title of the table |
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset to create |
[in] | nfields | The number of fields |
[in] | nrecords | The number of records |
[in] | type_size | The size in bytes of the structure associated with the table; This value is obtained with sizeof() . |
[in] | field_names | An array containing the names of the fields |
[in] | field_offset | An array containing the offsets of the fields |
[in] | field_types | An array containing the type of the fields |
[in] | chunk_size | The chunk size |
[in] | fill_data | Fill values data |
[in] | compress | Flag that turns compression on or off |
[in] | buf | Buffer with data to be written to the table |
H5TBmake_table() creates and writes a dataset named dset_name
attached to the object specified by the identifier loc_id.
H5_HLDLL herr_t H5TBread_fields_index | ( | hid_t | loc_id, |
const char * | dset_name, | ||
hsize_t | nfields, | ||
const int * | field_index, | ||
hsize_t | start, | ||
hsize_t | nrecords, | ||
size_t | type_size, | ||
const size_t * | field_offset, | ||
const size_t * | dst_sizes, | ||
void * | buf | ||
) |
Reads one or several fields. The fields are identified by index.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset to read |
[in] | nfields | The number of fields to read (This parameter is also the size of the field_index array.) fields to read |
[in] | field_index | The indexes of the fields to read |
[in] | start | The start record to read from |
[in] | nrecords | The number of records to read |
[in] | type_size | The size in bytes of the structure associated with the table (This value is obtained with sizeof() ) |
[in] | field_offset | An array containing the offsets of the fields |
[in] | dst_sizes | An array containing the size in bytes of the fields |
[out] | buf | Buffer with data |
H5TBread_fields_index() reads the fields identified by field_index
from a dataset named dset_name
attached to the object specified by the identifier loc_id
.
H5_HLDLL herr_t H5TBread_fields_name | ( | hid_t | loc_id, |
const char * | dset_name, | ||
const char * | field_names, | ||
hsize_t | start, | ||
hsize_t | nrecords, | ||
size_t | type_size, | ||
const size_t * | field_offset, | ||
const size_t * | dst_sizes, | ||
void * | buf | ||
) |
Reads one or several fields. The fields are identified by name.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset to read |
[in] | field_names | An array containing the names of the fields to read |
[in] | start | The start record to read from |
[in] | nrecords | The number of records to read |
[in] | type_size | The size in bytes of the structure associated with the table (This value is obtained with sizeof() .) |
[in] | field_offset | An array containing the offsets of the fields |
[in] | dst_sizes | An array containing the size in bytes of the fields |
[out] | buf | Buffer with data |
H5TBread_fields_name() reads the fields identified by field_names
from a dataset named dset_name
attached to the object specified by the identifier loc_id
.
H5_HLDLL herr_t H5TBread_records | ( | hid_t | loc_id, |
const char * | dset_name, | ||
hsize_t | start, | ||
hsize_t | nrecords, | ||
size_t | type_size, | ||
const size_t * | dst_offset, | ||
const size_t * | dst_sizes, | ||
void * | buf | ||
) |
Reads records.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset to read |
[in] | start | The start record to read from |
[in] | nrecords | The number of records to read |
[in] | type_size | The size of the structure type, as calculated by sizeof() |
[in] | dst_offset | An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro |
[in] | dst_sizes | An array containing the size in bytes of the fields |
[out] | buf | Buffer with data |
H5TBread_records() reads some records identified from a dataset named dset_name
attached to the object specified by the identifier loc_id
.
H5_HLDLL herr_t H5TBread_table | ( | hid_t | loc_id, |
const char * | dset_name, | ||
size_t | dst_size, | ||
const size_t * | dst_offset, | ||
const size_t * | dst_sizes, | ||
void * | dst_buf | ||
) |
Reads a table.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset to read |
[in] | dst_size | The size of the structure type, as calculated by sizeof() |
[in] | dst_offset | An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro |
[in] | dst_sizes | An array containing the sizes of the fields. These sizes can be calculated with the sizeof() macro. |
[in] | dst_buf | Buffer with data |
H5TBread_table() reads a table named dset_name
attached to the object specified by the identifier loc_id
.
H5_HLDLL herr_t H5TBwrite_fields_index | ( | hid_t | loc_id, |
const char * | dset_name, | ||
hsize_t | nfields, | ||
const int * | field_index, | ||
hsize_t | start, | ||
hsize_t | nrecords, | ||
size_t | type_size, | ||
const size_t * | field_offset, | ||
const size_t * | dst_sizes, | ||
const void * | buf | ||
) |
Overwrites fields.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset to overwrite |
[in] | nfields | The number of fields to overwrite. This parameter is also the size of the field_index array. |
[in] | field_index | The indexes of the fields to write |
[in] | start | The zero based index record to start writing |
[in] | nrecords | The number of records to write |
[in] | type_size | The size of the structure type, as calculated by sizeof() . |
[in] | field_offset | An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro |
[in] | dst_sizes | An array containing the sizes of the fields |
[in] | buf | Buffer with data |
H5TBwrite_fields_index() overwrites one or several fields specified by field_index
with a buffer buf
from a dataset named dset_name
attached to the object specified by the identifier loc_id
.
H5_HLDLL herr_t H5TBwrite_fields_name | ( | hid_t | loc_id, |
const char * | dset_name, | ||
const char * | field_names, | ||
hsize_t | start, | ||
hsize_t | nrecords, | ||
size_t | type_size, | ||
const size_t * | field_offset, | ||
const size_t * | dst_sizes, | ||
const void * | buf | ||
) |
Overwrites fields.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset to overwrite |
[in] | field_names | The names of the fields to write |
[in] | start | The zero index record to start writing |
[in] | nrecords | The number of records to write |
[in] | type_size | The size of the structure type, as calculated by sizeof() . |
[in] | field_offset | An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro |
[in] | dst_sizes | An array containing the sizes of the fields |
[in] | buf | Buffer with data |
H5TBwrite_fields_name() overwrites one or several fields specified by field_names
with data in buf
from a dataset named dset_name
attached to the object specified by the identifier loc_id
.
H5_HLDLL herr_t H5TBwrite_records | ( | hid_t | loc_id, |
const char * | dset_name, | ||
hsize_t | start, | ||
hsize_t | nrecords, | ||
size_t | type_size, | ||
const size_t * | field_offset, | ||
const size_t * | dst_sizes, | ||
const void * | buf | ||
) |
Overwrites records.
[in] | loc_id | Location identifier. The identifier may be that of a file or group. |
[in] | dset_name | The name of the dataset to overwrite |
[in] | start | The zero index record to start writing |
[in] | nrecords | The number of records to write |
[in] | type_size | The size of the structure type, as calculated by sizeof() . |
[in] | field_offset | An array containing the offsets of the fields. These offsets can be calculated with the HOFFSET macro |
[in] | dst_sizes | An array containing the sizes of the fields |
[in] | buf | Buffer with data |
H5TBwrite_records() overwrites records starting at the zero index position start of the table named dset_name
attached to the object specified by the identifier loc_id
.