From c7dbb9aca3c37323e8134a096340031e64732465 Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Fri, 19 Jan 2001 14:18:54 -0500 Subject: [PATCH] [svn-r3308] Purpose: Removing Ragged.html and RM_H5RA.html from the HDF5 doc set. These are the UG and RM pages, respectively, for Ragged Arrays, which were removed from the library last week. Solution: Removed the files Ragged.html and RM_H5RA.html. Platforms tested: IE 5 --- doc/html/RM_H5RA.html | 370 ------------------------------------------ doc/html/Ragged.html | 248 ---------------------------- 2 files changed, 618 deletions(-) delete mode 100644 doc/html/RM_H5RA.html delete mode 100644 doc/html/Ragged.html diff --git a/doc/html/RM_H5RA.html b/doc/html/RM_H5RA.html deleted file mode 100644 index 28e195c97e..0000000000 --- a/doc/html/RM_H5RA.html +++ /dev/null @@ -1,370 +0,0 @@ - - -HDF5/H5RA Experimental API Specification - - - - - -
-
- - - -
-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 - - - diff --git a/doc/html/Ragged.html b/doc/html/Ragged.html deleted file mode 100644 index 5646f39667..0000000000 --- a/doc/html/Ragged.html +++ /dev/null @@ -1,248 +0,0 @@ - - - - Ragged Array Experimental Interface (H5RA) - - - - - -
-
- - - -
- 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 Ragged Array Interface (H5RA)

- - - -
- -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!
- -
- -

1. Introduction

- -

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

2. Opening and Closing

- -
-
hid_t H5RAcreate (hid_t location, const char - *name, hid_t type, hid_t - plist) -
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 - plist defines the width of the raw dataset; - a nominal row is considered to be the width of a chunk. The - type argument defines the datatype which will be - stored in the file. A negative value is returned if the array - cannot be created. - -

-
hid_t H5RAopen (hid_t location, const char - *name) -
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. - -

-
herr_t H5RAclose (hid_t array) -
All ragged arrays should be closed by calling this - function. The group and component datasets will be closed - automatically by the library. -
- -

3. Reading and Writing

- -

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[]) -
A set of ragged array rows beginning at start_row - and continuing for nrows is written to the file, - converting the memory datatype type 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 - size array and the data for each row is pointed to - from the buf array. The size and - buf are indexed so their first element corresponds to - the first row on which to operate. - -

-
herr_t H5RAread (hid_t array_id, hssize_t - start_row, hsize_t nrows, hid_t - type, hsize_t size[], void - *buf[]) -
A set of ragged array rows beginning at start_row - and continuing for nrows is read from the file, - converting from the file datatype which was defined when the - array was created to the memory datatype type. The - number of elements to read from each row is specified in the - size array and the buffers in which to place the - results are pointed to by the buf array. On return, - the size 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 buf array is - null then the library will ignore the corresponding - size value and allocate a buffer large enough to hold - the entire row. This function returns negative for failures - with buf containing the original input values. -
- - -
-
- - - -
- 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   -
-
- - - -
-
-HDF Help Desk -
- - - -Last modified: 13 December 1999 - - -
-Describes HDF5 Release 1.4 Beta, December 2000 - - - -