HDF5 Reference Manual H5 H5A H5D H5E H5F H5G H5I H5P H5R H5RA H5S H5T H5Z Tools

# 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.

- H5RAcreate

- H5RAopen
- H5RAclose

- H5RAwrite
- H5RAread

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.

HDF5 Reference Manual H5 H5A H5D H5E H5F H5G H5I H5P H5R H5RA H5S H5T H5Z Tools

HDF Help Desk
Last modified: 27 October 1998