|
-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 - |
|
-
-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 -Datatypes - |
|
- Introduction to HDF5 - HDF5 Reference Manual - Other HDF5 documents and links - - |
-
- And in this document, the
- HDF5 User's Guide:
- - Files - Datasets - Datatypes - Dataspaces - Groups - - References - Attributes - Property Lists - Error Handling - - Filters - Caching - Chunking - Mounting Files - - Performance - Debugging - Environment - DDL - - Ragged Arrays - |
|
-
-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! |
|---|
Ragged arrays should be considered alpha quality. They were - added to HDF5 to satisfy the needs of the ASCI/DMF vector - bundle project; the interface and storage methods are likely - to change in the future in ways that are not backward - compatible. - -
A two-dimensional ragged array has been added to the library - and built on top of other existing functionality. A ragged - array is a one-dimensional array of rows where the - length of any row is independent of the lengths of the other - rows. The number of rows and the length of each row can be - changed at any time (the current version does not support - truncating an array by removing rows). All elements of the - ragged array have the same datatype and, as with datasets, the - data is type-converted between memory buffers and files. - -
The current implementation works best when most of the rows are - approximately the same length since a two dimensional dataset - can be created to hold a nominal number of elements from each - row with the additional elements stored in a separate dataset - which implements a heap. - -
A ragged array is a composite object implemented as a group - with three datasets. The name of the group is the name of the - ragged array. The raw dataset is a two-dimensional - array that contains the first N elements of each row - where N is determined by the application when the array - is created. If most rows have fewer than N elements - then internal fragmentation may be quite bad. - -
The over dataset is a one-dimensional array that - contains elements from each row that don't fit in the - raw dataset. - -
The meta dataset maintains information about each row - such as the number of elements in the row, the location of the - overflow elements in the over dataset (if any), and the - amount of space reserved in over for the row. The - meta dataset has one entry per row and is where most of - the storage overhead is concentrated when rows are relatively - short. - -
hid_t H5RAcreate (hid_t location, const char
- *name, hid_t type, hid_t
- plist)
- hid_t H5RAopen (hid_t location, const char
- *name)
- herr_t H5RAclose (hid_t array)
- In order to be as efficient as possible the ragged array layer - operates on sets of contiguous rows and it is to the - application's advantage to perform I/O on as many rows at a time - as possible. These functions take a starting row number and the - number of rows on which to operate. - -
herr_t H5RAwrite (hid_t array_id, hssize_t
- start_row, hsize_t nrows, hid_t
- type, hsize_t size[], void
- *buf[])
- herr_t H5RAread (hid_t array_id, hssize_t
- start_row, hsize_t nrows, hid_t
- type, hsize_t size[], void
- *buf[])
- |
- Introduction to HDF5 - HDF5 Reference Manual - Other HDF5 documents and links - - |
-
- And in this document, the
- HDF5 User's Guide:
- - Files - Datasets - Datatypes - Dataspaces - Groups - - References - Attributes - Property Lists - Error Handling - - Filters - Caching - Chunking - Mounting Files - - Performance - Debugging - Environment - DDL - - Ragged Arrays - |