diff options
| -rw-r--r-- | doxygen/dox/ReferenceManual.dox | 23 | ||||
| -rw-r--r-- | doxygen/dox/high_level/extension.dox | 657 | ||||
| -rw-r--r-- | doxygen/dox/high_level/high_level.dox | 29 | ||||
| -rw-r--r-- | doxygen/examples/H5DO_examples.c | 220 | ||||
| -rw-r--r-- | doxygen/examples/H5LDget_dset_elmts.c | 143 | ||||
| -rw-r--r-- | doxygen/examples/H5LT_examples.c | 27 | ||||
| -rw-r--r-- | doxygen/examples/H5TBAget_fill.c | 43 | ||||
| -rw-r--r-- | hl/src/H5DOpublic.h | 199 | ||||
| -rw-r--r-- | hl/src/H5DSpublic.h | 362 | ||||
| -rw-r--r-- | hl/src/H5IMpublic.h | 293 | ||||
| -rw-r--r-- | hl/src/H5LDpublic.h | 141 | ||||
| -rw-r--r-- | hl/src/H5LTpublic.h | 1398 | ||||
| -rw-r--r-- | hl/src/H5PTpublic.h | 416 | ||||
| -rw-r--r-- | hl/src/H5TBpublic.h | 539 |
14 files changed, 4480 insertions, 10 deletions
diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox index c477813..bc5a544 100644 --- a/doxygen/dox/ReferenceManual.dox +++ b/doxygen/dox/ReferenceManual.dox @@ -33,19 +33,26 @@ The functions provided by the HDF5 C-API are grouped into the following \li Functions with \ref ASYNC "asynchronous variants" \li \ref api-compat-macros \li <a href="./deprecated.html">Deprecated functions</a> -\li High-level Extensions +\li \ref high_level <ul> - <li><a href="https://portal.hdfgroup.org/display/HDF5/Lite">\Bold{HDF5 Lite} (H5LT)</a></li> - <li><a href="https://portal.hdfgroup.org/display/HDF5/Images">\Bold{HDF5 Image} (H5IM)</a></li> - <li><a href="https://portal.hdfgroup.org/display/HDF5/Tables">\Bold{HDF5 Table} (H5TB)</a></li> - <li><a href="https://portal.hdfgroup.org/display/HDF5/Packet+Tables">\Bold{HDF5 Packet Table} (H5TB)</a></li> - <li><a href="https://portal.hdfgroup.org/display/HDF5/Dimension+Scales">\Bold{HDF5 Dimension Scale} (H5DS)</a></li> + <li>\ref H5LT "Lite (H5LT, H5LD)" + <li>\ref H5IM "Images (H5IM)" + <li>\ref H5TB "Table (H5TB)" + <li>\ref H5PT "Packet Table (H5PT)" + <li>\ref H5DS "Dimension Scale (H5DS)" + <li>\ref H5DO "Optimizations (H5DO)" + <li>\ref H5LR "Extensions (H5LR, H5LT)" </ul> </td></tr> <tr><td colspan="3" style="border: none;"> -\ref H5 \ref H5A \ref H5D \ref H5E \ref H5ES \ref H5F \ref H5G \ref H5I \ref H5L +\a Core \a library: \ref H5 \ref H5A \ref H5D \ref H5E \ref H5ES \ref H5F \ref H5G \ref H5I \ref H5L \ref H5M \ref H5O \ref H5P \ref H5PL \ref H5R \ref H5S \ref H5T \ref H5VL \ref H5Z </td></tr> + +<tr><td colspan="3" style="border: none;"> +\a High-level \a library: \ref H5LT \ref H5IM \ref H5TB \ref H5PT \ref H5DS \ref H5DO \ref H5LR +</td></tr> + </table> </td></tr> @@ -86,4 +93,4 @@ Break a leg! <a href="https://github.com/HDFGroup/hdf5/pulls">pull request</a> !\n See the \ref RMT for general guidance. -*/
\ No newline at end of file +*/ diff --git a/doxygen/dox/high_level/extension.dox b/doxygen/dox/high_level/extension.dox new file mode 100644 index 0000000..1481bdd --- /dev/null +++ b/doxygen/dox/high_level/extension.dox @@ -0,0 +1,657 @@ +/** \defgroup H5LR Extensions + * + * <em>Working with region references, hyperslab selections, + * and bit-fields (H5LR, H5LT)</em> + * + * The following reference manual entries describe high-level HDF5 C and Fortran APIs + * for working with region references, hyperslab selections, and bit-fields. + * These functions were created as part of a project supporting + * NPP/NPOESS Data Production and Exploitation ( + * <a href="https://support.hdfgroup.org/projects/jpss/documentation"> + * project </a>, + * <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source"> + * software </a>). + * While they were written to facilitate access to NPP, NPOESS, and JPSS + * data in the HDF5 format, these functions may be useful to anyone working + * with region references, hyperslab selections, or bit-fields. + * + * Note that these functions are not part of the standard HDF5 distribution; + * the + * <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source"> + * software </a> + * must be separately downloaded and installed. + * + * A comprehensive guide to this library, + * <a href="https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf"> + * <em>User Guide to the HDF5 High-level Library for Handling Region References and Hyperslab Selections</em></a> + * is available at + * https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf. + * + * - \ref H5LRcopy_reference + * \n Copies data from the specified dataset to a new location and + * creates a reference to it. + * - \ref H5LRcopy_region + * \n Copies data from a referenced region to a region in a + * destination dataset. + * - \ref H5LRcreate_ref_to_all + * \n Creates a dataset with the region references to the data in all + * datasets located under a specified group in a file or creates a + * dataset with object references to all objects (groups or datasets) + * located under a specified group in a file. + * - \ref H5LRcreate_region_references + * \n Creates an array of region references using an array of paths to + * datasets and an array of corresponding hyperslab descriptions. + * - \ref H5LRget_region_info + * \n Retrieves information about the data a region reference points to. + * - \ref H5LRmake_dataset + * \n Creates and writes a dataset containing a list of + * region references. + * - \ref H5LRread_region + * \n Retrieves raw data pointed to by a region reference to + * an application buffer. + * - \ref H5LTcopy_region + * \n Copies data from a specified region in a source dataset + * to a specified region in a destination dataset. + * - \ref H5LTread_bitfield_value + * \n Retrieves the values of quality flags for each element + * to the application provided buffer. + * - \ref H5LTread_region + * \n Reads selected data to an application buffer. + * . + */ + +/*------------------------------------------------------------------------- + * + * Make dataset functions + * + *------------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Creates and writes a dataset containing a list of region references. + * + * \fgdta_loc_id + * \param[in] path Path to the dataset being created + * \param[in] type_id Datatype of the dataset + * \param[in] buf_size Size of the \p loc_id_ref and \p buf arrays + * \param[in] loc_id_ref Array of object identifiers; each identifier + * describes to which HDF5 file the corresponding + * region reference belongs to + * \param[in] buf Array of region references + * + * \return \herr_t + * + * \details Given an array of size \p buf_size of region references \p buf, + * the function will create a dataset with path \p path, at location + * specified by \p loc_id and of a datatype specified by \p type_id, + * and will write data associated with each region reference in the order + * corresponding to the order of the region references in the buffer. + * It is assumed that all referenced hyperslabs have the same dimensionality, + * and only the size of the slowest changing dimension may differ. + * Each reference in the \p buf array belongs to the file identified + * by the corresponding object identifiers in the array \p loc_id_ref. + * + * If \p path does not exist in \p loc_id then the function will + * create the path specified by \p path automatically. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +H5_HLRDLL herr_t H5LRmake_dataset(hid_t loc_id, + const char *path, + hid_t type_id, const size_t buf_size, + const hid_t *loc_id_ref, + const hdset_reg_ref_t *buf); + +/*------------------------------------------------------------------------- + * + * Make and manipulate dataset region references functions + * + *------------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Creates an array of region references using an array of paths to + * datasets and an array of corresponding hyperslab descriptions. + * + * \param[in] obj_id File identifier for the HDF5 file containing + * the referenced regions or an object identifier + * for any object in that file + * \param[in] num_elem Number of elements in the \p path and + * \p buf arrays + * \param[in] path Array of pointers to strings, which contain + * the paths to the target datasets for the + * region references + * \param[in] block_coord Array of hyperslab coordinate + * \param[out] buf Buffer for returning an array of region + * references + * + * \return \herr_t + * + * \note **Motivation:** + * \note H5LRcreate_region_references() is useful when creating + * large numbers of similar region references. + * + * \details H5LRcreate_region_references() creates a list of region references + * given an array of paths to datasets and another array listing the + * corner coordinates of the corresponding hyperslabs. + * + * \p path parameter is an array of pointers to strings. + * + * \p num_elem specifies the number of region references to be created, + * thus specifying the size of the \p path and \p _buf arrays. + * + * Buffer \p block_coord has size 2*rank and is the coordinates of the + * starting point following by the coordinates of the ending point of + * the hyperslab, repeated \p num_elem times for each hyperslab. + * For example, creating two region references to two hyperslabs, + * one with a rectangular hyperslab region starting at element (2,2) + * to element (5,4) and the second rectangular region starting at + * element (7,7) to element (9,10), results in \p block_coord + * being {2,2,5,4, 7,7,9,10}. + * + * The rank of the hyperslab will be the same as the rank of the + * target dataset. H5LRcreate_region_references() will retrieve + * the rank for each dataset and will use those values to interpret + * the values in the buffer. Please note that rank may vary from one + * dataset to another. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +H5_HLRDLL herr_t H5LRcreate_region_references(hid_t obj_id, + size_t num_elem, + const char **path, + const hsize_t *block_coord, + hdset_reg_ref_t *buf); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Copies data from the specified dataset to a new location and + * creates a reference to it. + * + * \param[in] obj_id Identifier of any object in a file an + * HDF5 reference belongs to + * \param[in] ref Reference to the datasets region + * \param[in] file Name of the destination file + * \param[in] path Full path to the destination dataset + * \param[in] block_coord Hyperslab coordinates in the destination + * dataset + * \param[out] ref_new Region reference to the new location of + * data + * + * \return \herr_t + * + * \details Given a data set pointed to by a region reference, the function + * H5LRcopy_reference() will copy the hyperslab data referenced by + * a datasets region reference into existing dataset specified by + * its path \p path in the file with the name \p file, and to location + * specified by the hyperslab coordinates \p block_coord. It will + * create the region reference \p ref_new to point to the new location. + * The number of elements in the old and newly specified regions has + * to be the same. + * + * Buffer \p block_coord has size 2*rank and is the coordinates of + * the starting point following by the coordinates of the ending + * point of the hyperslab. For example, to extract a rectangular + * hyperslab region starting at element (2,2) to element (5,4) + * then \p block_coord would be {2, 2, 5, 4}. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +H5_HLRDLL herr_t H5LRcopy_reference(hid_t obj_id, hdset_reg_ref_t *ref, const char *file, + const char *path, const hsize_t *block_coord, + hdset_reg_ref_t *ref_new); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Copies data from a referenced region to a region in a + * destination dataset. + * + * \param[in] obj_id Identifier of any object in a file + * dataset region reference belongs to + * \param[in] ref Dataset region reference + * \param[in] file Name of the destination file + * \param[in] path Full path to the destination dataset + * \param[in] block_coord Hyperslab coordinates in the destination + * dataset + * + * \return \herr_t + * + * \details Given a dataset region reference \p ref in a source file + * specified by an identifier of any object in that file + * \p obj_id, the function will write data to the existing + * dataset \p path in file \p file to the simple hyperslab + * specified by \p block_coord. + * + * Buffer \p block_coord has size 2*rank and is the coordinates + * of the starting point following by the coordinates of the + * ending point of the hyperslab. For example, to specify a + * rectangular hyperslab destination region starting at element + * (2,2) to element (5,4) then \p block_coord would be {2, 2, 5, 4}. + * + * If \p path does not exist in the destination file (as may be + * the case when writing to a new file) then the dataset will be + * copied directly to the \p path and \p block_coord will be + * disregarded. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +H5_HLRDLL herr_t H5LRcopy_region(hid_t obj_id, + hdset_reg_ref_t *ref, + const char *file, + const char *path, + const hsize_t *block_coord); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Creates a dataset with the region references to the data + * in all datasets located under a specified group in a file + * or creates a dataset with object references to all objects + * (groups or datasets) located under a specified group in a file. + * + * \fg_loc_id + * \param[in] group_path Absolute or relative path to the group + * at which traversal starts + * \param[in] ds_path Absolute or relative path to the dataset + * with region references to be created + * \param[in] index_type Index_type; + * see valid values below in description + * \param[in] order Order in which index is traversed; + * see valid values below in description + * \param[in] ref_type Reference type; + * see valid values below in description + * + * \return \herr_t + * + * \details H5LRcreate_ref_to_all() creates a dataset with the + * region references to the data in all datasets located + * under a specified group in a file or creates a dataset with + * object references to all objects (groups or datasets) located + * under a specified group in a file. + * + * Given a dataset path \p ds_path in a file specified by the + * \p loc_id identifier, the function H5LRcreate_ref_to_all() + * will create a contiguous one-dimensional dataset with the + * region references or object references depending on the value + * of the \p ref_type parameter. When \p ref_type is + * #H5R_DATASET_REGION, each region reference points to all data + * in a dataset encountered by an internally called H5Lvisit() + * routine, which starts at the group specified by the \p loc_id + * and \p group_path parameters. In a like manner, when + * \p ref_type is #H5R_OBJECT, each object reference points to + * an object (a group or a dataset) encountered by H5Lvisit(). + * + * If \p ds_path does not exist in \p loc_id then the function + * will create the path specified by \p ds_path automatically. + * + * \p index_type specifies the index to be used. + * Valid values include the following: + * - #H5_INDEX_NAME Alphanumeric index on name + * - #H5_INDEX_CRT_ORDER Index on creation order + * . + * + * \p order specifies the order in which objects are to be + * inspected along the index specified in \p index_type. + * Valid values include the following: + * - #H5_ITER_INC Increasing order + * - #H5_ITER_DEC Decreasing order + * - #H5_ITER_NATIVE Fastest available order + * . + * + * For more detailed information on these two parameters, + * see H5Lvisit(). + * + * \p ref_type specifies the type of the reference to be used. + * Valid values include the following: + * - #H5R_DATASET_REGION Dataset region reference + * - #H5R_OBJECT Object reference + * . + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +H5_HLRDLL herr_t H5LRcreate_ref_to_all(hid_t loc_id, const char *group_path, + const char *ds_path, H5_index_t index_type, H5_iter_order_t order, H5R_type_t ref_type); + +/*------------------------------------------------------------------------- + * + * Read dataset functions + * + *------------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Retrieves raw data pointed to by a region reference + * to an application buffer. + * + * \param[in] obj_id File identifier for the HDF5 file containing + * the dataset with the referenced region or an + * object identifier for any object in that file + * \param[in] ref Region reference specifying data to be read + * in + * \param[in] mem_type Memory datatype of data read from referenced + * region into the application buffer + * \param[in,out] numelem Number of elements to be read into buffer + * \p buf + * \param[out] buf Buffer in which data is returned to the + * application + * + * \return \herr_t + * + * \details H5LRread_region() reads data pointed to by the region + * reference \p ref into the buffer \p buf. + * + * \p numelem specifies the number of elements to be read + * into \p buf. When the size of the reference region is unknown, + * H5LRread_region() can be called with \p buf set to NULL; + * the number of elements in the referenced region will be returned + * in \p numelem. + * + * The buffer buf must be big enough to hold \p numelem elements + * of type \p mem_type. For example, if data is read from the referenced + * region into an integer buffer, \p mem_type should be #H5T_NATIVE_INT + * and the buffer must be at least \c sizeof(int) * \p numelem bytes + * in size. This buffer must be allocated by the application. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +H5_HLRDLL herr_t H5LRread_region(hid_t obj_id, + const hdset_reg_ref_t *ref, + hid_t mem_type, + size_t *numelem, + void *buf ); + +/*------------------------------------------------------------------------- + * + * Query dataset functions + * + *------------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Retrieves information about the data a region reference + * points to. + * + * \param[in] obj_id Identifier of any object in an HDF5 file + * the region reference belongs to. + * \param[in] ref Region reference to query + * \param[in,out] len Size of the buffer to store \p path in. + * NOTE: if \p *path is not NULL then \p *len + * must be the appropriate length + * \param[out] path Full path that a region reference points to + * \param[out] rank The number of dimensions of the dataset + * dimensions of the dataset pointed by + * region reference. + * \param[out] dtype Datatype of the dataset pointed by the + * region reference. + * \param[out] sel_type Type of the selection (point or hyperslab) + * \param[in,out] numelem Number of coordinate blocks or + * selected elements. + * \param[out] buf Buffer containing description of the region + * pointed by region reference + * + * \return \herr_t + * + * \details H5LRget_region_info() queries information about the data + * pointed by a region reference \p ref. It returns one of the + * absolute paths to a dataset, length of the path, dataset’s rank + * and datatype, description of the referenced region and type of + * the referenced region. Any output argument can be NULL if that + * argument does not need to be returned. + * + * The parameter \p obj_id is an identifier for any object in the + * HDF5 file containing the referenced object. For example, it can + * be an identifier of a dataset the region reference belongs to + * or an identifier of an HDF5 file the dataset with region references + * is stored in. + * + * The parameter \p ref is a region reference to query. + * + * The parameter \p path is a pointer to application allocated + * buffer of size \p len+1 to return an absolute path to a dataset + * the region reference points to. + * + * The parameter \p len is a length of absolute path string plus + * the \0 string terminator. If path parameter is NULL, actual + * length of the path (+1 for \0 string terminator) is returned to + * application and can be used to allocate buffer path of an + * appropriate length \p len. + * + * The parameter \p sel_type describes the type of the selected + * region. Possible values can be #H5S_SEL_POINTS for point + * selection and #H5S_SEL_HYPERSLABS for hyperslab selection. + * + * The parameter \p numelem describes how many elements will be + * placed in the buffer \p buf. The number should be interpreted + * using the value of \p sel_type. + * + * If value of \p sel_type is #H5S_SEL_HYPERSLABS, the parameter + * \p buf contains \p numelem blocks of the coordinates for each + * simple hyperslab of the referenced region. Each block has + * length \c 2*\p rank and is organized as follows: <"start" coordinate>, + * immediately followed by <"opposite" corner coordinate>. + * The total size of the buffer to hold the description of the + * region will be \c 2*\p rank*\p numelem. If region reference + * points to a contiguous sub-array, then the value of \p numelem + * is 1 and the block contains coordinates of the upper left and + * lower right corners of the sub-array (or simple hyperslab). + * + * If value of \p sel_type is #H5S_SEL_POINTS, the parameter \p buf + * contains \p numelem blocks of the coordinates for each selected + * point of the referenced region. Each block has length \p rank + * and contains coordinates of the element. The total size of the + * buffer to hold the description of the region will be + * \p rank* \p numelem. + * + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +H5_HLRDLL herr_t H5LRget_region_info(hid_t obj_id, + const hdset_reg_ref_t *ref, + size_t *len, + char *path, + int *rank, + hid_t *dtype, + H5S_sel_type *sel_type, + size_t *numelem, + hsize_t *buf ); + + + +/*------------------------------------------------------------------------- + * + * Make dataset functions + * + *------------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Copies data from a specified region in a source dataset + * to a specified region in a destination dataset + * + * \param[in] file_src Name of the source file + * \param[in] path_src Full path to the source dataset + * \param[in] block_coord_src Hyperslab coordinates in the + * source dataset + * \param[in] file_dest Name of the destination file + * \param[in] path_dest Full path to the destination dataset + * \param[in] block_coord_dset Hyperslab coordinates in the + * destination dataset + * + * \return \herr_t + * + * \details Given a path to a dataset \p path_src in a file with the + * name \p file_src, and description of a simple hyperslab of + * the source \p block_coord_src, the function will write data + * to the dataset \p path_dest in file \p file_dest to the + * simple hyperslab specified by \p block_coord_dset. + * The arrays \p block_coord_src and \p block_coord_dset have + * a length of 2*rank and are the coordinates of the starting + * point following by the coordinates of the ending point of the + * hyperslab. For example, to specify a rectangular hyperslab + * destination region starting at element (2,2) to element (5,4) + * then \p block_coord_dset would be {2, 2, 5, 4}. + * + * If \p path_dest does not exist in the destination file + * (as may be the case when writing to a new file) then the + * dataset will be copied directly to the \p path_dest and + * \p block_coord_dset will be disregarded. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +H5_HLRDLL herr_t H5LTcopy_region(const char *file_src, + const char *path_src, + const hsize_t *block_coord_src, + const char *file_dest, + const char *path_dest, + const hsize_t *block_coord_dset); + +/*------------------------------------------------------------------------- + * + * Read dataset functions + * + *------------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Reads selected data to an application buffer. + * + * \param[in] file Name of file + * \param[in] path Full path to a dataset + * \param[in] block_coord Hyperslab coordinates + * \param[in] mem_type Memory datatype, describing the buffer + * the referenced data will be read into + * \param[out] buf Buffer containing data from the + * referenced region + * + * \return \herr_t + * + * \details H5LTread_region() reads data from a region described by + * the hyperslab coordinates in \p block_coord, located in + * the dataset specified by its absolute path \p path in a + * file specified by its name \p file. Data is read into a + * buffer \p buf of the datatype that corresponds to the + * HDF5 datatype specified by \p mem_type. + * + * Buffer \p block_coord has size 2*rank and is the coordinates + * of the starting point following by the coordinates of the + * ending point of the hyperslab. For example, to extract a + * rectangular hyperslab region starting at element (2,2) to + * element (5,4) then \p block_coord would be {2, 2, 5, 4}. + * + * Buffer \p buf should be big enough to hold selected elements + * of the type that corresponds to the \p mem_type + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +H5_HLRDLL herr_t H5LTread_region(const char *file, + const char *path, + const hsize_t *block_coord, + hid_t mem_type, + void *buf ); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5LR + * + * \brief Retrieves the values of quality flags for each element + * to the application provided buffer. + * + * \param[in] dset_id Identifier of the dataset with bit-field values + * \param[in] num_values Number of the values to be extracted + * \param[in] offset Array of staring bits to be extracted from + * the element; valid values: 0 (zero) through 7 + * \param[in] lengths Array of the number of bits to be extracted + * for each value + * \param[in] space Dataspace identifier, describing the elements + * to be read from the dataset with bit-field + * values + * \param[out] buf Buffer to read the values in + * + * \return \herr_t + * + * \details H5LTread_bitfield_value() reads selected elements from a + * dataset specified by its identifier \p dset_id, and unpacks + * the bit-field values to a buffer \p buf. + * + * The parameter \p space is a space identifier that indicates + * which elements of the dataset should be read. + * + * The parameter \p offset is an array of length \p num_values; + * the i<sup>th</sup> element of the array holds the value of the + * starting bit of the i<sup>th</sup> bit-field value. + * Valid values are: 0 (zero) through 7. + * + * The parameter \p lengths is an array of length \p num_values; + * the i<sup>th</sup> element of the array holds the number of + * bits to be extracted for the i<sup>th</sup> bit-field value. + * Extracted bits will be interpreted as a base-2 integer value. + * Each value will be converted to the base-10 integer value and + * stored in the application buffer. + * + * Buffer \p buf is allocated by the application and should be big + * enough to hold \c num_sel_elem * \p num_values elements of the + * specified type, where \c num_sel_elem is a number of the elements + * to be read from the dataset. Data in the buffer is organized + * as \p num_values values for the first element, followed by the + * \p num_values values for the second element, ... , followed by + * the \p num_values values for the + * \c num_selected_elem<sup>th</sup> element. + * + * \version 1.1 Fortran wrapper introduced in this release. + * + * \since 1.0 + * + */ +H5_HLRDLL herr_t H5LTread_bitfield_value(hid_t dset_id, int num_values, const unsigned *offset, + const unsigned *lengths, hid_t space, int *buf); + diff --git a/doxygen/dox/high_level/high_level.dox b/doxygen/dox/high_level/high_level.dox new file mode 100644 index 0000000..c53d298 --- /dev/null +++ b/doxygen/dox/high_level/high_level.dox @@ -0,0 +1,29 @@ +/** \page high_level High-level library + * The high-level HDF5 library includes several sets of convenience and standard-use APIs to + * facilitate common HDF5 operations. + * + * <ul> + * <li>\ref H5LT "Lite (H5LT, H5LD)" + * \n + * Functions to simplify creating and manipulating datasets, attributes and other features + * <li>\ref H5IM "Image (H5IM)" + * \n + * Creating and manipulating HDF5 datasets intended to be interpreted as images + * <li>\ref H5TB "Table (H5TB)" + * \n + * Creating and manipulating HDF5 datasets intended to be interpreted as tables + * <li>\ref H5PT "Packet Table (H5PT)" + * \n + * Creating and manipulating HDF5 datasets to support append- and read-only operations on table data + * <li>\ref H5DS "Dimension Scale (H5DS)" + * \n + * Creating and manipulating HDF5 datasets that are associated with the dimension of another HDF5 dataset + * <li>\ref H5DO "Optimizations (H5DO)" + * \n + * Bypassing default HDF5 behavior in order to optimize for specific use cases + * <li>\ref H5LR "Extensions (H5LR, H5LT)" + * \n + * Working with region references, hyperslab selections, and bit-fields + * </ul> + * + */ diff --git a/doxygen/examples/H5DO_examples.c b/doxygen/examples/H5DO_examples.c new file mode 100644 index 0000000..7a33c6b --- /dev/null +++ b/doxygen/examples/H5DO_examples.c @@ -0,0 +1,220 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +//! <!-- [H5DOwrite] --> + +#include <zlib.h> +#include <math.h> +#define DEFLATE_SIZE_ADJUST(s) (ceil(((double)(s)) * 1.001) + 12) + : + : +size_t buf_size = CHUNK_NX*CHUNK_NY*sizeof(int); + const Bytef *z_src = (const Bytef *)(direct_buf); + Bytef * z_dst; /* Destination buffer */ + uLongf z_dst_nbytes = (uLongf)DEFLATE_SIZE_ADJUST(buf_size); + uLong z_src_nbytes = (uLong)buf_size; + int aggression = 9; /* Compression aggression setting */ + uint32_t filter_mask = 0; + size_t buf_size = CHUNK_NX * CHUNK_NY * sizeof(int); + + /* Create the data space */ + if ((dataspace = H5Screate_simple(RANK, dims, maxdims)) < 0) + goto error; + + /* Create a new file */ + if ((file = H5Fcreate(FILE_NAME5, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) < 0) + goto error; + + /* Modify dataset creation properties, i.e. enable chunking and compression */ + if ((cparms = H5Pcreate(H5P_DATASET_CREATE)) < 0) + goto error; + + if ((status = H5Pset_chunk(cparms, RANK, chunk_dims)) < 0) + goto error; + + if ((status = H5Pset_deflate(cparms, aggression)) < 0) + goto error; + + /* Create a new dataset within the file using cparms creation properties */ + if ((dset_id = H5Dcreate2(file, DATASETNAME, H5T_NATIVE_INT, dataspace, H5P_DEFAULT, cparms, + H5P_DEFAULT)) < 0) + goto error; + + /* Initialize data for one chunk */ + for (i = n = 0; i < CHUNK_NX; i++) + for (j = 0; j < CHUNK_NY; j++) + direct_buf[i][j] = n++; + + /* Allocate output (compressed) buffer */ + outbuf = malloc(z_dst_nbytes); + z_dst = (Bytef *)outbuf; + + /* Perform compression from the source to the destination buffer */ + ret = compress2(z_dst, &z_dst_nbytes, z_src, z_src_nbytes, aggression); + + /* Check for various zlib errors */ + if (Z_BUF_ERROR == ret) { + fprintf(stderr, "overflow"); + goto error; + } + else if (Z_MEM_ERROR == ret) { + fprintf(stderr, "deflate memory error"); + goto error; + } + else if (Z_OK != ret) { + fprintf(stderr, "other deflate error"); + goto error; + } + + /* Write the compressed chunk data repeatedly to cover all the + * * chunks in the dataset, using the direct write function. */ + for (i = 0; i < NX / CHUNK_NX; i++) { + for (j = 0; j < NY / CHUNK_NY; j++) { + status = + H5DOwrite_chunk(dset_id, H5P_DEFAULT, filter_mask, offset, z_dst_nbytes, outbuf); + offset[1] += CHUNK_NY; + } + offset[0] += CHUNK_NX; + offset[1] = 0; + } + + /* Overwrite the first chunk with uncompressed data. Set the filter mask to + * * indicate the compression filter is skipped */ + filter_mask = 0x00000001; + offset[0] = offset[1] = 0; + if (H5DOwrite_chunk(dset_id, H5P_DEFAULT, filter_mask, offset, buf_size, direct_buf) < 0) + goto error; + + /* Read the entire dataset back for data verification converting ints to longs */ + if (H5Dread(dataset, H5T_NATIVE_LONG, H5S_ALL, H5S_ALL, H5P_DEFAULT, outbuf_long) < 0) + goto error; + + /* Data verification here */ + : + : + + //! <!-- [H5DOwrite] --> + + //! <!-- [H5DOread] --> + +#include <zlib.h> +#include <math.h> +#define DEFLATE_SIZE_ADJUST(s) (ceil(((double)(s)) * 1.001) + 12) + : + : +size_t buf_size = CHUNK_NX*CHUNK_NY*sizeof(int); + const Bytef *z_src = (const Bytef *)(direct_buf); + Bytef * z_dst; /* Destination buffer */ + uLongf z_dst_nbytes = (uLongf)DEFLATE_SIZE_ADJUST(buf_size); + uLong z_src_nbytes = (uLong)buf_size; + int aggression = 9; /* Compression aggression setting */ + uint32_t filter_mask = 0; + size_t buf_size = CHUNK_NX * CHUNK_NY * sizeof(int); + /* For H5DOread_chunk() */ + void * readbuf = NULL; /* Buffer for reading data */ + const Bytef *pt_readbuf; /* Point to the buffer for data read */ + hsize_t read_chunk_nbytes; /* Size of chunk on disk */ + int read_dst_buf[CHUNK_NX][CHUNK_NY]; /* Buffer to hold un-compressed data */ + + /* Create the data space */ + if ((dataspace = H5Screate_simple(RANK, dims, maxdims)) < 0) + goto error; + + /* Create a new file */ + if ((file = H5Fcreate(FILE_NAME5, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) < 0) + goto error; + + /* Modify dataset creation properties, i.e. enable chunking and compression */ + if ((cparms = H5Pcreate(H5P_DATASET_CREATE)) < 0) + goto error; + + if ((status = H5Pset_chunk(cparms, RANK, chunk_dims)) < 0) + goto error; + + if ((status = H5Pset_deflate(cparms, aggression)) < 0) + goto error; + + /* Create a new dataset within the file using cparms creation properties */ + if ((dset_id = H5Dcreate2(file, DATASETNAME, H5T_NATIVE_INT, dataspace, H5P_DEFAULT, cparms, + H5P_DEFAULT)) < 0) + goto error; + + /* Initialize data for one chunk */ + for (i = n = 0; i < CHUNK_NX; i++) + for (j = 0; j < CHUNK_NY; j++) + direct_buf[i][j] = n++; + + /* Allocate output (compressed) buffer */ + outbuf = malloc(z_dst_nbytes); + z_dst = (Bytef *)outbuf; + + /* Perform compression from the source to the destination buffer */ + ret = compress2(z_dst, &z_dst_nbytes, z_src, z_src_nbytes, aggression); + + /* Check for various zlib errors */ + if (Z_BUF_ERROR == ret) { + fprintf(stderr, "overflow"); + goto error; + } + else if (Z_MEM_ERROR == ret) { + fprintf(stderr, "deflate memory error"); + goto error; + } + else if (Z_OK != ret) { + fprintf(stderr, "other deflate error"); + goto error; + } + + /* Write the compressed chunk data repeatedly to cover all the + * * chunks in the dataset, using the direct write function. */ + for (i = 0; i < NX / CHUNK_NX; i++) { + for (j = 0; j < NY / CHUNK_NY; j++) { + status = H5DOwrite_chunk(dset_id, H5P_DEFAULT, filter_mask, offset, z_dst_nbytes, outbuf); + offset[1] += CHUNK_NY; + } + offset[0] += CHUNK_NX; + offset[1] = 0; + } + + if (H5Fflush(dataset, H5F_SCOPE_LOCAL) < 0) + goto error; + + if (H5Dclose(dataset) < 0) + goto error; + + if ((dataset = H5Dopen2(file, DATASETNAME1, H5P_DEFAULT)) < 0) + goto error; + + offset[0] = CHUNK_NX; + offset[1] = CHUNK_NY; + + /* Get the size of the compressed chunk */ + ret = H5Dget_chunk_storage_size(dataset, offset, &read_chunk_nbytes); + + readbuf = HDmalloc(read_chunk_nbytes); + pt_readbuf = (const Bytef *)readbuf; + + /* Use H5DOread_chunk() to read the chunk back */ + if ((status = H5DOread_chunk(dataset, H5P_DEFAULT, offset, &read_filter_mask, readbuf)) < 0) + goto error; + + ret = + uncompress((Bytef *)read_dst_buf, (uLongf *)&buf_size, pt_readbuf, (uLong)read_chunk_nbytes); + + /* Check for various zlib errors */ + if (Z_BUF_ERROR == ret) { + fprintf(stderr, "error: not enough room in output buffer"); + goto error; + } + else if (Z_MEM_ERROR == ret) { + fprintf(stderr, "error: not enough memory"); + goto error; + } + else if (Z_OK != ret) { + fprintf(stderr, "error: corrupted input data"); + goto error; + } + + /* Data verification here */ + : + : +//! <!-- [H5DOread] --> diff --git a/doxygen/examples/H5LDget_dset_elmts.c b/doxygen/examples/H5LDget_dset_elmts.c new file mode 100644 index 0000000..e23299a --- /dev/null +++ b/doxygen/examples/H5LDget_dset_elmts.c @@ -0,0 +1,143 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +//! <!-- [first_declare] --> + +DATASET "DSET1" {DATATYPE H5T_STD_I32LE DATASPACE SIMPLE{(4, 13) / (60, 100)} : : } + +//! <!-- [first_declare] --> + +//! <!-- [first_reading] --> + +/* open the HDF5 file */ +fid = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT); + +/* open the dataset */ +did = H5Dopen2(fid, "DSET1", H5P_DEFAULT); + : + : + /* define hsize_t dims[2]; */ + /* define hsize_t new_dims[2]; */ + /* get the dataset's current dimension sizes */ + H5LDget_dset_dims(did, dims); + + /* extend the dataset by 2 */ + new_dims[0] = dims[0] + 2; + new_dims[1] = dims[1] + 2; + H5Dset_extent(did, new_dims) + + /* write data to the extended dataset */ + : : + /* get the size of the dataset's data type */ + type_size = H5LDget_dset_type_size(did, NULL); + : + : + /* allocate buffer for storing selected data elements from the dataset */ + /* calculate # of selected elements from dims & new_dims */ + /* buffer size = type_size * number of selected elements */ + : + : + /* read the selected elements from the dataset into buf */ + H5LDget_dset_elmts(did, dims, new_dims, NULL, buf); + : + : + H5Dclose(did); + H5Fclose(fid); + + //! <!-- [first_reading] --> + + //! <!-- [first_output] --> + + data for elements (0, 13), (0, 14) + data for elements (1, 13), (1, 14) + data for elements (2, 13), (2, 14) + data for elements (3, 13), (3, 14) + data for elements (4, 0), (4, 1), (4, 2)......................(4, 13), (4, 14) + data for elements (5, 0), (5, 1), (5, 2)......................(5, 13), (5, 14) + +//! <!-- [first_output] --> + + +//! <!-- [second_declare] --> + + DATASET "DSET2" { + DATATYPE H5T_COMPOUND { + H5T_STD_I32LE "a"; + H5T_STD_I32LE "b"; + H5T_ARRAY + { + [4] H5T_STD_I32LE + } + "c"; + H5T_STD_I32LE "d"; + H5T_STD_I32LE "e"; + H5T_COMPOUND + { + H5T_STD_I32LE "a"; + H5T_STD_I32LE "b"; + H5T_ARRAY + { + [4] H5T_STD_I32LE + } + "c"; + H5T_STD_I32LE "d"; + H5T_STD_I32LE "e"; + } + "s2"; + } + DATASPACE SIMPLE + { + (5) / (5) + } + :: + } + + //! <!-- [second_declare] --> + + //! <!-- [second_reading] --> + + /* open the HDF5 file */ + fid = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT); + + /* open the dataset */ + did = H5Dopen2(fid, "DSET2", H5P_DEFAULT); + + /* define hsize_t dims[1]; */ + /* define hsize_t new_dims[1]; */ + : + : + /* get the dataset's current dimension size */ + H5LDget_dset_dims(did, dims); + + /* extend the dataset by 2 */ + new_dims[0] = dims[0] + 2; + H5Dset_extent(did, new_dims); + : + : + /* write data to the extended part of the dataset */ + : + : + /* #define fields "d,s2.c" */ + /* get the size of the dataset's data type for the selected fields */ + type_size = H5LDget_dset_type_size(did, fields); + : + : + /* allocate buffer for storing selected data elements from the dataset */ + /* calculate # of selected elements from dims & new_dims */ + /* buffer size = type_size * number of selected elements */ + : + : + /* read the selected elements from the dataset into buf */ + H5LD_get_dset_elmts(did, dims, new_dims, fields, buf); + : + : + H5Dclose(did); + H5Fclose(fid); + + //! <!-- [second_reading] --> + + //! <!-- [second_output] --> + + Data for element (5): integer value for "d", 4 integer values for array "s2.c" + Data for element (6): integer value for "d", 4 integer values for array "s2.c" + +//! <!-- [second_output] --> diff --git a/doxygen/examples/H5LT_examples.c b/doxygen/examples/H5LT_examples.c new file mode 100644 index 0000000..5ed4c29 --- /dev/null +++ b/doxygen/examples/H5LT_examples.c @@ -0,0 +1,27 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +//! <!-- [get_attribute_info] --> + +H5T_class_t type_class; +size_t type_size; +hsize_t dims[0]; +... status = H5LTget_attribute_info(file_id, "/", STRNAME, dims, &type_class, &type_size); +if (type_class == H5T_STRING) { + printf("Attribute is a string.\n"); + printf("String size: %i\n", type_size); + + //! <!-- [get_attribute_info] --> + + //! <!-- [enum] --> + + “H5T_ENUM + { + H5T_NATIVE_INT; + “Bob” 0; + “Elena” 1; + “Quincey” 2; + “Frank” 3; + } + ” + +//! <!-- [enum] --> diff --git a/doxygen/examples/H5TBAget_fill.c b/doxygen/examples/H5TBAget_fill.c new file mode 100644 index 0000000..15eae8b --- /dev/null +++ b/doxygen/examples/H5TBAget_fill.c @@ -0,0 +1,43 @@ +unsigned char tmp_fill_buf[40]; +... + + file_id = H5Fopen(FILENAME, H5F_ACC_RDWR, H5P_DEFAULT); +dataset_id = H5Dopen(file_id, TABLE_NAME, H5P_DEFAULT); +datatype_id = H5Dget_type(dataset_id); + +status = H5TBget_table_info(file_id, TABLE_NAME, &nfields, &nrecords); + +hasfill = H5TBAget_fill(file_id, TABLE_NAME, dataset_id, tmp_fill_buf); + +for (i = 0; i < nfields; i++) { + member_type_id = H5Tget_member_type(datatype_id, (unsigned)i); + native_mem_type_id = H5Tget_native_type(member_type_id, H5T_DIR_ASCEND); + member_offset = H5Tget_member_offset(datatype_id, (unsigned)i); + printf("member_offset: %i\n", member_offset); + memb_class = H5Tget_class(member_type_id); + switch (memb_class) { + case H5T_INTEGER: + /* convert unsigned char array to integer */ + break; + case H5T_FLOAT: + /* convert unsigned char array to double or float */ + + if (H5Tequal(native_mem_type_id, H5T_NATIVE_DOUBLE)) { + } + else if (H5Tequal(native_mem_type_id, H5T_NATIVE_FLOAT)) { + f.i = tmp_fill_buf[member_offset] | (tmp_fill_buf[member_offset + 1] << 8) | + (tmp_fill_buf[member_offset + 2] << 16) | (tmp_fill_buf[member_offset + 3] << 24); + printf("Field %i Fill Value: %lf\n", i, f.f); + } + break; + + case H5T_STRING: + /* convert unsigned char array to string */ + strsize = H5Tget_size(member_type_id); + + printf("Field %i Fill Value: ", i); + for (j = 0; j < strsize; j++) + printf("%c", tmp_fill_buf[member_offset + j]); + printf("\n"); + break; + } diff --git a/hl/src/H5DOpublic.h b/hl/src/H5DOpublic.h index 88616a3..99358b3 100644 --- a/hl/src/H5DOpublic.h +++ b/hl/src/H5DOpublic.h @@ -18,6 +18,29 @@ extern "C" { #endif +/**\defgroup H5DO Optimizations + * + * <em>Bypassing default HDF5 behavior in order to optimize for specific + * use cases (H5DO)</em> + * + * HDF5 functions described is this section are implemented in the HDF5 High-level + * library as optimized functions. These functions generally require careful setup + * and testing as they enable an application to bypass portions of the HDF5 + * library’s I/O pipeline for performance purposes. + * + * These functions are distributed in the standard HDF5 distribution and are + * available any time the HDF5 High-level library is available. + * + * - \ref H5DOappend + * \n Appends data to a dataset along a specified dimension. + * - \ref H5DOread_chunk + * \n Reads a raw data chunk directly from a dataset in a file into a buffer (DEPRECATED) + * - \ref H5DOwrite_chunk + * \n Writes a raw data chunk from a buffer directly to a dataset in a file (DEPRECATED) + * . + * + */ + /*------------------------------------------------------------------------- * * "Optimized dataset" routines. @@ -25,6 +48,48 @@ extern "C" { *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5DO + * + * \brief Appends data to a dataset along a specified dimension. + * + * \param[in] dset_id Dataset identifier + * \param[in] dxpl_id Dataset transfer property list identifier + * \param[in] axis Dataset Dimension (0-based) for the append + * \param[in] extension Number of elements to append for the + * axis-th dimension + * \param[in] memtype The memory datatype identifier + * \param[in] buf Buffer with data for the append + * + * \return \herr_t + * + * \details The H5DOappend() routine extends a dataset by \p extension + * number of elements along a dimension specified by a + * dimension \p axis and writes \p buf of elements to the + * dataset. Dimension \p axis is 0-based. Elements’ type + * is described by \p memtype. + * + * This routine combines calling H5Dset_extent(), + * H5Sselect_hyperslab(), and H5Dwrite() into a single routine + * that simplifies application development for the common case + * of appending elements to an existing dataset. + * + * For a multi-dimensional dataset, appending to one dimension + * will write a contiguous hyperslab over the other dimensions. + * For example, if a 3-D dataset has dimension sizes (3, 5, 8), + * extending the 0th dimension (currently of size 3) by 3 will + * append 3*5*8 = 120 elements (which must be pointed to by the + * \p buffer parameter) to the dataset, making its final + * dimension sizes (6, 5, 8). + * + * If a dataset has more than one unlimited dimension, any of + * those dimensions may be appended to, although only along + * one dimension per call to H5DOappend(). + * + * \since 1.10.0 + * + */ H5_HLDLL herr_t H5DOappend(hid_t dset_id, hid_t dxpl_id, unsigned axis, size_t extension, hid_t memtype, const void *buf); @@ -35,8 +100,142 @@ H5_HLDLL herr_t H5DOappend(hid_t dset_id, hid_t dxpl_id, unsigned axis, size_t e #ifndef H5_NO_DEPRECATED_SYMBOLS /* Compatibility wrappers for functionality moved to H5D */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5DO + * + * \brief Writes a raw data chunk from a buffer directly to a dataset in a file. + * + * \param[in] dset_id Identifier for the dataset to write to + * \param[in] dxpl_id Transfer property list identifier for + * this I/O operation + * \param[in] filters Mask for identifying the filters in use + * \param[in] offset Logical position of the chunk’s first element + * in the dataspace + * \param[in] data_size Size of the actual data to be written in bytes + * \param[in] buf Buffer containing data to be written to the chunk + * + * \return \herr_t + * + * \deprecated This function was deprecated in favor of the function + * H5Dwrite_chunk() of HDF5-1.10.3. + * The functionality of H5DOwrite_chunk() was moved + * to H5Dwrite_chunk(). + * \deprecated For compatibility, this API call has been left as a stub which + * simply calls H5Dwrite_chunk(). New code should use H5Dwrite_chunk(). + * + * \details The H5DOwrite_chunk() writes a raw data chunk as specified by its + * logical \p offset in a chunked dataset \p dset_id from the application + * memory buffer \p buf to the dataset in the file. Typically, the data + * in \p buf is preprocessed in memory by a custom transformation, such as + * compression. The chunk will bypass the library’s internal data + * transfer pipeline, including filters, and will be written directly to the file. + * + * \p dxpl_id is a data transfer property list identifier. + * + * \p filters is a mask providing a record of which filters are used + * with the chunk. The default value of the mask is zero (\c 0), + * indicating that all enabled filters are applied. A filter is skipped + * if the bit corresponding to the filter’s position in the pipeline + * (<tt>0 ≤ position < 32</tt>) is turned on. This mask is saved + * with the chunk in the file. + * + * \p offset is an array specifying the logical position of the first + * element of the chunk in the dataset’s dataspace. The length of the + * offset array must equal the number of dimensions, or rank, of the + * dataspace. The values in \p offset must not exceed the dimension limits + * and must specify a point that falls on a dataset chunk boundary. + * + * \p data_size is the size in bytes of the chunk, representing the number of + * bytes to be read from the buffer \p buf. If the data chunk has been + * precompressed, \p data_size should be the size of the compressed data. + * + * \p buf is the memory buffer containing data to be written to the chunk in the file. + * + * \attention Exercise caution when using H5DOread_chunk() and H5DOwrite_chunk(), + * as they read and write data chunks directly in a file. + * H5DOwrite_chunk() bypasses hyperslab selection, the conversion of data + * from one datatype to another, and the filter pipeline to write the chunk. + * Developers should have experience with these processes before + * using this function. Please see + * <a href="https://portal.hdfgroup.org/display/HDF5/Using+the+Direct+Chunk+Write+Function"> + * Using the Direct Chunk Write Function</a> + * for more information. + * + * \note H5DOread_chunk() and H5DOwrite_chunk() are not + * supported under parallel and do not support variable length types. + * + * \par Example + * The following code illustrates the use of H5DOwrite_chunk to write + * an entire dataset, chunk by chunk: + * \snippet H5DO_examples.c H5DOwrite + * + * \version 1.10.3 Function deprecated in favor of H5Dwrite_chunk. + * + * \since 1.8.11 + */ H5_HLDLL herr_t H5DOwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, const hsize_t *offset, size_t data_size, const void *buf); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5DO + * + * \brief Reads a raw data chunk directly from a dataset in a file into a buffer. + * + * \param[in] dset_id Identifier for the dataset to be read + * \param[in] dxpl_id Transfer property list identifier for + * this I/O operation + * \param[in] offset Logical position of the chunk’s first + element in the dataspace + * \param[in,out] filters Mask for identifying the filters used + * with the chunk + * \param[in] buf Buffer containing the chunk read from + * the dataset + * + * \return \herr_t + * + * \deprecated This function was deprecated in favor of the function + * H5Dread_chunk() as of HDF5-1.10.3. + * In HDF5 1.10.3, the functionality of H5DOread_chunk() + * was moved to H5Dread_chunk(). + * \deprecated For compatibility, this API call has been left as a stub which + * simply calls H5Dread_chunk(). New code should use H5Dread_chunk(). + * + * \details The H5DOread_chunk() reads a raw data chunk as specified + * by its logical \p offset in a chunked dataset \p dset_id + * from the dataset in the file into the application memory + * buffer \p buf. The data in \p buf is read directly from the file + * bypassing the library’s internal data transfer pipeline, + * including filters. + * + * \p dxpl_id is a data transfer property list identifier. + * + * The mask \p filters indicates which filters are used with the + * chunk when written. A zero value indicates that all enabled filters + * are applied on the chunk. A filter is skipped if the bit corresponding + * to the filter’s position in the pipeline + * (<tt>0 ≤ position < 32</tt>) is turned on. + * + * \p offset is an array specifying the logical position of the first + * element of the chunk in the dataset’s dataspace. The length of the + * offset array must equal the number of dimensions, or rank, of the + * dataspace. The values in \p offset must not exceed the dimension + * limits and must specify a point that falls on a dataset chunk boundary. + * + * \p buf is the memory buffer containing the chunk read from the dataset + * in the file. + * + * \par Example + * The following code illustrates the use of H5DOread_chunk() + * to read a chunk from a dataset: + * \snippet H5DO_examples.c H5DOread + * + * \version 1.10.3 Function deprecated in favor of H5Dread_chunk. + * + * \since 1.10.2, 1.8.19 + */ H5_HLDLL herr_t H5DOread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, uint32_t *filters /*out*/, void *buf /*out*/); diff --git a/hl/src/H5DSpublic.h b/hl/src/H5DSpublic.h index 979a173..1dd0781 100644 --- a/hl/src/H5DSpublic.h +++ b/hl/src/H5DSpublic.h @@ -19,33 +19,393 @@ #define REFERENCE_LIST "REFERENCE_LIST" #define DIMENSION_LABELS "DIMENSION_LABELS" +/** + * \brief Prototype for H5DSiterate_scales() operator + * + */ +//! <!-- [H5DS_iterate_t_snip] --> typedef herr_t (*H5DS_iterate_t)(hid_t dset, unsigned dim, hid_t scale, void *visitor_data); +//! <!-- [H5DS_iterate_t_snip] --> #ifdef __cplusplus extern "C" { #endif +/**\defgroup H5DS Dimension Scales + * + * <em>Creating and manipulating HDF5 datasets that are associated with + * the dimension of another HDF5 dataset (H5DS)</em> + * + * \note \Bold{Programming hints:} + * \note To use any of these functions or subroutines, + * you must first include the relevant include file (C) or + * module (Fortran) in your application. + * \note The following line includes the HDF5 Dimension Scale package, + * H5DS, in C applications: + * \code #include "hdf5_hl.h" \endcode + * \note This line includes the H5DS module in Fortran applications: + * \code use h5ds \endcode + * + * - \ref H5DSwith_new_ref + * \n Determines if new references are used with dimension scales. + * - \ref H5DSattach_scale + * \n Attach dimension scale dsid to dimension idx of dataset did. + * - \ref H5DSdetach_scale + * \n Detach dimension scale dsid from the dimension idx of Dataset did. + * - \ref H5DSget_label + * \n Read the label for dimension idx of did into buffer label. + * - \ref H5DSget_num_scales + * \n Determines how many Dimension Scales are attached + * to dimension idx of did. + * - \ref H5DSget_scale_name + * \n Retrieves name of scale did into buffer name. + * - \ref H5DSis_attached + * \n Report if dimension scale dsid is currently attached + * to dimension idx of dataset did. + * - \ref H5DSis_scale + * \n Determines whether dset is a Dimension Scale. + * - \ref H5DSiterate_scales + * \n Iterates the operation visitor through the scales + * attached to dimension dim. + * - \ref H5DSset_label + * \n Set label for the dimension idx of did to the value label. + * - \ref H5DSset_scale + * \n Convert dataset dsid to a dimension scale, + * with optional name, dimname. + * . + * + */ + +/* THIS IS A NEW ROUTINE NOT ON OLD PORTAL */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Determines if new references are used with dimension scales. + * + * \param[in] obj_id Object identifier + * \param[out] with_new_ref New references are used or not + * + * \return \herr_t + * + * \details H5DSwith_new_ref() takes any object identifier and checks + * if new references are used for dimension scales. Currently, + * new references are used when non-native VOL connector is + * used or when H5_DIMENSION_SCALES_WITH_NEW_REF is set up + * via configure option. + * + */ H5_HLDLL herr_t H5DSwith_new_ref(hid_t obj_id, hbool_t *with_new_ref); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Attach dimension scale \p dsid to dimension \p idx of + * dataset did. + * + * \param[in] did The dataset + * \param[in] dsid The scale to be attached + * \param[in] idx The dimension of \p did that \p dsid is associated with + * + * \return \herr_t + * + * \details Define Dimension Scale \p dsid to be associated with + * dimension \p idx of dataset \p did. + * + * Entries are created in the #DIMENSION_LIST and + * #REFERENCE_LIST attributes, as defined in section 4.2 of + * <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf"> + * HDF5 Dimension Scale Specification</a>. + * + * Fails if: + * - Bad arguments + * - If \p dsid is not a Dimension Scale + * - If \p did is a Dimension Scale + * (A Dimension Scale cannot have scales.) + * + * \note The Dimension Scale \p dsid can be attached to the + * same dimension more than once, which has no effect. + */ H5_HLDLL herr_t H5DSattach_scale(hid_t did, hid_t dsid, unsigned int idx); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Detach dimension scale \p dsid from the dimension \p idx of dataset \p did. + * + * \param[in] did The dataset + * \param[in] dsid The scale to be detached + * \param[in] idx The dimension of \p did to detach + * + * \return \herr_t + * + * \details If possible, deletes association of Dimension Scale \p dsid with + * dimension \p idx of dataset \p did. This deletes the entries in the + * #DIMENSION_LIST and #REFERENCE_LIST attributes, + * as defined in section 4.2 of + * <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf"> + * HDF5 Dimension Scale Specification</a>. + * + * Fails if: + * - Bad arguments + * - The dataset \p did or \p dsid do not exist + * - The \p dsid is not a Dimension Scale + * - \p dsid is not attached to \p did + * . + * + * \note A scale may be associated with more than dimension of the + * same dataset. If so, the detach operation only deletes one + * of the associations, for \p did. + * + */ H5_HLDLL herr_t H5DSdetach_scale(hid_t did, hid_t dsid, unsigned int idx); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Convert dataset \p dsid to a dimension scale, + * with optional name, \p dimname. + * + * \param[in] dsid The dataset to be made a Dimemsion Scale + * \param[in] dimname The dimension name (optional), NULL if the + * dimension has no name. + * + * \return \herr_t + * + * \details The dataset \p dsid is converted to a Dimension Scale dataset, + * as defined above. Creates the CLASS attribute, set to the value + * "DIMENSION_SCALE" and an empty #REFERENCE_LIST attribute, + * as described in + * <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf"> + * HDF5 Dimension Scale Specification</a>. + * (PDF, see section 4.2). + * + * If \p dimname is specified, then an attribute called NAME + * is created, with the value \p dimname. + * + * Fails if: + * - Bad arguments + * - If \p dsid is already a scale + * - If \p dsid is a dataset which already has dimension scales + * . + * + * If the dataset was created with the Table, Image, or Palette interface [9], + * it is not recommended to convert to a Dimension Scale. + * (These Datasets will have a CLASS Table, Image, or Palette.) + * + * \todo what is [9] after Palette interface? + */ H5_HLDLL herr_t H5DSset_scale(hid_t dsid, const char *dimname); -H5_HLDLL int H5DSget_num_scales(hid_t did, unsigned int dim); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Determines how many Dimension Scales are attached + * to dimension \p idx of \p did. + * + * \param[in] did The dataset to query + * \param[in] idx The dimension of \p did to query + * + * \return Returns the number of Dimension Scales associated + * with \p did, if successful, otherwise returns a + * negative value. + * + * \details H5DSget_num_scales() determines how many Dimension + * Scales are attached to dimension \p idx of + * dataset \p did. + * + */ +H5_HLDLL int H5DSget_num_scales(hid_t did, unsigned int idx); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Set label for the dimension \p idx of \p did + * to the value \p label. + * + * \param[in] did The dataset + * \param[in] idx The dimension + * \param[in] label The label + * + * \return \herr_t + * + * \details Sets the #DIMENSION_LABELS for dimension \p idx of + * dataset \p did. If the dimension had a label, + * the new value replaces the old. + * + * Fails if: + * - Bad arguments + * . + */ H5_HLDLL herr_t H5DSset_label(hid_t did, unsigned int idx, const char *label); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Read the label for dimension \p idx of \p did into buffer \p label. + * + * \param[in] did The dataset + * \param[in] idx The dimension + * \param[out] label The label + * \param[in] size The length of the label buffer + * + * \return Upon success, size of label or zero if no label found. + * Negative if fail. + * + * \details Returns the value of the #DIMENSION_LABELS for + * dimension \p idx of dataset \p did, if set. + * Up to \p size characters of the name are copied into + * the buffer \p label. If the label is longer than + * \p size, it will be truncated to fit. The parameter + * \p size is set to the size of the returned \p label. + * + * If \p did has no label, the return value of + * \p label is NULL. + * + * Fails if: + * - Bad arguments + * . + */ H5_HLDLL ssize_t H5DSget_label(hid_t did, unsigned int idx, char *label, size_t size); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Retrieves name of scale \p did into buffer \p name. + * + * \param[in] did Dimension scale identifier + * \param[out] name Buffer to contain the returned name + * \param[in] size Size in bytes, of the \p name buffer + * + * \return Upon success, the length of the scale name or zero if no name found. + * Negative if fail. + * + * \details H5DSget_scale_name() retrieves the name attribute + * for scale \p did. + * + * Up to \p size characters of the scale name are returned + * in \p name; additional characters, if any, are not returned + * to the user application. + * + * If the length of the name, which determines the required value of + * \p size, is unknown, a preliminary H5DSget_scale_name() call can + * be made by setting \p name to NULL. The return value of this call + * will be the size of the scale name; that value plus one (1) can then + * be assigned to \p size for a second H5DSget_scale_name() call, + * which will retrieve the actual name. (The value passed in with the + * parameter \p size must be one greater than size in bytes of the actual + * name in order to accommodate the null terminator; + * if \p size is set to the exact size of the name, the last byte + * passed back will contain the null terminator and the last character + * will be missing from the name passed back to the calling application.) + */ H5_HLDLL ssize_t H5DSget_scale_name(hid_t did, char *name, size_t size); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Determines whether \p did is a Dimension Scale. + * + * \param[in] did The dataset to query + * + * \return \htri_t + * + * \details H5DSis_scale() determines if \p did is a Dimension Scale, + * i.e., has class="DIMENSION_SCALE"). + * + */ H5_HLDLL htri_t H5DSis_scale(hid_t did); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Iterates the operation visitor through the scales + * attached to dimension \p dim. + * + * \param[in] did The dataset + * \param[in] dim The dimension of dataset \p did + * \param[in,out] idx Input the index to start iterating, + * output the next index to visit. + * If NULL, start at the first position. + * \param[in] visitor The visitor function + * \param[in] visitor_data Arbitrary data to pass to the + * visitor function + * + * \return Returns the return value of the last operator if it was + * non-zero, or zero if all scales were processed. + * + * \details H5DSiterate_scales() iterates over the scales attached to + * dimension \p dim of dataset \p did. For each scale in the + * list, the \p visitor_data and some additional information, + * specified below, are passed to the \p visitor function. + * The iteration begins with the \p idx object in the + * group and the next element to be processed by the operator + * is returned in \p idx. If \p idx is NULL, then the + * iterator starts at the first group member; since no + * stopping point is returned in this case, + * the iterator cannot be restarted if one of the calls + * to its operator returns non-zero. + * + * The prototype for \ref H5DS_iterate_t is: + * \snippet this H5DS_iterate_t_snip + * + * The operation receives the Dimension Scale dataset + * identifier, \p scale, and the pointer to the operator + * data passed in to H5DSiterate_scales(), \p visitor_data. + * + * The return values from an operator are: + * + * - Zero causes the iterator to continue, returning zero + * when all group members have been processed. + * - Positive causes the iterator to immediately return that + * positive value, indicating short-circuit success. + * The iterator can be restarted at the next group member. + * - Negative causes the iterator to immediately return + * that value, indicating failure. The iterator can be + * restarted at the next group member. + * . + * + * H5DSiterate_scales() assumes that the scales of the + * dimension identified by \p dim remain unchanged through + * the iteration. If the membership changes during the iteration, + * the function's behavior is undefined. + */ H5_HLDLL herr_t H5DSiterate_scales(hid_t did, unsigned int dim, int *idx, H5DS_iterate_t visitor, void *visitor_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Report if dimension scale \p dsid is currently attached to + * dimension \p idx of dataset \p did. + * + * \param[in] did The dataset + * \param[in] dsid The scale to be attached + * \param[in] idx The dimension of \p did that \p dsid is associated with + * + * \return \htri_t + * + * \details Report if dimension scale \p dsid is currently attached to + * dimension \p idx of dataset \p did. + * + * Fails if: + * - Bad arguments + * - If \p dsid is not a Dimension Scale + * - The \p dsid is not a Dimension Scale + * - If \p did is a Dimension Scale (A Dimension Scale cannot have scales.) + * . + * + */ H5_HLDLL htri_t H5DSis_attached(hid_t did, hid_t dsid, unsigned int idx); #ifdef __cplusplus diff --git a/hl/src/H5IMpublic.h b/hl/src/H5IMpublic.h index 2843942..2129509 100644 --- a/hl/src/H5IMpublic.h +++ b/hl/src/H5IMpublic.h @@ -18,33 +18,326 @@ extern "C" { #endif +/**\defgroup H5IM Images + * + * <em>Creating and manipulating HDF5 datasets intended to be + * interpreted as images (H5IM)</em> + * + * The specification for the Images API is presented in another + * document: \ref IMG + * This version of the API is primarily concerned with two dimensional raster + * data similar to HDF4 Raster Images. + * The HDF5 Images API uses the \ref H5LT HDF5 API. + * + * \note \Bold{Programming hints:} + * \note To use any of these functions or subroutines, + * you must first include the relevant include file (C) or + * module (Fortran) in your application. + * \note The following line includes the HDF5 Images package, H5IM, + * in C applications: + * \code #include "hdf5_hl.h" \endcode + * \note This line includes the H5IM module in Fortran applications: + * \code use h5im \endcode + * + * - \ref H5IMget_image_info + * \n Gets information about an image dataset (dimensions, + * interlace mode and number of associated palettes). + * - \ref H5IMget_npalettes + * \n Gets the number of palettes associated to an image. + * - \ref H5IMget_palette + * \n Gets the palette dataset. + * - \ref H5IMget_palette_info + * \n Gets information about a palette dataset (dimensions). + * - \ref H5IMis_image + * \n Inquires if a dataset is an image + * - \ref H5IMis_palette + * \n Inquires if a dataset is a palette. + * - \ref H5IMlink_palette + * \n Attaches a palette to an image. + * - \ref H5IMmake_image_8bit + * \n Creates and writes an image. + * - \ref H5IMmake_image_24bit + * \n Creates and writes a true color image. + * - \ref H5IMmake_palette + * \n Creates and writes a palette. + * - \ref H5IMread_image + * \n Reads image data from disk. + * - \ref H5IMunlink_palette + * \n Dettaches a palette from an image. + * . + * + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Creates and writes an image. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[in] width The width of the image + * \param[in] height The height of the image + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5IMmake_image_8bit() creates and writes a dataset named + * \p dset_name attached to the file or group specified by the + * identifier \p loc_id. Attributes conforming to the HDF5 Image + * and Palette specification for an indexed image are attached to + * the dataset, thus identifying it as an image. The image data is + * of the type #H5T_NATIVE_UCHAR. An indexed image is an image in + * which each each pixel information storage is an index to a + * table palette. + * + */ H5_HLDLL herr_t H5IMmake_image_8bit(hid_t loc_id, const char *dset_name, hsize_t width, hsize_t height, const unsigned char *buffer); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Creates and writes a true color image. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[in] width The width of the image + * \param[in] height The height of the image + * \param[in] interlace String defining the interlace mode + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5IMmake_image_24bit() creates and writes a dataset named + * \p dset_name attached to the file or group specified by the + * identifier \p loc_id. This function defines a true color image + * conforming to the HDF5 Image and Palette specification. + * The function assumes that the image data is of the type + * #H5T_NATIVE_UCHAR. + * + * A true color image is an image where the pixel storage contains + * several color planes. In a 24 bit RGB color model, these planes + * are red, green and blue. In a true color image the stream of bytes + * can be stored in several different ways, thus defining the + * interlace (or interleaving) mode. The 2 most used types of interlace mode + * are interlace by pixel and interlace by plane. In the 24 bit RGB color + * model example, interlace by plane means all the red components for the + * entire dataset are stored first, followed by all the green components, + * and then by all the blue components. Interlace by pixel in this example + * means that for each pixel the sequence red, green, blue is defined. + * In this function, the interlace mode is defined in the parameter + * \p interlace, a string that can have the values INTERLACE_PIXEL + * or INTERLACE_PLANE. + * + */ H5_HLDLL herr_t H5IMmake_image_24bit(hid_t loc_id, const char *dset_name, hsize_t width, hsize_t height, const char *interlace, const unsigned char *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Gets information about an image dataset + * (dimensions, interlace mode and number of associated palettes). + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset + * \param[out] width The width of the image + * \param[out] height The height of the image + * \param[out] planes The number of color planes of the image + * \param[out] interlace The interlace mode of the image + * \param[out] npals The number of palettes associated to the image + * + * \return \herr_t + * + * \details H5IMget_image_info() gets information about an image + * named \p dset_name attached to the file or group specified + * by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5IMget_image_info(hid_t loc_id, const char *dset_name, hsize_t *width, hsize_t *height, hsize_t *planes, char *interlace, hssize_t *npals); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Reads image data from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[out] buffer Buffer with data to store the image + * + * \return \herr_t + * + * \details H5IMread_image() reads a dataset named \p dset_name + * attached to the file or group specified by the + * identifier \p loc_id. + * + */ H5_HLDLL herr_t H5IMread_image(hid_t loc_id, const char *dset_name, unsigned char *buffer); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Creates and writes a palette. + * + * \fg_loc_id + * \param[in] pal_name The name of the palette + * \param[in] pal_dims An array of the size of the palette dimensions + * \param[in] pal_data Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5IMmake_palette() creates and writes a dataset + * named \p pal_name. Attributes conforming to the HDF5 Image and + * Palette specification are attached to the dataset, thus + * identifying it as a palette. The palette data is of the + * type #H5T_NATIVE_UCHAR. + * + */ H5_HLDLL herr_t H5IMmake_palette(hid_t loc_id, const char *pal_name, const hsize_t *pal_dims, const unsigned char *pal_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Attaches a palette to an image. + * + * \fg_loc_id + * \param[in] image_name The name of the dataset to attach the palette to + * \param[in] pal_name The name of the palette + * + * \return \herr_t + * + * \details H5IMlink_palette() attaches a palette named \p pal_name + * to an image specified by \p image_name. The image dataset + * may or not already have an attached palette. If it has, + * the array of palette references is extended to hold the reference + * to the new palette. + * + */ H5_HLDLL herr_t H5IMlink_palette(hid_t loc_id, const char *image_name, const char *pal_name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Dettaches a palette from an image. + * + * \fg_loc_id + * \param[in] image_name The name of the image dataset + * \param[in] pal_name The name of the palette + * + * \return \herr_t + * + * \details H5IMunlink_palette() dettaches a palette from an image + * specified by \p image_name. + * + */ H5_HLDLL herr_t H5IMunlink_palette(hid_t loc_id, const char *image_name, const char *pal_name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Gets the number of palettes associated to an image. + * + * \fg_loc_id + * \param[in] image_name The name of the image dataset + * \param[out] npals The number of palettes + * + * \return \herr_t + * + * \details H5IMget_npalettes() gets the number of palettes associated to + * an image specified by \p image_name. + * + */ H5_HLDLL herr_t H5IMget_npalettes(hid_t loc_id, const char *image_name, hssize_t *npals); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Gets information about a palette dataset (dimensions). + * + * \fg_loc_id + * \param[in] image_name The name of the image dataset + * \param[in] pal_number The zero based index that identifies + * the palette + * \param[out] pal_dims The dimensions of the palette dataset + * + * \return \herr_t + * + * \details H5IMget_palette_info() gets the dimensions of the palette + * dataset identified by \p pal_number (a zero based index) + * associated to an image specified by \p image_name. + * + */ H5_HLDLL herr_t H5IMget_palette_info(hid_t loc_id, const char *image_name, int pal_number, hsize_t *pal_dims); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Gets the palette dataset. + * + * \fg_loc_id + * \param[in] image_name The name of the image dataset + * \param[in] pal_number The zero based index that identifies + * the palette + * \param[out] pal_data The palette dataset + * + * \return \herr_t + * + * \details H5IMget_palette() gets the palette dataset identified + * by \p pal_number (a zero based index) associated to an + * image specified by \p image_name. + * + */ H5_HLDLL herr_t H5IMget_palette(hid_t loc_id, const char *image_name, int pal_number, unsigned char *pal_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Inquires if a dataset is an image. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset + * + * \return \htri_t + * + * \details H5IMis_image() inquires if a dataset named \p dset_name, + * attached to the file or group specified by the identifier + * \p loc_id, is an image based on the HDF5 Image and Palette + * Specification. + * + */ H5_HLDLL herr_t H5IMis_image(hid_t loc_id, const char *dset_name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Inquires if a dataset is a palette + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset + * + * \return \htri_t + * + * \details H5IMis_palette() inquires if a dataset named \p dset_name, + * attached to the file or group specified by the + * identifier \p loc_id, is a palette based on the HDF5 + * Image and Palette Specification. + * + */ H5_HLDLL herr_t H5IMis_palette(hid_t loc_id, const char *dset_name); #ifdef __cplusplus diff --git a/hl/src/H5LDpublic.h b/hl/src/H5LDpublic.h index 011b208..826da40 100644 --- a/hl/src/H5LDpublic.h +++ b/hl/src/H5LDpublic.h @@ -18,8 +18,149 @@ extern "C" { #endif +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Retrieves the current dimension sizes of a dataset. + * + * \param[in] did The dataset identifier + * \param[out] cur_dims The current dimension sizes of the dataset + * + * \return \herr_t + * + * \details H5LDget_dset_dims() retrieves the current dimension sizes + * for the dataset \p did through the parameter \p cur_dims. + * It will return failure if \p cur_dims is NULL. + * + * \note See Also: + * \note Dataset Watch functions (used with \ref h5watch): + * - H5LDget_dset_dims() + * - H5LDget_dset_elmts() + * - H5LDget_dset_type_size() + * . + * + * \par Example: + * See the example code in H5LDget_dset_elmts() for usage of this routine. + * + * \since 1.10.0 + * + */ H5_HLDLL herr_t H5LDget_dset_dims(hid_t did, hsize_t *cur_dims); + +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Returns the size in bytes of the dataset’s datatype + * + * \param[in] did The dataset identifier + * \param[in] fields The pointer to a comma-separated list of fields for a compound datatype + * + * \return If successful, returns the size in bytes of the + * dataset’s datatype. Otherwise, returns 0. + * + * \details H5LDget_dset_type_size() allows the user to find out the datatype + * size for the dataset associated with \p did. If the + * parameter \p fields is NULL, this routine just returns the size + * of the dataset’s datatype. If the dataset has a compound datatype + * and \p fields is non-NULL, this routine returns the size of the + * datatype(s) for the selected fields specified in \p fields. + * Note that ’,’ is the separator for the fields of a compound + * datatype while ’.’ (dot) is the separator for a nested field. + * Use a backslash ( \ ) to escape characters in field names that + * conflict with these two separators. + * + * \note See Also: + * \note Dataset Watch functions (used with \ref h5watch): + * - H5LDget_dset_dims() + * - H5LDget_dset_elmts() + * - H5LDget_dset_type_size() + * . + * + * \par Example: + * See the example code in H5LDget_dset_elmts() for usage of this routine. + * + * \since 1.10.0 + * + */ H5_HLDLL size_t H5LDget_dset_type_size(hid_t did, const char *fields); + +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Retrieves selected data from the dataset + * + * \param[in] did The dataset identifier + * \param[in] prev_dims The previous dimension size of the dataset + * \param[in] cur_dims The current dimension sizes of the dataset + * \param[in] fields A string containing a comma-separated list + * of fields for a compound datatype + * \param[out] buf Buffer for storing data retrieved from the + * dataset + * + * \return \herr_t + * + * \details H5LDget_dset_dims() retrieves selected data of the dataset + * \p did and stores the data in the parameter \p buf. + * The difference between the parameters \p prev_dims and + * \p cur_dims indicates the dimension sizes of the data to be + * selected from the dataset. Note that \p cur_dims must have + * at least one dimension whose size is greater than the + * corresponding dimension in \p prev_dims. Users can + * determine the size of buf by multipling the datatype + * size of the dataset by the number of selected elements. + * + * If the parameter \p fields is NULL, this routine returns + * data for the selected elements of the dataset. If \p fields + * is not NULL and the dataset has a compound datatype, \p fields + * is a string containing a comma-separated list of fields. + * Each name in \p fields specifies a field in the compound + * datatype, and this routine returns data of the selected fields + * for the dataset's selected elements. Note that ’,’ is the + * separator for the fields of a compound datatype while + * ’.’ is the separator for a nested field. Use backslash to + * escape characters in field names that conflict with these + * two separators. + * + * \note See Also: + * \note Dataset Watch functions (used with \ref h5watch): + * - H5LDget_dset_dims() + * - H5LDget_dset_elmts() + * - H5LDget_dset_type_size() + * . + * + * \par Examples: + * + * For the first example, \c DSET1 is a two-dimensional chunked dataset with atomic type defined below: + * \snippet H5LDget_dset_elmts.c first_declare + * + * The following coding sample illustrates the reading of + * data elements appended to the dataset \c DSET1: + * \snippet H5LDget_dset_elmts.c first_reading + * + * The output buffer will contain data elements selected from + * \c DSET1 as follows: + * \snippet H5LDget_dset_elmts.c first_output + * + * For the second example, DSET2 is a one-dimensional chunked dataset + * with compound type defined below: + * \snippet H5LDget_dset_elmts.c second_declare + * + * The following coding sample illustrates the reading of data elements + * appended to the dataset \c DSET2 with compound datatype. + * This example selects only 2 fields: the fourth field \c d and a + * subfield of the sixth field \c s2.c: + * \snippet H5LDget_dset_elmts.c second_reading + * + * The output buffer will contain data for \c d and \c s2.c + * selected from \c DSET2 as follows: + * \snippet H5LDget_dset_elmts.c second_output + * + * \since 1.10.0 + * + */ H5_HLDLL herr_t H5LDget_dset_elmts(hid_t did, const hsize_t *prev_dims, const hsize_t *cur_dims, const char *fields, void *buf); diff --git a/hl/src/H5LTpublic.h b/hl/src/H5LTpublic.h index a6c7c84..2f87944 100644 --- a/hl/src/H5LTpublic.h +++ b/hl/src/H5LTpublic.h @@ -35,6 +35,116 @@ typedef enum H5LT_lang_t { extern "C" { #endif +/**\defgroup H5LT Lite + * <em>Functions used to simplify creating and manipulating datasets, + * attributes and other features (H5LT, H5LD)</em> + * + * The HDF5 Lite API consists of higher-level functions which do + * more operations per call than the basic HDF5 interface. + * The purpose is to wrap intuitive functions around certain sets + * of features in the existing APIs. + * It has the following sets of functions listed below. + * + * \note \Bold{Programming hints:} + * \note To use any of these functions or subroutines, + * you must first include the relevant include file (C) or + * module (Fortran) in your application. + * \note The following line includes the HDF5 Lite package, H5LT, + * in C applications: + * \code #include "hdf5_hl.h" \endcode + * \note This line includes the H5LT module in Fortran applications: + * \code use h5lt \endcode + * + * - Dataset Functions + * - Make dataset functions + * - \ref H5LTmake_dataset + * - \ref H5LTmake_dataset_char + * - \ref H5LTmake_dataset_short + * - \ref H5LTmake_dataset_int + * - \ref H5LTmake_dataset_long + * - \ref H5LTmake_dataset_float + * - \ref H5LTmake_dataset_double + * - \ref H5LTmake_dataset_string + * . + * - Read dataset functions + * - \ref H5LTread_dataset + * - \ref H5LTread_dataset_char + * - \ref H5LTread_dataset_short + * - \ref H5LTread_dataset_int + * - \ref H5LTread_dataset_long + * - \ref H5LTread_dataset_float + * - \ref H5LTread_dataset_double + * - \ref H5LTread_dataset_string + * . + * - Query dataset functions + * - \ref H5LTfind_dataset + * - \ref H5LTget_dataset_ndims + * - \ref H5LTget_dataset_info + * . + * - Dataset watch functions + * - \ref H5LDget_dset_dims + * - \ref H5LDget_dset_elmts + * - \ref H5LDget_dset_type_size + * . + * . + * - Attribute Functions + * - Set attribute functions + * - \ref H5LTset_attribute_string + * - \ref H5LTset_attribute_char + * - \ref H5LTset_attribute_uchar + * - \ref H5LTset_attribute_short + * - \ref H5LTset_attribute_ushort + * - \ref H5LTset_attribute_int + * - \ref H5LTset_attribute_uint + * - \ref H5LTset_attribute_long + * - \ref H5LTset_attribute_long_long + * - \ref H5LTset_attribute_ulong + * - \ref H5LTset_attribute_ullong + * - \ref H5LTset_attribute_float + * - \ref H5LTset_attribute_double + * - \ref H5LTset_attribute_f (fortran ONLY) + * . + * - Get attribute functions + * - \ref H5LTget_attribute + * - \ref H5LTget_attribute_string + * - \ref H5LTget_attribute_char + * - \ref H5LTget_attribute_uchar + * - \ref H5LTget_attribute_short + * - \ref H5LTget_attribute_ushort + * - \ref H5LTget_attribute_int + * - \ref H5LTget_attribute_uint + * - \ref H5LTget_attribute_long + * - \ref H5LTget_attribute_long_long + * - \ref H5LTget_attribute_ulong + * - \ref H5LTget_attribute_ullong + * - \ref H5LTget_attribute_float + * - \ref H5LTget_attribute_double + * . + * - Query attribute functions + * - \ref H5LTfind_attribute + * - \ref H5LTget_attribute_info + * - \ref H5LTget_attribute_ndims + * . + * . + * - Datatype Functions + * - Datatype translation functions + * - \ref H5LTtext_to_dtype + * - \ref H5LTdtype_to_text + * . + * . + * - File image function + * - Open file image function + * - \ref H5LTopen_file_image + * . + * . + * - Path and object function + * - Query path and object function + * - \ref H5LTpath_valid + * . + * . + * . + */ + /*------------------------------------------------------------------------- * * Make dataset functions @@ -42,27 +152,214 @@ extern "C" { *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset of a type \p type_id. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] type_id Identifier of the datatype to use when creating the dataset + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset() creates and writes a dataset named + * \p dset_name attached to the object specified by the + * identifier \p loc_id. + * + * The parameter \p type_id can be any valid HDF5 Prdefined \ref PDTNAT; + * For example, setting \p type_id to #H5T_NATIVE_INT will result in a dataset + * of <em>signed \e integer datatype</em>. + * + * \version 1.10.0 Fortran 2003 subroutine added to accept a C address of the data buffer. + * \version 1.8.7 Fortran subroutine modified in this release to accommodate arrays + * with more than three dimensions. + * + */ H5_HLDLL herr_t H5LTmake_dataset(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, hid_t type_id, const void *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_char() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset’s datatype will be \e character, #H5T_NATIVE_CHAR. + * + */ H5_HLDLL herr_t H5LTmake_dataset_char(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, const char *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_short() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset’s datatype will be <em>short signed integer</em>, + * #H5T_NATIVE_SHORT. + * + */ H5_HLDLL herr_t H5LTmake_dataset_short(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, const short *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_int() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset’s datatype will be <em>native signed integer</em>, + * #H5T_NATIVE_INT. + * + * \version Fortran subroutine modified in this release to accommodate + * arrays with more than three dimensions. + * + */ H5_HLDLL herr_t H5LTmake_dataset_int(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, const int *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_long() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset’s datatype will be <em>long signed integer</em>, + * #H5T_NATIVE_LONG. + * + */ H5_HLDLL herr_t H5LTmake_dataset_long(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, const long *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_float() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset’s datatype will be <em>native floating point</em>, + * #H5T_NATIVE_FLOAT. + * + * \version 1.8.7 Fortran subroutine modified in this release to accommodate + * arrays with more than three dimensions. + * + */ H5_HLDLL herr_t H5LTmake_dataset_float(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, const float *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_double() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset’s datatype will be + * <em>native floating-point double</em>, #H5T_NATIVE_DOUBLE. + * + * \version 1.8.7 Fortran subroutine modified in this release to accommodate + * arrays with more than three dimensions. + * + */ H5_HLDLL herr_t H5LTmake_dataset_double(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, const double *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset with string datatype. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[in] buf Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_string() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset’s datatype will be <em>C string</em>, #H5T_C_S1. + * + */ H5_HLDLL herr_t H5LTmake_dataset_string(hid_t loc_id, const char *dset_name, const char *buf); /*------------------------------------------------------------------------- @@ -72,20 +369,169 @@ H5_HLDLL herr_t H5LTmake_dataset_string(hid_t loc_id, const char *dset_name, con *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[in] type_id Identifier of the datatype to use when reading + * the dataset + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * + * \version 1.10.0 Fortran 2003 subroutine added to accept a C + * address of the data buffer. + * \version 1.8.7 Fortran subroutine modified in this release to + * accommodate arrays with more than three dimensions. + * + */ H5_HLDLL herr_t H5LTread_dataset(hid_t loc_id, const char *dset_name, hid_t type_id, void *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_char() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_NATIVE_CHAR. + * + */ H5_HLDLL herr_t H5LTread_dataset_char(hid_t loc_id, const char *dset_name, char *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_short() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_NATIVE_SHORT. + * + */ H5_HLDLL herr_t H5LTread_dataset_short(hid_t loc_id, const char *dset_name, short *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_int() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_NATIVE_INT. + * + * \version 1.8.7 Fortran subroutine modified in this release to + * accommodate arrays with more than three dimensions. + * + */ H5_HLDLL herr_t H5LTread_dataset_int(hid_t loc_id, const char *dset_name, int *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_long() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_NATIVE_LONG. + * + */ H5_HLDLL herr_t H5LTread_dataset_long(hid_t loc_id, const char *dset_name, long *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_float() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_NATIVE_FLOAT. + * + * \version 1.8.7 Fortran subroutine modified in this release to + * accommodate arrays with more than three dimensions. + */ H5_HLDLL herr_t H5LTread_dataset_float(hid_t loc_id, const char *dset_name, float *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_double() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_NATIVE_DOUBLE. + * + * \version 1.8.7 Fortran subroutine modified in this release to + * accommodate arrays with more than three dimensions. + */ H5_HLDLL herr_t H5LTread_dataset_double(hid_t loc_id, const char *dset_name, double *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buf Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_string() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_C_S1. + * + */ H5_HLDLL herr_t H5LTread_dataset_string(hid_t loc_id, const char *dset_name, char *buf); /*------------------------------------------------------------------------- @@ -95,11 +541,67 @@ H5_HLDLL herr_t H5LTread_dataset_string(hid_t loc_id, const char *dset_name, cha *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Gets the dimensionality of a dataset + * + * \param[in] loc_id Identifier of the object to + * locate the dataset within + * \param[in] dset_name The dataset name + * \param[out] rank The dimensionality of the dataset + * + * \return \herr_t + * + * \details H5LTget_dataset_ndims() gets the dimensionality of a dataset + * named \p dset_name exists attached to the object \p loc_id. + * + */ H5_HLDLL herr_t H5LTget_dataset_ndims(hid_t loc_id, const char *dset_name, int *rank); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Retrieves information about a dataset + * + * \param[in] loc_id Identifier of the object to locate + * the dataset within + * \param[in] dset_name The dataset name + * \param[out] dims The dimensions of the dataset + * \param[out] type_class The class identifier. #H5T_class_t is defined in + * H5Tpublic.h. See H5Tget_class() for a list + * of class types. + * \param[out] type_size The size of the datatype in bytes + * + * \return \herr_t + * + * \details H5LTget_dataset_info() retrieves information about a dataset + * named \p dset_name attached to the object \p loc_id. + * + */ H5_HLDLL herr_t H5LTget_dataset_info(hid_t loc_id, const char *dset_name, hsize_t *dims, H5T_class_t *type_class, size_t *type_size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Determines whether a dataset exists. + * + * \param[in] loc_id Identifier of the group containing the dataset + * \param[in] name Dataset name + * + * \return \htri_t + * + * \details H5LTfind_dataset() determines whether a dataset named + * \p name exists in the group specified by \p loc_id. + * + * \p loc_id must be a group identifier and \p name must + * specify a dataset that is a member of that group. + * + */ H5_HLDLL herr_t H5LTfind_dataset(hid_t loc_id, const char *name); /*------------------------------------------------------------------------- @@ -109,42 +611,343 @@ H5_HLDLL herr_t H5LTfind_dataset(hid_t loc_id, const char *name); *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a string attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] attr_data Buffer with data to be written to the attribute + * + * \return \herr_t + * + * \details H5LTset_attribute_string() creates and writes a string attribute + * named \p attr_name and attaches it to the object specified by + * the name \p obj_name. If the attribute already exists, + * it is overwritten. + * + */ H5_HLDLL herr_t H5LTset_attribute_string(hid_t loc_id, const char *obj_name, const char *attr_name, const char *attr_data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_char() creates and writes a numerical attribute + * named \p attr_name and attaches it to the object specified by the + * name \p obj_name. The attribute has a dimensionality of 1. + * The HDF5 datatype of the attribute is #H5T_NATIVE_CHAR. + * + */ H5_HLDLL herr_t H5LTset_attribute_char(hid_t loc_id, const char *obj_name, const char *attr_name, const char *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_uchar() creates and writes a numerical attribute + * named \p attr_name and attaches it to the object specified by the + * name \p obj_name. The attribute has a dimensionality of 1. + * The HDF5 datatype of the attribute is #H5T_NATIVE_UCHAR. + * + */ H5_HLDLL herr_t H5LTset_attribute_uchar(hid_t loc_id, const char *obj_name, const char *attr_name, const unsigned char *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_short() creates and writes a numerical attribute + * named \p attr_name and attaches it to the object specified by the + * name \p obj_name. The attribute has a dimensionality of 1. + * The HDF5 datatype of the attribute is #H5T_NATIVE_SHORT. + * + */ H5_HLDLL herr_t H5LTset_attribute_short(hid_t loc_id, const char *obj_name, const char *attr_name, const short *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_ushort() creates and writes a numerical attribute + * named \p attr_name and attaches it to the object specified by the + * name \p obj_name. The attribute has a dimensionality of 1. + * The HDF5 datatype of the attribute is #H5T_NATIVE_USHORT. + * + */ H5_HLDLL herr_t H5LTset_attribute_ushort(hid_t loc_id, const char *obj_name, const char *attr_name, const unsigned short *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_int() creates and writes a numerical integer + * attribute named \p attr_name and attaches it to the object + * specified by the name \p obj_name. The attribute has a + * dimensionality of 1. The HDF5 datatype of the attribute + * is #H5T_NATIVE_INT. + * + */ H5_HLDLL herr_t H5LTset_attribute_int(hid_t loc_id, const char *obj_name, const char *attr_name, const int *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_uint() creates and writes a numerical integer + * attribute named \p attr_name and attaches it to the object specified + * by the name \p obj_name. The attribute has a dimensionality of 1. + * The HDF5 datatype of the attribute is #H5T_NATIVE_UINT. + * + */ H5_HLDLL herr_t H5LTset_attribute_uint(hid_t loc_id, const char *obj_name, const char *attr_name, const unsigned int *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_long() creates and writes a numerical + * attribute named \p attr_name and attaches it to the object + * specified by the name \p obj_name. The attribute has a + * dimensionality of 1. The HDF5 datatype of the attribute + * is #H5T_NATIVE_LONG. + * + */ H5_HLDLL herr_t H5LTset_attribute_long(hid_t loc_id, const char *obj_name, const char *attr_name, const long *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Location of the object to which the attribute + * is to be attached + * \param[in] obj_name That object's name + * \param[in] attr_name Attribute name + * \param[in] buffer Attribute value + * \param[in] size Attribute size + * + * \return \herr_t + * + * \details H5LTset_attribute_long_long() creates and writes a numerical + * attribute named \p attr_name and attaches it to the object + * specified by the name \p obj_name. + * + * The attribute has a dimensionality of 1 and its HDF5 datatype + * is #H5T_NATIVE_LLONG. + * + */ H5_HLDLL herr_t H5LTset_attribute_long_long(hid_t loc_id, const char *obj_name, const char *attr_name, const long long *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_ulong() creates and writes a numerical + * attribute named \p attr_name and attaches it to the object + * specified by the name \p obj_name. The attribute has a + * dimensionality of 1. The HDF5 datatype of the attribute + * is #H5T_NATIVE_ULONG. + * + */ H5_HLDLL herr_t H5LTset_attribute_ulong(hid_t loc_id, const char *obj_name, const char *attr_name, const unsigned long *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Location of the object to which the attribute + * is to be attached + * \param[in] obj_name That object's name + * \param[in] attr_name Attribute name + * \param[in] buffer Attribute value + * \param[in] size Attribute size + * + * \return \herr_t + * + * \details H5LTset_attribute_ullong() creates and writes a numerical + * attribute named \p attr_name and attaches it to the object + * specified by the name \p obj_name. + * + * The attribute has a dimensionality of 1 and its HDF5 datatype + * is #H5T_NATIVE_ULLONG. + * + */ H5_HLDLL herr_t H5LTset_attribute_ullong(hid_t loc_id, const char *obj_name, const char *attr_name, const unsigned long long *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_float() creates and writes a numerical + * floating point attribute named \p attr_name and attaches + * it to the object specified by the name \p obj_name. + * The attribute has a dimensionality of 1. The HDF5 datatype + * of the attribute is #H5T_NATIVE_FLOAT. + * + */ H5_HLDLL herr_t H5LTset_attribute_float(hid_t loc_id, const char *obj_name, const char *attr_name, const float *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_double() creates and writes a numerical + * attribute named \p attr_name and attaches + * it to the object specified by the name \p obj_name. + * The attribute has a dimensionality of 1. The HDF5 datatype + * of the attribute is #H5T_NATIVE_DOUBLE. + * + */ H5_HLDLL herr_t H5LTset_attribute_double(hid_t loc_id, const char *obj_name, const char *attr_name, const double *buffer, size_t size); @@ -155,42 +958,337 @@ H5_HLDLL herr_t H5LTset_attribute_double(hid_t loc_id, const char *obj_name, con *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[in] mem_type_id Identifier of the memory datatype + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute() reads an attribute named + * \p attr_name with the memory type \p mem_type_id. + * + */ H5_HLDLL herr_t H5LTget_attribute(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t mem_type_id, void *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_string() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The datatype is a string. + * + * \version 1.8.9 The content of the buffer returned by the Fortran + * subroutine has changed in this release:\n + * If the returned buffer requires padding, + * h5ltget_attribute_string_f() now employs space + * padding; this buffer was previously returned with a C NULL terminator. + * + */ H5_HLDLL herr_t H5LTget_attribute_string(hid_t loc_id, const char *obj_name, const char *attr_name, char *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_char() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The datatype of the attribute + * is #H5T_NATIVE_CHAR. + * + */ H5_HLDLL herr_t H5LTget_attribute_char(hid_t loc_id, const char *obj_name, const char *attr_name, char *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_uchar() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_UCHAR + * + */ H5_HLDLL herr_t H5LTget_attribute_uchar(hid_t loc_id, const char *obj_name, const char *attr_name, unsigned char *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_short() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_SHORT + * + */ H5_HLDLL herr_t H5LTget_attribute_short(hid_t loc_id, const char *obj_name, const char *attr_name, short *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_ushort() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_USHORT. + * + */ H5_HLDLL herr_t H5LTget_attribute_ushort(hid_t loc_id, const char *obj_name, const char *attr_name, unsigned short *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_int() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_INT. + * + */ H5_HLDLL herr_t H5LTget_attribute_int(hid_t loc_id, const char *obj_name, const char *attr_name, int *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_uint() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_INT. + * + */ H5_HLDLL herr_t H5LTget_attribute_uint(hid_t loc_id, const char *obj_name, const char *attr_name, unsigned int *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_long() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_LONG. + * + */ H5_HLDLL herr_t H5LTget_attribute_long(hid_t loc_id, const char *obj_name, const char *attr_name, long *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a \e long \e long attribute. + * + * \param[in] loc_id Location of the object to which + * the attribute is attached + * \param[in] obj_name That object's name + * \param[in] attr_name Attribute name + * \param[out] data Attribute value + * + * \return \herr_t + * + * \details H5LTget_attribute_long_long() reads the attribute + * specified by \p loc_id and \p obj_name. + * + */ H5_HLDLL herr_t H5LTget_attribute_long_long(hid_t loc_id, const char *obj_name, const char *attr_name, long long *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_ulong() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_ULONG. + * + */ H5_HLDLL herr_t H5LTget_attribute_ulong(hid_t loc_id, const char *obj_name, const char *attr_name, unsigned long *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_ullong() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_ULLONG. + * + */ H5_HLDLL herr_t H5LTget_attribute_ullong(hid_t loc_id, const char *obj_name, const char *attr_name, unsigned long long *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_float() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_FLOAT. + * + */ H5_HLDLL herr_t H5LTget_attribute_float(hid_t loc_id, const char *obj_name, const char *attr_name, float *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_double() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_DOUBLE. + * + */ H5_HLDLL herr_t H5LTget_attribute_double(hid_t loc_id, const char *obj_name, const char *attr_name, double *data); @@ -201,8 +1299,55 @@ H5_HLDLL herr_t H5LTget_attribute_double(hid_t loc_id, const char *obj_name, con *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Gets the dimensionality of an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] rank The dimensionality of the attribute + * + * \return \herr_t + * + * \details H5LTget_attribute_ndims() gets the dimensionality of an attribute + * named \p attr_name that is attached to the object specified + * by the name \p obj_name. + * + */ H5_HLDLL herr_t H5LTget_attribute_ndims(hid_t loc_id, const char *obj_name, const char *attr_name, int *rank); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Gets information about an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] dims The dimensions of the attribute + * \param[out] type_class The class identifier. #H5T_class_t is + * defined in H5Tpublic.h. For a list of valid class + * types see: H5Tget_class(). + * \param[out] type_size The size of the datatype in bytes + * + * \return \herr_t + * + * \details H5LTget_attribute_info() gets information about an attribute + * named \p attr_name attached to the object specified by + * the name \p obj_name. + * + * \par Example + * \snippet H5LT_examples.c get_attribute_info + * + */ H5_HLDLL herr_t H5LTget_attribute_info(hid_t loc_id, const char *obj_name, const char *attr_name, hsize_t *dims, H5T_class_t *type_class, size_t *type_size); @@ -213,7 +1358,74 @@ H5_HLDLL herr_t H5LTget_attribute_info(hid_t loc_id, const char *obj_name, const *------------------------------------------------------------------------- */ -H5_HLDLL hid_t H5LTtext_to_dtype(const char *text, H5LT_lang_t lang_type); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates an HDF5 datatype given a text description. + * + * \param[in] text A character string containing a DDL + * definition of the datatype to be created + * \param[in] lang_type The language used to describe the datatype. + * The only currently supported language is + * #H5LT_DDL. + * + * \return Returns the datatype identifier(non-negative) if successful; + * otherwise returns a negative value. + * + * \details Given a text description of a datatype, this function creates + * an HDF5 datatype and returns the datatype identifier. + * The text description of the datatype has to comply with the + * \p lang_type definition of HDF5 datatypes. + * Currently, only the DDL(#H5LT_DDL) is supported. + * The complete DDL definition of HDF5 datatypes can be found in + * the last chapter of the + * <a href="https://portal.hdfgroup.org/display/HDF5/HDF5+User+Guides"> + * HDF5 User's Guide</a>. + * + * \par Example + * An example of DDL definition of \c enum type is shown as follows. + * \snippet H5LT_examples.c enum + * + */ +H5_HLDLL hid_t H5LTtext_to_dtype(const char *text, H5LT_lang_t lang_type); + +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates a text description of an HDF5 datatype. + * + * \param[in] dtype Identifier of the datatype to be converted + * \param[out] str Buffer for the text description of the datatype + * \param[in] lang_type The language used to describe the datatype. + * The currently supported language is #H5LT_DDL. + * \param[out] len The size of buffer needed to store the text description + * + * \return \herr_t + * + * \details Given an HDF5 datatype identifier, this function creates + * a description of this datatype in \p lang_type language format. + * A preliminary H5LTdtype_to_text() call can be made to determine + * the size of the buffer needed with a NULL passed in for \p str. + * This value is returned as \p len. That value can then be assigned + * to len for a second H5Ttype_to_text() call, which will + * retrieve the actual text description for the datatype. + * + * If \p len is not big enough for the description, the text + * description will be truncated to fit in the buffer. + * + * Currently only DDL (#H5LT_DDL) is supported for \p lang_type. + * The complete DDL definition of HDF5 data types can be found in + * the last chapter of the + * <a href="https://portal.hdfgroup.org/display/HDF5/HDF5+User+Guides"> + * HDF5 User's Guide</a>. + * + * \par Example + * An example of DDL definition of \c enum type is shown as follows. + * \snippet H5LT_examples.c enum + * + */ H5_HLDLL herr_t H5LTdtype_to_text(hid_t dtype, char *str, H5LT_lang_t lang_type, size_t *len); /*------------------------------------------------------------------------- @@ -223,8 +1435,116 @@ H5_HLDLL herr_t H5LTdtype_to_text(hid_t dtype, char *str, H5LT_lang_t lang_type, *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Determines whether an attribute exists. + * + * \param[in] loc_id Identifier of the object to which the attribute + * is expected to be attached + * \param[in] name Attribute name + * + * \return \htri_t + * + * \details H5LTfind_attribute() determines whether an attribute named + * \p name exists attached to the object specified + * by \p loc_id. + * + * \p loc_id must be an object identifier and \p name + * must specify an attribute that is expected to be attached + * to that object. + * + */ H5_HLDLL herr_t H5LTfind_attribute(hid_t loc_id, const char *name); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Determines whether an HDF5 path is valid and, optionally, + * whether the path resolves to an HDF5 object. + * + * \param[in] loc_id Identifier of an object in the file + * \param[in] path The path to the object to check; + * links in \p path may be of any type. + * \param[in] check_object_valid If TRUE, determine whether the final + * component of \p path resolves to + * an object; if FALSE, do not check. + * + * \return Upon success: + * \return If \p check_object_valid is set to \c FALSE: + * \return Returns \c TRUE if the path is valid; + * otherwise returns \c FALSE. + * \return If \p check_object_valid is set to \c TRUE: + * \return Returns \c TRUE if the path is valid and + * resolves to an HDF5 object; + * otherwise returns \c FALSE. + * + * \return Upon error, returns a negative value. + * + * \details H5LTpath_valid() checks the validity of \p path relative + * to the identifier of an object, \p loc_id. Optionally, + * \p check_object_valid can be set to determine whether the + * final component of \p path resolves to an HDF5 object; + * if not, the final component is a dangling link. + * + * The meaning of the function’s return value depends on the + * value of \p check_object_valid: + * + * If \p check_object_valid is set to \c FALSE, H5LTpath_valid() + * will check all links in \p path to verify that they exist. + * If all the links in \p path exist, the function will + * return \c TRUE; otherwise the function will return \c FALSE. + * + * If \p check_object_valid is set to \c TRUE, + * H5LTpath_valid() will first check the links in \p path, + * as described above. If all the links exist, + * \p check_object_valid will then determine whether the final + * component of \p path resolves to an actual HDF5 object. + * H5LTpath_valid() will return \c TRUE if all the links in + * \p path exist and the final component resolves to an + * actual object; otherwise, it will return \c FALSE. + * + * \p path can be any one of the following: + * + * - An absolute path, which starts with a slash (\c /) + * indicating the file’s root group, followed by the members + * - A relative path with respect to \p loc_id + * - A dot (\c .), if \p loc_id is the object identifier for + * the object itself + * . + * + * If \p path is an absolute path, then \p loc_id can be an + * identifier for any object in the file as it is used only to + * identify the file. If \p path is a relative path, then + * \p loc_id must be a file or a group identifier. + * + * \note + * <b>Note on Behavior Change:</b> + * The behavior of H5LTpath_valid() was changed in the 1.10.0 release + * in the case where the root group, “/”, is the value of path. + * This change is described below: + * - Let \p loc_id denote a valid HDF5 file identifier, and let + * \p check_object_valid be set to true or false. + * A call to H5LTpath_valid() with arguments \p loc_id, “/”, + * and \p check_object_valid returns a positive value; + * in other words, H5LTpath_valid(loc_id, "/", check_object_valid) + * returns a positive value. + * In HDF5 version 1.8.16, this function returns 0. + * - Let ‘root’ denote a valid HDF5 group identifier that refers + * to the root group of an HDF5 file, and let \p check_object_valid + * be set to true or false. + * A call to H5LTpath_valid() with arguments ‘root’, “/”, and + * \p check_object_valid returns a positive value; + * in other words, H5LTpath_valid(root, "/", check_object_valid) + * returns a positive value. + * In HDF5 version 1.8.16, this function returns 0. + * + * \version 1.10.0 Function behavior changed in this release. + * See the “Note on Behavior Change” section above. + * + */ H5_HLDLL htri_t H5LTpath_valid(hid_t loc_id, const char *path, hbool_t check_object_valid); /*------------------------------------------------------------------------- @@ -234,6 +1554,82 @@ H5_HLDLL htri_t H5LTpath_valid(hid_t loc_id, const char *path, hbool_t check_obj *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Opens an HDF5 file image in memory. + * + * \param[in] buf_ptr A pointer to the supplied initial image + * \param[in] buf_size Size of the supplied buffer + * \param[in] flags Flags specifying whether to open the image + * read-only or read/write, whether HDF5 is to + * take control of the buffer, and instruction + * regarding releasing the buffer. + * + * \return Returns a file identifier if successful; + * otherwise returns a negative value. + * \warning \Bold{Failure Modes:} + * \warning H5LTopen_file_image() will fail if either \p buf_ptr is NULL + * or \p buf_size equals 0 (zero). + * + * + * \details H5LTopen_file_image() opens the HDF5 file image that is + * located in system memory at the address indicated by + * \p buf_ptr of size \p buf_size. + * H5LTopen_file_image() opens a file image with the + * Core driver, #H5FD_CORE. + * + * A value of NULL for \p buf_ptr is invalid and will + * cause the function to fail. + * + * A value of 0 for \p buf_size is invalid and will cause + * the function to fail. + * + * The flags passed in \p flags specify whether to open the image + * read-only or read/write, whether HDF5 is to take control of the + * buffer, and instruction regarding releasing the buffer. + * Valid values are: + * - #H5LT_FILE_IMAGE_OPEN_RW + * - Specifies opening the file image in read/write mode. + * - Default without this flag: File image will be opened read-only. + * . + * - #H5LT_FILE_IMAGE_DONT_COPY + * - Specifies to not copy the provided file image buffer; + * the buffer will be used directly. HDF5 will release the + * file image when finished. + * - Default without this flag: Copy the file image buffer and + * open the copied file image. + * . + * - #H5LT_FILE_IMAGE_DONT_RELEASE + * - Specifies that HDF5 is not to release the buffer when + * the file opened with H5LTopen_file_image() is closed; + * releasing the buffer will be left to the application. + * - Default without this flag: HDF5 will automatically + * release the file image buffer after the file image is + * closed. This flag is valid only when used with + * #H5LT_FILE_IMAGE_DONT_COPY. + * . + * . + * + * \note **Motivation:** + * \note H5LTopen_file_image() and other elements of HDF5 + * are used to load an image of an HDF5 file into system memory + * and open that image as a regular HDF5 file. An application can + * then use the file without the overhead of disk I/O. + * + * \note **Recommended Reading:** + * \note This function is part of the file image operations feature set. + * It is highly recommended to study the guide + * <a href="https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations"> + * HDF5 File Image Operations</a> before using this feature set.\n + * See the “See Also” section below for links to other elements of + * HDF5 file image operations. + * + * \todo There is no "See Also" section??? + * + * \since 1.8.9 + */ H5_HLDLL hid_t H5LTopen_file_image(void *buf_ptr, size_t buf_size, unsigned flags); #ifdef __cplusplus diff --git a/hl/src/H5PTpublic.h b/hl/src/H5PTpublic.h index d74baa5..b881b25 100644 --- a/hl/src/H5PTpublic.h +++ b/hl/src/H5PTpublic.h @@ -18,19 +18,201 @@ extern "C" { #endif +/**\defgroup H5PT Packet Table + * + * <em>Creating and manipulating HDF5 datasets to support append- + * and read-only operations on table data (H5PT)</em> + * + * The HDF5 Packet Table API is designed to allow records to be + * appended to and read from a table. Packet Table datasets are + * chunked, allowing them to grow as needed. + * + * The Packet Table API, with the H5PT prefix, is not to be confused with + * the H5TB Table API (H5TB prefix). The H5TB APIs are stateless + * (H5TB Tables do not need to be opened or closed) but H5PT Packet Tables + * require less performance overhead. Also, H5TB Tables support insertions + * and deletions, while H5PT Packet Tables support only append operations. + * H5TB functions should not be called on tables created with the + * H5PT API, or vice versa. + * + * Packet Tables are datasets in an HDF5 file, so while their contents + * should not be changed outside of the H5PT API calls, the datatypes of + * Packet Tables can be queried using \ref H5Dget_type. + * Packet Tables can also be given attributes using the normal HDF5 APIs. + * + * \note \Bold{Programming hints:} + * \note The following line includes the HDF5 Packet Table package, H5PT, + * in C applications: + * \code #include "hdf5_hl.h" \endcode + * Without this include, an application will not have access to + * these functions. + * + * - \ref H5PTappend + * \n Appends packets to the end of a packet table. + * - \ref H5PTclose + * \n Closes an open packet table. + * - \ref H5PTcreate + * \n Creates a packet table to store fixed-length + * or variable-length packets. + * - \ref H5PTcreate_fl + * \n Creates a packet table to store fixed-length packets. + * - \ref H5PTcreate_index + * \n Resets a packet table's index to the first packet. + * - \ref H5PTfree_vlen_buff + * \n Releases memory allocated in the process of + * reading variable-length packets. + * - \ref H5PTget_dataset + * \n Returns the backend dataset of this packet table. + * - \ref H5PTget_index + * \n Gets the current record index for a packet table + * - \ref H5PTget_next + * \n Reads packets from a packet table starting at the + * current index. + * - \ref H5PTget_num_packets + * \n Returns the number of packets in a packet table. + * - \ref H5PTget_type + * \n Returns the backend datatype of this packet table. + * - \ref H5PTis_valid + * \n Determines whether an identifier points to a packet table. + * - \ref H5PTis_varlen + * \n Determines whether a packet table contains variable-length + * or fixed-length packets. + * - \ref H5PTopen + * \n Opens an existing packet table. + * - \ref H5PTread_packets + * \n Reads a number of packets from a packet table. + * - \ref H5PTset_index + * \n Sets a packet table's index. + * . + * + */ + /*------------------------------------------------------------------------- * Create/Open/Close functions *------------------------------------------------------------------------- */ /* NOTE: H5PTcreate is replacing H5PTcreate_fl for better name due to the removal of H5PTcreate_vl. H5PTcreate_fl may be retired in 1.8.19. */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Creates a packet table to store fixed-length or + * variable-length packets. + * + * \fg_loc_id + * \param[in] dset_name The name of the packet table to create + * \param[in] dtype_id The datatype of the packet + * \param[in] chunk_size The size in number of table entries per chunk + * \param[in] plist_id Identifier of the property list. Can be used to + * specify the compression of the packet table. + * + * \return Returns an identifier for the new packet table or + * #H5I_INVALID_HID on error. + * + * \details The H5PTcreate() creates and opens a packet table named + * \p dset_name attached to the object specified by the + * identifier \p loc_id. The created packet table should be closed + * with H5PTclose(), eventually. + * + * The datatype, \p dtype_id, may specify any datatype, including + * variable-length data. If \p dtype_id specifies a compound + * datatype, one or more fields in that compound type may be + * variable-length. + * + * \p chunk_size is the size in number of table entries per chunk. + * Packet table datasets use HDF5 chunked storage + * to allow them to grow. This value allows the user + * to set the size of a chunk. The chunk size affects + * performance. + * + * \since 1.10.0 and 1.8.17 + * + */ H5_HLDLL hid_t H5PTcreate(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size, hid_t plist_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Opens an existing packet table. + * + * \fg_loc_id + * \param[in] dset_name The name of the packet table to open + * + * \return Returns an identifier for the packet table or + * #H5I_INVALID_HID on error. + * + * \details H5PTopen() opens an existing packet table in the file or group + * specified by \p loc_id. \p dset_name is the name of the packet + * table and is used to identify it in the file. This function is + * used to open both fixed-length packet tables and variable-length + * packet tables. The packet table should later be closed with + * H5PTclose(). + * + */ H5_HLDLL hid_t H5PTopen(hid_t loc_id, const char *dset_name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Closes an open packet table. + * + * \param[in] table_id Identifier of packet table to be closed + * + * \return \herr_t + * + * \details The H5PTclose() ends access to a packet table specified + * by \p table_id. + * + */ H5_HLDLL herr_t H5PTclose(hid_t table_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Creates a packet table to store fixed-length packets + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[in] dtype_id The datatype of a packet. + * \param[in] chunk_size The size in number of table entries per + * chunk. + * \param[in] compression The compression level; + * a value of 0 through 9. + * + * \return Returns an identifier for the packet table or + * #H5I_INVALID_HID on error. + * + * \deprecated This function was deprecated in favor of the function + * H5PTcreate(). + * + * \details The H5PTcreate_fl() creates and opens a packet table + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. It should be closed + * with H5PTclose(). + * + * The datatype, \p dtype_id, may specify any datatype, + * including variable-length data. If \p dtype_id specifies a + * compound datatype, one or more fields in that compound type + * may be variable-length. + * + * \p chunk_size is the size in number of table entries per chunk. + * Packet table datasets use HDF5 chunked storage + * to allow them to grow. This value allows the user + * to set the size of a chunk. The chunk size affects + * performance. + * + * \p compression is the compression level, a value of 0 through 9. + * Level 0 is faster but offers the least compression; + * level 9 is slower but offers maximum compression. + * A setting of -1 indicates that no compression is desired. + + */ /* This function may be removed from the packet table in release 1.8.19. */ H5_HLDLL hid_t H5PTcreate_fl(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size, int compression); @@ -39,24 +221,148 @@ H5_HLDLL hid_t H5PTcreate_fl(hid_t loc_id, const char *dset_name, hid_t dtype_id * Write functions *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Appends packets to the end of a packet table. + * + * \param[in] table_id Identifier of packet table to which + * packets should be appended + * \param[in] nrecords Number of packets to be appended + * \param[in] data Buffer holding data to write + * + * \return \herr_t + * + * \details The H5PTappend() writes \p nrecords packets to the end of a + * packet table specified by \p table_id. \p data is a buffer + * containing the data to be written. For a packet table holding + * fixed-length packets, this data should be in the packet + * table's datatype. For a variable-length packet table, + * the data should be in the form of #hvl_t structs. + * + */ H5_HLDLL herr_t H5PTappend(hid_t table_id, size_t nrecords, const void *data); /*------------------------------------------------------------------------- * Read functions *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Reads packets from a packet table starting at the current index. + * + * \param[in] table_id Identifier of packet table to read from + * \param[in] nrecords Number of packets to be read + * \param[out] data Buffer into which to read data + * + * \return \herr_t + * + * \details The H5PTget_next() reads \p nrecords packets starting with + * the "current index" from a packet table specified by \p table_id. + * The packet table's index is set and reset with H5PTset_index() + * and H5PTcreate_index(). \p data is a buffer into which the + * data should be read. + * + * For a packet table holding variable-length records, the data + * returned in the buffer will be in form of a #hvl_t struct + * containing the length of the data and a pointer to it in memory. + * The memory used by this data must be freed using H5PTfree_vlen_buff(). + * + */ H5_HLDLL herr_t H5PTget_next(hid_t table_id, size_t nrecords, void *data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Reads a number of packets from a packet table. + * + * \param[in] table_id Identifier of packet table to read from + * \param[in] start Packet to start reading from + * \param[in] nrecords Number of packets to be read + * \param[out] data Buffer into which to read data. + * + * \return \herr_t + * + * \details The H5PTread_packets() reads \p nrecords packets starting at + * packet number \p start from a packet table specified by + * \p table_id. \p data is a buffer into which the data should + * be read. + * + * For a packet table holding variable-length records, the data + * returned in the buffer will be in form of #hvl_t structs, + * each containing the length of the data and a pointer to it in + * memory. The memory used by this data must be freed using + * H5PTfree_vlen_buff(). + * + */ H5_HLDLL herr_t H5PTread_packets(hid_t table_id, hsize_t start, size_t nrecords, void *data); /*------------------------------------------------------------------------- * Inquiry functions *------------------------------------------------------------------------- */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Returns the number of packets in a packet table. + * + * \param[in] table_id Identifier of packet table to query + * \param[out] nrecords Number of packets in packet table + * + * \return \herr_t + * + * \details The H5PTget_num_packets() returns by reference the number + * of packets in a packet table specified by \p table_id. + * + */ H5_HLDLL herr_t H5PTget_num_packets(hid_t table_id, hsize_t *nrecords); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Determines whether an identifier points to a packet table. + * + * \param[in] table_id Identifier to query + * + * \return Returns a non-negative value if \p table_id is + * a valid packet table, otherwise returns a negative value. + * + * \details The H5PTis_valid() returns a non-negative value if + * \p table_id corresponds to an open packet table, + * and returns a negative value otherwise. + * + */ H5_HLDLL herr_t H5PTis_valid(hid_t table_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Determines whether a packet table contains + * variable-length or fixed-length packets. + * + * \param[in] table_id Packet table to query + * + * \return Returns 1 for a variable-length packet table, + * 0 for fixed-length, or a negative value on error. + * + * \details The H5PTis_varlen() returns 1 (TRUE) if \p table_id is + * a packet table containing variable-length records. + * It returns 0 (FALSE) if \p table_id is a packet table + * containing fixed-length records. If \p table_id is not a + * packet table, a negative value is returned. + * + * \version 1.10.0 and 1.8.17 Function re-introduced. + * Function had been removed in 1.8.3. + * + */ H5_HLDLL herr_t H5PTis_varlen(hid_t table_id); /*------------------------------------------------------------------------- @@ -66,8 +372,42 @@ H5_HLDLL herr_t H5PTis_varlen(hid_t table_id); *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Returns the backend dataset of this packet table. + * + * \param[in] table_id Identifier of the packet table + * + * \return Returns a dataset identifier or H5I_INVALID_HID on error. + * + * \details The H5PTget_dataset() returns the identifier of the dataset + * storing the packet table \p table_id. This dataset identifier + * will be closed by H5PTclose(). + * + * \since 1.10.0 and 1.8.17 + * + */ H5_HLDLL hid_t H5PTget_dataset(hid_t table_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Returns the backend datatype of this packet table. + * + * \param[in] table_id Identifier of the packet table + * + * \return Returns a datatype identifier or H5I_INVALID_HID on error. + * + * \details The H5PTget_type() returns the identifier of the datatype + * used by the packet table \p table_id. This datatype + * identifier will be closed by H5PTclose(). + * + * \since 1.10.0 and 1.8.17 + * + */ H5_HLDLL hid_t H5PTget_type(hid_t table_id); /*------------------------------------------------------------------------- @@ -77,10 +417,63 @@ H5_HLDLL hid_t H5PTget_type(hid_t table_id); *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Resets a packet table's index to the first packet. + * + * \param[in] table_id Identifier of packet table whose index + * should be initialized. + * + * \return \herr_t + * + * \details Each packet table keeps an index of the "current" packet + * so that \c get_next can iterate through the packets in order. + * H5PTcreate_index() initializes a packet table's index, and + * should be called before using \c get_next. The index must be + * initialized every time a packet table is created or opened; + * this information is lost when the packet table is closed. + * + */ H5_HLDLL herr_t H5PTcreate_index(hid_t table_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Sets a packet table's index. + * + * \param[in] table_id Identifier of packet table whose index is to be set + * \param[in] pt_index The packet to which the index should point + * + * \return \herr_t + * + * \details Each packet table keeps an index of the "current" packet + * so that \c get_next can iterate through the packets in order. + * H5PTset_index() sets this index to point to a user-specified + * packet (the packets are zero-indexed). + * + */ H5_HLDLL herr_t H5PTset_index(hid_t table_id, hsize_t pt_index); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Gets the current record index for a packet table. + * + * \param[in] table_id Table identifier + * \param[out] pt_index Current record index + * + * \return \herr_t + * + * \details The H5PTget_index() returns the current record index + * \p pt_index for the table identified by \p table_id. + * + * \since 1.8.0 + * + */ H5_HLDLL herr_t H5PTget_index(hid_t table_id, hsize_t *pt_index); /*------------------------------------------------------------------------- @@ -90,6 +483,29 @@ H5_HLDLL herr_t H5PTget_index(hid_t table_id, hsize_t *pt_index); *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Releases memory allocated in the process of reading + * variable-length packets. + * + * \param[in] table_id Packet table whose memory should be freed. + * \param[in] bufflen Size of \p buff + * \param[in] buff Buffer that was used to read in variable-length + * packets + * + * \return \herr_t + * + * \details When variable-length packets are read, memory is automatically + * allocated to hold them, and must be freed. H5PTfree_vlen_buff() + * frees this memory, and should be called whenever packets are + * read from a variable-length packet table. + * + * \version 1.10.0 and 1.8.17 Function re-introduced. + * Function had been removed in 1.8.3. + * + */ H5_HLDLL herr_t H5PTfree_vlen_buff(hid_t table_id, size_t bufflen, void *buff); #ifdef __cplusplus diff --git a/hl/src/H5TBpublic.h b/hl/src/H5TBpublic.h index 1750490..042bf99 100644 --- a/hl/src/H5TBpublic.h +++ b/hl/src/H5TBpublic.h @@ -18,6 +18,64 @@ extern "C" { #endif +/**\defgroup H5TB Table + * + * <em>Creating and manipulating HDF5 datasets intended to be + * interpreted as tables (H5TB)</em> + * + * The HDF5 Table API defines a standard storage for HDF5 datasets + * that are intended to be interpreted as tables. A table is defined + * as a collection of records whose values are stored in fixed-length + * fields. All records have the same structure, and all values in + * each field have the same data type. + * + * \note \Bold{Programming hints:} + * \note To use any of these functions or subroutines, + * you must first include the relevant include file (C) or + * module (Fortran) in your application. + * \note The following line includes the HDF5 Table package, H5TB, + * in C applications: + * \code #include "hdf5_hl.h" \endcode + * \note To include the H5TB module in Fortran applications specify: + * \code use h5tb \endcode + * Fortran applications must also include \ref H5open before + * any HDF5 calls to initialize global variables and \ref H5close + * after all HDF5 calls to close the Fortran interface. + * + * - Creation + * - \ref H5TBmake_table + * - Storage + * - \ref H5TBappend_records (No Fortran) + * - \ref H5TBwrite_records (No Fortran) + * - \ref H5TBwrite_fields_name + * - \ref H5TBwrite_fields_index + * . + * - Modification + * - \ref H5TBdelete_record (No Fortran) + * - \ref H5TBinsert_record (No Fortran) + * - \ref H5TBadd_records_from (No Fortran) + * - \ref H5TBcombine_tables (No Fortran) + * - \ref H5TBinsert_field + * - \ref H5TBdelete_field + * . + * - Retrieval + * - \ref H5TBread_table + * - \ref H5TBread_records (No Fortran) + * - \ref H5TBread_fields_name + * - \ref H5TBread_fields_index + * . + * - Query + * - \ref H5TBget_table_info + * - \ref H5TBget_field_info + * . + * - Query Table Attributes + * - \ref H5TBAget_fill + * - \ref H5TBAget_title + * . + * . + * + */ + /*------------------------------------------------------------------------- * * Create functions @@ -25,6 +83,38 @@ extern "C" { *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Creates and writes a table + * + * \param[in] table_title The title of the table + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[in] nfields The number of fields + * \param[in] nrecords The number of records + * \param[in] type_size The size in bytes of the structure + * associated with the table; + * This value is obtained with \c sizeof(). + * \param[in] field_names An array containing the names of + * the fields + * \param[in] field_offset An array containing the offsets of + * the fields + * \param[in] field_types An array containing the type of + * the fields + * \param[in] chunk_size The chunk size + * \param[in] fill_data Fill values data + * \param[in] compress Flag that turns compression on or off + * \param[in] buf Buffer with data to be written to the table + * + * \return \herr_t + * + * \details H5TBmake_table() creates and writes a dataset named + * \p dset_name attached to the object specified by the + * identifier loc_id. + * + */ H5_HLDLL herr_t H5TBmake_table(const char *table_title, hid_t loc_id, const char *dset_name, hsize_t nfields, hsize_t nrecords, size_t type_size, const char *field_names[], const size_t *field_offset, const hid_t *field_types, hsize_t chunk_size, @@ -37,17 +127,128 @@ H5_HLDLL herr_t H5TBmake_table(const char *table_title, hid_t loc_id, const char *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Adds records to the end of the table + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to overwrite + * \param[in] nrecords The number of records to append + * \param[in] type_size The size of the structure type, + * as calculated by \c sizeof(). + * \param[in] field_offset An array containing the offsets of + * the fields. These offsets can be + * calculated with the #HOFFSET macro + * \param[in] dst_sizes An array containing the sizes of + * the fields + * \param[in] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBappend_records() adds records to the end of the table + * named \p dset_name attached to the object specified by the + * identifier \p loc_id. The dataset is extended to hold the + * new records. + * + */ H5_HLDLL herr_t H5TBappend_records(hid_t loc_id, const char *dset_name, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Overwrites records + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to overwrite + * \param[in] start The zero index record to start writing + * \param[in] nrecords The number of records to write + * \param[in] type_size The size of the structure type, as + * calculated by \c sizeof(). + * \param[in] field_offset An array containing the offsets of + * the fields. These offsets can be + * calculated with the #HOFFSET macro + * \param[in] dst_sizes An array containing the sizes of + * the fields + * \param[in] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBwrite_records() overwrites records starting at the zero + * index position start of the table named \p dset_name attached + * to the object specified by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBwrite_records(hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Overwrites fields + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to overwrite + * \param[in] field_names The names of the fields to write + * \param[in] start The zero index record to start writing + * \param[in] nrecords The number of records to write + * \param[in] type_size The size of the structure type, as + * calculated by \c sizeof(). + * \param[in] field_offset An array containing the offsets of + * the fields. These offsets can be + * calculated with the #HOFFSET macro + * \param[in] dst_sizes An array containing the sizes of + * the fields + * \param[in] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBwrite_fields_name() overwrites one or several fields + * specified by \p field_names with data in \p buf from a + * dataset named \p dset_name attached to the object specified + * by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBwrite_fields_name(hid_t loc_id, const char *dset_name, const char *field_names, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Overwrites fields + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to overwrite + * \param[in] nfields The number of fields to overwrite. + * This parameter is also the size of the + * \p field_index array. + * \param[in] field_index The indexes of the fields to write + * \param[in] start The zero based index record to start writing + * \param[in] nrecords The number of records to write + * \param[in] type_size The size of the structure type, as + * calculated by \c sizeof(). + * \param[in] field_offset An array containing the offsets of + * the fields. These offsets can be + * calculated with the #HOFFSET macro + * \param[in] dst_sizes An array containing the sizes of + * the fields + * \param[in] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBwrite_fields_index() overwrites one or several fields + * specified by \p field_index with a buffer \p buf from a + * dataset named \p dset_name attached to the object + * specified by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBwrite_fields_index(hid_t loc_id, const char *dset_name, hsize_t nfields, const int *field_index, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, @@ -60,18 +261,128 @@ H5_HLDLL herr_t H5TBwrite_fields_index(hid_t loc_id, const char *dset_name, hsiz *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Reads a table + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[in] dst_size The size of the structure type, + * as calculated by \c sizeof() + * \param[in] dst_offset An array containing the offsets of + * the fields. These offsets can be + * calculated with the #HOFFSET macro + * \param[in] dst_sizes An array containing the sizes of + * the fields. These sizes can be + * calculated with the sizeof() macro. + * \param[in] dst_buf Buffer with data + * + * \return \herr_t + * + * \details H5TBread_table() reads a table named + * \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBread_table(hid_t loc_id, const char *dset_name, size_t dst_size, const size_t *dst_offset, const size_t *dst_sizes, void *dst_buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Reads one or several fields. The fields are identified by name. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[in] field_names An array containing the names of the + * fields to read + * \param[in] start The start record to read from + * \param[in] nrecords The number of records to read + * \param[in] type_size The size in bytes of the structure associated + * with the table + * (This value is obtained with \c sizeof().) + * \param[in] field_offset An array containing the offsets of the fields + * \param[in] dst_sizes An array containing the size in bytes of + * the fields + * \param[out] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBread_fields_name() reads the fields identified + * by \p field_names from a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBread_fields_name(hid_t loc_id, const char *dset_name, const char *field_names, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Reads one or several fields. The fields are identified by index. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[in] nfields The number of fields to read + * (This parameter is also the size of the + * \p field_index array.) + * fields to read + * \param[in] field_index The indexes of the fields to read + * \param[in] start The start record to read from + * \param[in] nrecords The number of records to read + * \param[in] type_size The size in bytes of the structure associated + * with the table + * (This value is obtained with \c sizeof()) + * \param[in] field_offset An array containing the offsets of the fields + * \param[in] dst_sizes An array containing the size in bytes of + * the fields + * \param[out] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBread_fields_index() reads the fields identified + * by \p field_index from a dataset named \p dset_name attached + * to the object specified by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBread_fields_index(hid_t loc_id, const char *dset_name, hsize_t nfields, const int *field_index, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Reads records + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[in] start The start record to read from + * \param[in] nrecords The number of records to read + * \param[in] type_size The size of the structure type, + * as calculated by \c sizeof() + * \param[in] dst_offset An array containing the offsets of the + * fields. These offsets can be calculated + * with the #HOFFSET macro + * \param[in] dst_sizes An array containing the size in bytes of + * the fields + * \param[out] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBread_records() reads some records identified from a dataset + * named \p dset_name attached to the object specified by the + * identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBread_records(hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *dst_offset, const size_t *dst_sizes, void *buf); @@ -83,8 +394,52 @@ H5_HLDLL herr_t H5TBread_records(hid_t loc_id, const char *dset_name, hsize_t st *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Gets the table dimensions + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] nfields The number of fields + * \param[out] nrecords The number of records + * + * \return \herr_t + * + * \details H5TBget_table_info() retrieves the table dimensions from a + * dataset named \p dset_name attached to the object specified + * by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBget_table_info(hid_t loc_id, const char *dset_name, hsize_t *nfields, hsize_t *nrecords); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Gets information about a table + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] field_names An array containing the names of the fields + * \param[out] field_sizes An array containing the size of the fields + * \param[out] field_offsets An array containing the offsets of the fields + * \param[out] type_size The size of the HDF5 datatype associated + * with the table. (More specifically, + * the size in bytes of the HDF5 compound + * datatype used to define a row, or record, + * in the table) + * + * \return \herr_t + * + * \details H5TBget_field_info() gets information about a dataset + * named \p dset_name attached to the object specified + * by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBget_field_info(hid_t loc_id, const char *dset_name, char *field_names[], size_t *field_sizes, size_t *field_offsets, size_t *type_size); @@ -95,21 +450,162 @@ H5_HLDLL herr_t H5TBget_field_info(hid_t loc_id, const char *dset_name, char *fi *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Delete records + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset + * \param[in] start The start record to delete from + * \param[in] nrecords The number of records to delete + * + * \return \herr_t + * + * \details H5TBdelete_record() deletes nrecords number of records starting + * from \p start from the middle of the table \p dset_name + * ("pulling up" all the records after it). + * + */ H5_HLDLL herr_t H5TBdelete_record(hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Insert records + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset + * \param[in] start The position to insert + * \param[in] nrecords The number of records to insert + * \param[in] dst_size The size in bytes of the structure + * associated with the table + * \param[in] dst_offset An array containing the offsets of the + * fields + * \param[in] dst_sizes An array containing the size in bytes of + * the fields + * \param[in] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBinsert_record() inserts records into the middle of the table + * ("pushing down" all the records after it) + * + */ H5_HLDLL herr_t H5TBinsert_record(hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t dst_size, const size_t *dst_offset, const size_t *dst_sizes, void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Add records from first table to second table + * + * \fg_loc_id + * \param[in] dset_name1 The name of the dataset to read the records + * \param[in] start1 The position to read the records from the + * first table + * \param[in] nrecords The number of records to read from the first + * table + * \param[in] dset_name2 The name of the dataset to write the records + * \param[in] start2 The position to write the records on the + * second table + * + * \return \herr_t + * + * \details H5TBadd_records_from() adds records from a dataset named + * \p dset_name1 to a dataset named \p dset_name2. Both tables + * are attached to the object specified by the identifier loc_id. + * + */ H5_HLDLL herr_t H5TBadd_records_from(hid_t loc_id, const char *dset_name1, hsize_t start1, hsize_t nrecords, const char *dset_name2, hsize_t start2); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Combines records from two tables into a third + * + * \param[in] loc_id1 Identifier of the file or group in which + * the first table is located + * \param[in] dset_name1 The name of the first table to combine + * \param[in] loc_id2 Identifier of the file or group in which + * the second table is located + * \param[in] dset_name2 The name of the second table to combine + * \param[in] dset_name3 The name of the new table + * + * \return \herr_t + * + * \details H5TBcombine_tables() combines records from two datasets named + * \p dset_name1 and \p dset_name2, to a new table named + * \p dset_name3. These tables can be located on different files, + * identified by \p loc_id1 and \p loc_id2 (identifiers obtained + * with H5Fcreate()). They can also be located on the same file. + * In this case one uses the same identifier for both parameters + * \p loc_id1 and \p loc_id2. If two files are used, the third + * table is written in the first file. + * + */ H5_HLDLL herr_t H5TBcombine_tables(hid_t loc_id1, const char *dset_name1, hid_t loc_id2, const char *dset_name2, const char *dset_name3); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Insert a new field into a table + * + * \fg_loc_id + * \param[in] dset_name The name of the table + * \param[in] field_name The name of the field to insert + * \param[in] field_type The data type of the field + * \param[in] position The zero based index position where to + * insert the field + * \param[in] fill_data Fill value data for the field. This parameter + * can be NULL + * \param[in] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBinsert_field() inserts a new field named \p field_name into + * the table \p dset_name. Note: this function requires the table + * to be re-created and rewritten in its entirety, and this can result + * in some unused space in the file, and can also take a great deal of + * time if the table is large. + * + */ H5_HLDLL herr_t H5TBinsert_field(hid_t loc_id, const char *dset_name, const char *field_name, hid_t field_type, hsize_t position, const void *fill_data, const void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Deletes a field from a table + * + * \fg_loc_id + * \param[in] dset_name The name of the table + * \param[in] field_name The name of the field to delete + * + * \return \herr_t + * + * \details H5TBdelete_field() deletes a field named \p field_name from the + * table \p dset_name. Note: this function requires the table to be + * re-created and rewritten in its entirety, and this can result in + * some unused space in the file, and can also take a great deal of + * time if the table is large. + * + */ H5_HLDLL herr_t H5TBdelete_field(hid_t loc_id, const char *dset_name, const char *field_name); /*------------------------------------------------------------------------- @@ -119,8 +615,51 @@ H5_HLDLL herr_t H5TBdelete_field(hid_t loc_id, const char *dset_name, const char *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Reads a table's title + * + * \fg_loc_id + * \param[out] table_title Buffer for title name + * + * \return \herr_t + * + * \details H5TBget_title() returns the title of the table identified + * by \p loc_id in a buffer \p table_title. + * + */ H5_HLDLL herr_t H5TBAget_title(hid_t loc_id, char *table_title); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Reads the table attribute fill values + * + * \fg_loc_id + * \param[in] dset_name Name of table + * \param[in] dset_id Table identifier + * \param[out] dst_buf Buffer of fill values for table fields + * + * \return + * \return A return value of 1 indicates that a fill value is present. + * \return A return value of 0 indicates a fill value is not present. + * \return A return value <0 indicates an error. + * + * + * \details H5TBget_fill() reads the table attribute fill values into + * the buffer \p dst_buf for the table specified by \p dset_id + * and \p dset_name located in \p loc_id. + * + * + * \par Example + * \include H5TBAget_fill.c + * + */ H5_HLDLL htri_t H5TBAget_fill(hid_t loc_id, const char *dset_name, hid_t dset_id, unsigned char *dst_buf); #ifdef __cplusplus |