[svn-r673] Changes since 19980908

---------------------- ./COPYING Reformatted as text instead of C. Removed zlib crew from the list of contributors since no zlib code is actually in the hdf5 library. ./INSTALL ./INSTALL.ascired ./MANIFEST Minor updates for Beta release including version number change. ./INSTALL_MAINT Added information about making a release. ./RELEASE Updated function list based on public header files. ./bin/checkposix Got rid of complaints about some obvious things. ./doc/html/H5.api.html ./doc/html/RM_H5F.html ./src/H5F.c ./src/H5Fpublic.h ./test/tfile.c Changed H5Fget_create_template() and H5Fget_access_template() to H5Fget_create_plist() and H5Fget_access_plist() since that conforms better to lots of other names. ./doc/html/Datatypes.html ./doc/html/ExternalFiles.html ./doc/html/Files.html ./doc/html/H5.api.html ./doc/html/H5.sample_code.html ./doc/html/RM_H5F.html ./doc/html/RM_H5Front.html Changed `template' to `property list', etc. ./doc/html/Ragged.html [NEW] Documentation for ragged arrays. ./src/H5Iprivate.h ./src/H5Ipublic.h ./src/H5I.c Changed the scope of some symbols to be more local. ./src/H5.c ./src/H5AC.c ./src/H5D.c ./src/H5E.c ./src/H5F.c ./src/H5Ffamily.c ./src/H5Fistore.c ./src/H5Flow.c ./src/H5Fsec2.c ./src/H5Fsplit.c ./src/H5Fstdio.c ./src/H5G.c ./src/H5Gnode.c ./src/H5HG.c ./src/H5I.c ./src/H5O.c ./src/H5Ocomp.c ./src/H5Odtype.c ./src/H5Oefl.c ./src/H5Omtime.c ./src/H5Oname.c ./src/H5P.c ./src/H5S.c ./src/H5Shyper.c ./src/H5Tbit.c ./src/H5Tconv.c ./src/H5V.c ./src/H5Z.c ./src/H5private.h Fixed some violations of our naming scheme by adding HD to the beginning of all Posix functions.
author: Robb Matzke <matzke@llnl.gov> 1998-09-08 19:15:44 (GMT)
committer: Robb Matzke <matzke@llnl.gov> 1998-09-08 19:15:44 (GMT)
commit: b5e2752ad6d942a5dcee5f9fd4fad0a2e89c4a67 (patch)
tree: 790770464529c19e146112e5b48c77218132d8b7 /doc/html/Ragged.html
parent: 72a58073cd51996f34906f992a2377073df5bbc0 (diff)
download: hdf5-b5e2752ad6d942a5dcee5f9fd4fad0a2e89c4a67.zip
hdf5-b5e2752ad6d942a5dcee5f9fd4fad0a2e89c4a67.tar.gz
hdf5-b5e2752ad6d942a5dcee5f9fd4fad0a2e89c4a67.tar.bz2
1 files changed, 138 insertions, 0 deletions
diff --git a/doc/html/Ragged.html b/doc/html/Ragged.html
new file mode 100644
index 0000000..aaa653b
--- /dev/null
+++ b/doc/html/Ragged.html
@@ -0,0 +1,138 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+  <head>
+    <title>Ragged Arrays</title>
+  </head>
+
+  <body>
+    <h1>Ragged Arrays</h1>
+
+    <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 H5Rcreate (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 H5Ropen (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 H5Rclose (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 H5Rwrite (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 H5Rread (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>
+    <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 -->
+  </body>
+</html>
author	Robb Matzke <matzke@llnl.gov>	1998-09-08 19:15:44 (GMT)
committer	Robb Matzke <matzke@llnl.gov>	1998-09-08 19:15:44 (GMT)
commit	b5e2752ad6d942a5dcee5f9fd4fad0a2e89c4a67 (patch)
tree	790770464529c19e146112e5b48c77218132d8b7 /doc/html/Ragged.html
parent	72a58073cd51996f34906f992a2377073df5bbc0 (diff)
download	hdf5-b5e2752ad6d942a5dcee5f9fd4fad0a2e89c4a67.zip hdf5-b5e2752ad6d942a5dcee5f9fd4fad0a2e89c4a67.tar.gz hdf5-b5e2752ad6d942a5dcee5f9fd4fad0a2e89c4a67.tar.bz2