82fb21b613
been checked into "HDF5 Development" branch. General ======= Various "copy edit" types of repairs. Revisions to document cross-linking. Added structural links tying all docs together (banners at top and bottom of documents, similar to Reference Manual banners of the Beta release). Set background color to white in all documents. NCSAfooterlogo.gif hdf2.jpg New image files to make the documents more self-contained (i.e., to prevent loading images from NCSA and HDF home servers). index.html Redesigned to isolate links external to the installation in a single location. Intro to HDF5 ============= H5.intro.html Fixed banner linking Intro to other docs. Set all URLs to be relative within the distribution; nothing points back to the HDF server. Updates to "Limits of the Current Release" and "Changes in the Current Release." HDF5 User's Guide ================= Changed several User Guide section titles such that all sections that are primarily about a particular interface are now titled in the format "The xxxxx Interface (H5x)". H5.user.html Commented out links to developer docs since they are marked in MANIFEST as not being for distribution in the release. Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. Datatypes.html Removed the sentence "I'm deferring definition until later since they're probably not as important as the other data types." from Section 3.3, "Properties of Date and Time Atomic Types." Added info regarding 'char' versus 'string' datatypes. Added as Section 3.7, "Character and String Datatype Issues." References.html Commented out substantial material (at end of document) from References planning document that is not appropriate for the User Guide but that is worth keeping around. Groups.html Final edits from elimination of "current working group." HDF5 Reference Manual ===================== Removed "Draft" from the <title>__</title> lines. RM_H5Front.html Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. RM_H5F.html RM_H5P.html Add file mounting information.
286 lines
11 KiB
HTML
286 lines
11 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Ragged Arrays</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Files.html">Files</a>
|
|
<br>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Data Types</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
<a href="Groups.html">Groups</a>
|
|
<a href="References.html">References</a>
|
|
<br>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<br>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
Ragged Arrays
|
|
<!--
|
|
<hr>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Attributes.html">H5A</a>
|
|
<a href="Datasets.html">H5D</a>
|
|
<a href="Errors.html">H5E</a>
|
|
<a href="Files.html">H5F</a>
|
|
<a href="Groups.html">H5G</a>
|
|
<a href="Properties.html">H5P</a>
|
|
<a href="References.html">H5R & H5I</a>
|
|
<a href="Ragged.html">H5RA</a>
|
|
<a href="Dataspaces.html">H5S</a>
|
|
<a href="Datatypes.html">H5T</a>
|
|
<a href="Filters.html">H5Z</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
-->
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<h1>The Ragged Array Interface (H5RA)</h1>
|
|
|
|
<table border=1>
|
|
<tr><th align=left>
|
|
<font color=red>
|
|
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.
|
|
<p><center>Use these functions at your own risk!<br>
|
|
Do not create any archives using this interface!</center>
|
|
</font>
|
|
</th></tr>
|
|
</table>
|
|
|
|
<h2>1. Introduction</h2>
|
|
|
|
<p><b>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.</b>
|
|
|
|
<p>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 <em>rows</em> 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 data type and, as with datasets, the
|
|
data is type-converted between memory buffers and files.
|
|
|
|
<p>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.
|
|
|
|
<p>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 <em>raw</em> dataset is a two-dimensional
|
|
array that contains the first <em>N</em> elements of each row
|
|
where <em>N</em> is determined by the application when the array
|
|
is created. If most rows have fewer than <em>N</em> elements
|
|
then internal fragmentation may be quite bad.
|
|
|
|
<p>The <em>over</em> dataset is a one-dimensional array that
|
|
contains elements from each row that don't fit in the
|
|
<em>raw</em> dataset.
|
|
|
|
<p>The <em>meta</em> dataset maintains information about each row
|
|
such as the number of elements in the row, the location of the
|
|
overflow elements in the <em>over</em> dataset (if any), and the
|
|
amount of space reserved in <em>over</em> for the row. The
|
|
<em>meta</em> dataset has one entry per row and is where most of
|
|
the storage overhead is concentrated when rows are relatively
|
|
short.
|
|
|
|
<h2>2. Opening and Closing</h2>
|
|
|
|
<dl>
|
|
<dt><code>hid_t H5RAcreate (hid_t <em>location</em>, const char
|
|
*<em>name</em>, hid_t <em>type</em>, hid_t
|
|
<em>plist</em>)</code>
|
|
<dd>This function creates a new ragged array by creating the
|
|
group with the specified name and populating it with the
|
|
component datasets (which should not be accessed
|
|
independently). The dataset creation property list
|
|
<em>plist</em> defines the width of the <em>raw</em> dataset;
|
|
a nominal row is considered to be the width of a chunk. The
|
|
<em>type</em> argument defines the data type which will be
|
|
stored in the file. A negative value is returned if the array
|
|
cannot be created.
|
|
|
|
<br><br>
|
|
<dt><code>hid_t H5RAopen (hid_t <em>location</em>, const char
|
|
*<em>name</em>)</code>
|
|
<dd>This function opens a ragged array by opening the specified
|
|
group and the component datasets (which should not be accessed
|
|
indepently). A negative value is returned if the array cannot
|
|
be opened.
|
|
|
|
<br><br>
|
|
<dt><code>herr_t H5RAclose (hid_t <em>array</em>)</code>
|
|
<dd>All ragged arrays should be closed by calling this
|
|
function. The group and component datasets will be closed
|
|
automatically by the library.
|
|
</dl>
|
|
|
|
<h2>3. Reading and Writing</h2>
|
|
|
|
<p>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.
|
|
|
|
<dl>
|
|
<dt><code>herr_t H5RAwrite (hid_t <em>array_id</em>, hssize_t
|
|
<em>start_row</em>, hsize_t <em>nrows</em>, hid_t
|
|
<em>type</em>, hsize_t <em>size</em>[], void
|
|
*<em>buf</em>[])</code>
|
|
<dd>A set of ragged array rows beginning at <em>start_row</em>
|
|
and continuing for <em>nrows</em> is written to the file,
|
|
converting the memory data type <em>type</em> to the file data
|
|
type which was defined when the array was created. The number
|
|
of elements to write from each row is specified in the
|
|
<em>size</em> array and the data for each row is pointed to
|
|
from the <em>buf</em> array. The <em>size</em> and
|
|
<em>buf</em> are indexed so their first element corresponds to
|
|
the first row on which to operate.
|
|
|
|
<br><br>
|
|
<dt><code>herr_t H5RAread (hid_t <em>array_id</em>, hssize_t
|
|
<em>start_row</em>, hsize_t <em>nrows</em>, hid_t
|
|
<em>type</em>, hsize_t <em>size</em>[], void
|
|
*<em>buf</em>[])</code>
|
|
<dd>A set of ragged array rows beginning at <em>start_row</em>
|
|
and continuing for <em>nrows</em> is read from the file,
|
|
converting from the file data type which was defined when the
|
|
array was created to the memory data type <em>type</em>. The
|
|
number of elements to read from each row is specified in the
|
|
<em>size</em> array and the buffers in which to place the
|
|
results are pointed to by the <em>buf</em> array. On return,
|
|
the <em>size</em> array will contain the actual size of the
|
|
row which may be different than the requested size. When the
|
|
request size is smaller than the actual size the row will be
|
|
truncated; otherwise the remainder of the output buffer will
|
|
be zero filled. If a pointer in the <em>buf</em> array is
|
|
null then the library will ignore the corresponding
|
|
<em>size</em> value and allocate a buffer large enough to hold
|
|
the entire row. This function returns negative for failures
|
|
with <em>buf</em> containing the original input values.
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Files.html">Files</a>
|
|
<br>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Data Types</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
<a href="Groups.html">Groups</a>
|
|
<a href="References.html">References</a>
|
|
<br>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<br>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
Ragged Arrays
|
|
<!--
|
|
<hr>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Attributes.html">H5A</a>
|
|
<a href="Datasets.html">H5D</a>
|
|
<a href="Errors.html">H5E</a>
|
|
<a href="Files.html">H5F</a>
|
|
<a href="Groups.html">H5G</a>
|
|
<a href="Properties.html">H5P</a>
|
|
<a href="References.html">H5R & H5I</a>
|
|
<a href="Ragged.html">H5RA</a>
|
|
<a href="Dataspaces.html">H5S</a>
|
|
<a href="Datatypes.html">H5T</a>
|
|
<a href="Filters.html">H5Z</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
-->
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
|
|
|
|
<!--
|
|
<hr>
|
|
<address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address>
|
|
-->
|
|
<!-- Created: Wed Aug 26 14:10:32 EDT 1998 -->
|
|
<!-- hhmts start -->
|
|
<!--
|
|
Last modified: Fri Aug 28 14:27:19 EDT 1998
|
|
-->
|
|
<!-- hhmts end -->
|
|
|
|
<hr>
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
</address>
|
|
|
|
Last modified: 30 October 1998
|
|
|
|
</body>
|
|
</html>
|