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   Datatypes  

H5RA: Ragged Array Interface

Ragged Array API Functions

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.

Use these functions at your own risk!
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.


Name: H5RAcreate
Signature:
hid_t H5RAcreate(hid_t loc_id, const char *name, hid_t type_id, hid_t plist_id )
Purpose:
Creates a ragged array.
Description:
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.

Parameters:
hid_t loc_id
Location identifier of the dataset.
const char *name
The assigned name of the data set to be stored in the ragged array.
hid_t type_id
Data type identifier for the ragged array data.
hid_t plist_id
Property list of the dataset.
Returns:
Returns a ragged array identifier if successful; otherwise returns a negative value.

Name: H5RAopen
Signature:
hid_t H5RAopen(hid_t loc_id, const char *name )
Purpose:
Opens a ragged array.
Description:
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.

Parameters:
hid_t loc_id
The location identifier of the dataset.
const char *name
The name of the ragged array.
Returns:
Returns a ragged array identifier if successful; otherwise returns a negative value.

Name: H5RAclose
Signature:
herr_t H5RAclose(hid_t array_id)
Purpose:
Closes a ragged array.
Description:
H5RAclose closes the ragged array specified with the array identifier array_id.
Parameters:
hid_t array_id
The array identifier for the ragged array to be closed.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5RAwrite
Signature:
herr_t H5RAwrite(hid_t array_id, hssize_t start_row, hsize_t nrows, hid_t type_id, hsize_t size[/*nrows*/], void *buf[/*nrows*/] )
Purpose:
Writes to a ragged array.
Description:
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.

Parameters:
hid_t array_id
Array identifier for the ragged array to be written to.
hssize_t start_row
Row at which the write will start.
hsize_t nrows
Number of rows to be written
hid_t type_id
Data type identifier for the data to be written.
hsize_t size[/*nrows*/]
Lengths of the rows to be written.
void *buf[/*nrows*/]
Pointers to buffers containing the data to be written.
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5RAread
Signature:
herr_t H5RAread(hid_t array_id, hssize_t start_row, hsize_t nrows, hid_t type_id, hsize_t size[/*nrows*/], void *buf[/*nrows*/] )
Purpose:
Description:
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.

Parameters:
hid_t array_id
Array identifier for the ragged array to be read from.
hssize_t start_row
Row at which the read will start.
hsize_t nrows
Number of rows to be read
hid_t type_id
Data type identifier for the data to be read.
hsize_t size[/*nrows*/]
Lengths of the rows to be read.
void *buf[/*nrows*/]
Pointers to buffers into which the data is to be read.
Returns:
Returns a non-negative value if successful. The values of the 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   Datatypes  

HDF Help Desk
Last modified: 8 July 1999
Describes HDF5 Release 1.4 Beta, December 2000