|
Introduction to HDF5 HDF5 User Guide Other HDF5 documents and links |
And in this document, the
HDF5 Reference Manual
H5 H5A H5D H5E H5F H5G H5I H5P H5R H5RA H5S H5T H5Z Tools |
|
The H5RA Interface is strictly experimental at this time;
the interface may change dramatically or support for ragged arrays
may be unavailable in future in releases. As a result, future releases
may be unable to retrieve data stored with this interface.
Do not create any archives using this interface! |
|---|
These functions enable the user to store and retrieve data in ragged arrays.
This version of the Ragged Array interface implements a
two-dimensional array where each row of the array is a different length.
It is intended for applications where the distribution of row lengths
is such that most rows are near an average length with only a few rows
that are significantly shorter or longer. The raw data is split among
two datasets, raw and over: the raw
dataset is a two-dimensional chunked dataset whose width is large enough
to hold most of the rows while the over dataset is a heap
that stores the ends of rows that overflow the first dataset.
A third dataset, called meta, contains one record for each
row and describes what elements, if any, overflow the raw
dataset and where they are stored in the over dataset.
All three datasets are contained in a single group whose name is the
name of the ragged array.
H5RAcreate(hid_t loc_id,
const char *name,
hid_t type_id,
hid_t plist_id
)
H5RAcreate creates a new ragged array with the
name specified in name. A ragged array is
implemented as a group containing three datasets.
The dataset raw is a fixed width dataset
which will hold the majority of the data.
The dataset over is a one dimensional heap
which will hold the end of rows which are too long to fit
in raw
Finally, the meta dataset contains information
about the over array. All elements of the
ragged array are stored with the same data type.
The property list plist_id should contain
information about chunking. The chunk width will determine
the width of the raw dataset while the chunk
length should be such that the total chunk size is
reasonably large since I/O will be performed in units
of chunks). If the plist_id does not have
a chunk size defined (e.g., H5P_DEFAULT)
then this function will fail.
loc_id
name
type_id
plist_id
H5RAopen(hid_t loc_id,
const char *name
)
H5RAopen opens an existing ragged array.
The name of the array, name, should be the same
that was used when the array was created, i.e., the name of
the group which implements the array.
loc_id
name
H5RAclose(hid_t array_id)
H5RAclose closes the ragged array specified
with the array identifier array_id.
array_id
H5RAwrite(hid_t array_id,
hssize_t start_row,
hsize_t nrows,
hid_t type_id,
hsize_t size[/*nrows*/],
void *buf[/*nrows*/]
)
H5RAwrite writes a contiguous set of rows to a
ragged array beginning at row number start_row
and continuing for nrows rows.
Each row of the ragged array contains size[]
elements of type type_id and each row is stored
in a buffer pointed to by buf[].
Datatype conversion takes place at the time of a read or write and is automatic. See the Data Conversion section of The Data Type Interface (H5T) in the HDF5 User's Guide for a discussion of data conversion, including the range of conversions currently supported by the HDF5 libraries.
array_id
start_row
nrows
type_id
size[/*nrows*/]
buf[/*nrows*/]
H5RAread(hid_t array_id,
hssize_t start_row,
hsize_t nrows,
hid_t type_id,
hsize_t size[/*nrows*/],
void *buf[/*nrows*/]
)
H5RAread reads the contents of one or more rows
of the ragged array pointed to by array_id.
The rows to be read begin at row start_row and
continue for nrows rows.
All raw data is converted to type type_id.
The caller must allocate the size[] and
buf[] arrays.
Memory for the data can be allocated by either the caller or
the library. In the former case, the caller should initialize
the buf[] array with pointers to valid memory and
the size[] array with the lengths of the buffers.
In the latter case, the caller should initialize
buf[] with null pointers (the input value of
size[] is irrelevant in this case) and the
library will allocate memory for each row by calling
malloc().
Datatype conversion takes place at the time of a read or write and is automatic. See the Data Conversion section of The Data Type Interface (H5T) in the HDF5 User's Guide for a discussion of data conversion, including the range of conversions currently supported by the HDF5 libraries.
array_id
start_row
nrows
type_id
size[/*nrows*/]
buf[/*nrows*/]
size[] array will be the
true length of each row. If a row is longer than the
caller-allocated length, then size[] will
contain the true length of the row although not all elements
of that row will be stored in the buffer.
Returns a negative value on failure. The buf[]
array will contain it's original pointers (null or otherwise),
although the caller-supplied buffers may have been modified.
The size[] array may also have been modified.
|
Introduction to HDF5 HDF5 User Guide Other HDF5 documents and links |
And in this document, the
HDF5 Reference Manual
H5 H5A H5D H5E H5F H5G H5I H5P H5R H5RA H5S H5T H5Z Tools |