From f199c866dd3118f38904cb1935197438e662181c Mon Sep 17 00:00:00 2001 From: vchoi-hdfgroup <55293060+vchoi-hdfgroup@users.noreply.github.com> Date: Sat, 16 Jul 2022 04:59:43 -0500 Subject: Add doxygen for high level modules to hdf51.10 (#1899) --- doxygen/dox/ReferenceManual.dox | 23 +- doxygen/dox/high_level/extension.dox | 654 ++++++++++++++++ doxygen/dox/high_level/high_level.dox | 29 + doxygen/examples/H5DO_examples.c | 220 ++++++ doxygen/examples/H5LDget_dset_elmts.c | 143 ++++ doxygen/examples/H5LT_examples.c | 27 + doxygen/examples/H5TBAget_fill.c | 43 ++ hl/src/H5DOpublic.h | 198 +++++ hl/src/H5DSpublic.h | 336 +++++++- hl/src/H5IMpublic.h | 292 +++++++ hl/src/H5LDpublic.h | 138 ++++ hl/src/H5LTpublic.h | 1354 ++++++++++++++++++++++++++++++++- hl/src/H5PTpublic.h | 415 ++++++++++ hl/src/H5TBpublic.h | 545 +++++++++++++ src/H5Amodule.h | 2 +- src/H5Dmodule.h | 2 +- src/H5Emodule.h | 2 +- src/H5Fmodule.h | 2 +- src/H5Gmodule.h | 2 +- src/H5Imodule.h | 2 +- src/H5Lmodule.h | 2 +- src/H5Omodule.h | 2 +- src/H5PLmodule.h | 2 +- src/H5Pmodule.h | 2 +- src/H5Rmodule.h | 2 +- src/H5Smodule.h | 2 +- src/H5Tmodule.h | 2 +- src/H5Zmodule.h | 2 +- 28 files changed, 4421 insertions(+), 24 deletions(-) create mode 100644 doxygen/dox/high_level/extension.dox create mode 100644 doxygen/dox/high_level/high_level.dox create mode 100644 doxygen/examples/H5DO_examples.c create mode 100644 doxygen/examples/H5LDget_dset_elmts.c create mode 100644 doxygen/examples/H5LT_examples.c create mode 100644 doxygen/examples/H5TBAget_fill.c diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox index 155352a..cd438c2 100644 --- a/doxygen/dox/ReferenceManual.dox +++ b/doxygen/dox/ReferenceManual.dox @@ -29,19 +29,26 @@ The functions provided by the HDF5 C-API are grouped into the following \li \ref api-compat-macros \li Deprecated functions -\li High-level Extensions +\li \ref high_level -\ref H5 \ref H5A \ref H5D \ref H5E \ref H5F \ref H5G \ref H5I \ref H5L +\a Core \a library: \ref H5 \ref H5A \ref H5D \ref H5E \ref H5F \ref H5G \ref H5I \ref H5L \ref H5O \ref H5P \ref H5PL \ref H5R \ref H5S \ref H5T \ref H5Z + + +\a High-level \a library: \ref H5LT \ref H5IM \ref H5TB \ref H5PT \ref H5DS \ref H5DO \ref H5LR + + @@ -82,4 +89,4 @@ Break a leg! pull request !\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..c81ac6e --- /dev/null +++ b/doxygen/dox/high_level/extension.dox @@ -0,0 +1,654 @@ +/** \defgroup H5LR Extensions + * + * Working with region references, hyperslab selections, + * and bit-fields (H5LR, H5LT) + * + * 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 ( + * + * project , + * + * software ). + * 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 + * + * software + * must be separately downloaded and installed. + * + * A comprehensive guide to this library, + * + * User Guide to the HDF5 High-level Library for Handling Region References and Hyperslab Selections + * 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 ith element of the array holds the value of the + * starting bit of the ith bit-field value. + * Valid values are: 0 (zero) through 7. + * + * The parameter \p lengths is an array of length \p num_values; + * the ith element of the array holds the number of + * bits to be extracted for the ith 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_elemth 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. + * + * + * + */ 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" -*- */ + +//! + +#include +#include +#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 */ + : + : + + //! + + //! + +#include +#include +#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 */ + : + : +//! 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" -*- */ + +//! + +DATASET "DSET1" {DATATYPE H5T_STD_I32LE DATASPACE SIMPLE{(4, 13) / (60, 100)} : : } + +//! + +//! + +/* 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); + + //! + + //! + + 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) + +//! + + +//! + + 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) + } + :: + } + + //! + + //! + + /* 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); + + //! + + //! + + 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" + +//! 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" -*- */ + +//! + +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); + + //! + + //! + + “H5T_ENUM + { + H5T_NATIVE_INT; + “Bob” 0; + “Elena” 1; + “Quincey” 2; + “Frank” 3; + } + ” + +//! 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..13b2422 100644 --- a/hl/src/H5DOpublic.h +++ b/hl/src/H5DOpublic.h @@ -18,6 +18,28 @@ extern "C" { #endif +/**\defgroup H5DO Optimizations + * + * Bypassing default HDF5 behavior in order to optimize for specific + * use cases (H5DO) + * + * 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 +47,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 +99,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 + * (0 ≤ position < 32) 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 + * + * Using the Direct Chunk Write Function + * 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 + * (0 ≤ position < 32) 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 7306cbc..8449a0d 100644 --- a/hl/src/H5DSpublic.h +++ b/hl/src/H5DSpublic.h @@ -19,31 +19,365 @@ #define REFERENCE_LIST "REFERENCE_LIST" #define DIMENSION_LABELS "DIMENSION_LABELS" +/** + * \brief Prototype for H5DSiterate_scales() operator + * + */ +//! typedef herr_t (*H5DS_iterate_t)(hid_t dset, unsigned dim, hid_t scale, void *visitor_data); +//! #ifdef __cplusplus extern "C" { #endif +/**\defgroup H5DS Dimension Scales + * + * Creating and manipulating HDF5 datasets that are associated with + * the dimension of another HDF5 dataset (H5DS) + * + * \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 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. + * + */ + +/** + * -------------------------------------------------------------------------- + * \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 + * + * HDF5 Dimension Scale Specification. + * + * 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 + * + * HDF5 Dimension Scale Specification. + * + * 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 + * + * HDF5 Dimension Scale Specification. + * (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..b5426d6 100644 --- a/hl/src/H5IMpublic.h +++ b/hl/src/H5IMpublic.h @@ -18,33 +18,325 @@ extern "C" { #endif +/**\defgroup H5IM Images + * + * Creating and manipulating HDF5 datasets intended to be + * interpreted as images (H5IM) + * + * 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..e42c8d8 100644 --- a/hl/src/H5LDpublic.h +++ b/hl/src/H5LDpublic.h @@ -18,8 +18,146 @@ 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 47bb334..90deb56 100644 --- a/hl/src/H5LTpublic.h +++ b/hl/src/H5LTpublic.h @@ -35,6 +35,118 @@ typedef enum H5LT_lang_t { extern "C" { #endif +/**\defgroup H5LT Lite + * Functions used to simplify creating and manipulating datasets, + * attributes and other features (H5LT, H5LD) + * + * 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_float + * - \ref H5LTset_attribute_double + * - 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_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 +154,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 signed \e integer datatype. + * + * \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 short signed integer, + * #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 native signed integer, + * #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 long signed integer, + * #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 native floating point, + * #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 + * native floating-point double, #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 C string, #H5T_C_S1. + * + */ H5_HLDLL herr_t H5LTmake_dataset_string(hid_t loc_id, const char *dset_name, const char *buf); /*------------------------------------------------------------------------- @@ -72,20 +371,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 +543,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,39 +613,317 @@ 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 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); @@ -152,39 +934,313 @@ 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_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); @@ -195,8 +1251,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); @@ -207,7 +1310,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 + * + * HDF5 User's Guide. + * + * \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 + * + * HDF5 User's Guide. + * + * \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); /*------------------------------------------------------------------------- @@ -217,8 +1387,115 @@ 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 + * Note on Behavior Change: + * 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); /*------------------------------------------------------------------------- @@ -228,6 +1505,81 @@ 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 + * + * HDF5 File Image Operations 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..04741ac 100644 --- a/hl/src/H5PTpublic.h +++ b/hl/src/H5PTpublic.h @@ -18,19 +18,200 @@ extern "C" { #endif +/**\defgroup H5PT Packet Table + * + * Creating and manipulating HDF5 datasets to support append- + * and read-only operations on table data (H5PT) + * + * 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 +220,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 +371,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 +416,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 +482,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..9ad8e08 100644 --- a/hl/src/H5TBpublic.h +++ b/hl/src/H5TBpublic.h @@ -18,6 +18,70 @@ extern "C" { #endif +/**\defgroup H5TB Table + * + * Creating and manipulating HDF5 datasets intended to be + * interpreted as tables (H5TB) + * + * 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 +89,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 +133,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 +267,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 +400,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 +456,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 +621,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 diff --git a/src/H5Amodule.h b/src/H5Amodule.h index 29e5960..cab56d4 100644 --- a/src/H5Amodule.h +++ b/src/H5Amodule.h @@ -375,7 +375,7 @@ * * Previous Chapter \ref sec_dataspace - Next Chapter \ref sec_error * - * \defgroup H5A H5A Attributes + * \defgroup H5A H5A * * An HDF5 attribute is a small metadata object describing the nature and/or intended usage of a primary data * object. A primary data object may be a dataset, group, or committed datatype. diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h index 8cca52e..0eb7d68 100644 --- a/src/H5Dmodule.h +++ b/src/H5Dmodule.h @@ -2983,7 +2983,7 @@ allocated if necessary. */ /** - * \defgroup H5D H5D Datasets + * \defgroup H5D H5D * * Use the functions in this module to manage HDF5 datasets, including the * transfer of data between memory and disk and the description of dataset diff --git a/src/H5Emodule.h b/src/H5Emodule.h index 3a65bed..aeba66d 100644 --- a/src/H5Emodule.h +++ b/src/H5Emodule.h @@ -580,7 +580,7 @@ * * Previous Chapter \ref sec_attribute - Next Chapter \ref sec_plist * - * \defgroup H5E H5E Error Handling + * \defgroup H5E H5E * * \internal The \c FUNC_ENTER macro clears the error stack whenever an * interface function is entered. When an error is detected, an entry diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h index ae2f6a1..8904d9c 100644 --- a/src/H5Fmodule.h +++ b/src/H5Fmodule.h @@ -69,7 +69,7 @@ */ /** - * \defgroup H5F H5F File + * \defgroup H5F H5F * * Use the functions in this module to manage HDF5 files. * diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h index f15b929..13589fd 100644 --- a/src/H5Gmodule.h +++ b/src/H5Gmodule.h @@ -951,7 +951,7 @@ */ /** - * \defgroup H5G H5G Groups + * \defgroup H5G H5G * * Use the functions in this module to manage HDF5 groups. * diff --git a/src/H5Imodule.h b/src/H5Imodule.h index c4bdf7b..024d8ab 100644 --- a/src/H5Imodule.h +++ b/src/H5Imodule.h @@ -30,7 +30,7 @@ #define H5_MY_PKG_INIT NO /** - * \defgroup H5I H5I Identifiers + * \defgroup H5I H5I * * Use the functions in this module to manage identifiers defined by the HDF5 * library. See \ref H5IUD for user-defined identifiers and identifier diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h index cd102f7..47c8ad1 100644 --- a/src/H5Lmodule.h +++ b/src/H5Lmodule.h @@ -30,7 +30,7 @@ #define H5_MY_PKG_INIT YES /** - * \defgroup H5L H5L Links + * \defgroup H5L H5L * * Use the functions in this module to manage HDF5 links and link types. * diff --git a/src/H5Omodule.h b/src/H5Omodule.h index 7a023b9..866e3b4 100644 --- a/src/H5Omodule.h +++ b/src/H5Omodule.h @@ -30,7 +30,7 @@ #define H5_MY_PKG_INIT YES /** - * \defgroup H5O H5O Objects + * \defgroup H5O H5O * * Use the functions in this module to manage HDF5 objects. * diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h index 24fb93c..94cbf49 100644 --- a/src/H5PLmodule.h +++ b/src/H5PLmodule.h @@ -28,7 +28,7 @@ #define H5_MY_PKG_INIT YES /** - * \defgroup H5PL H5PL Plugins + * \defgroup H5PL H5PL * * Use the functions in this module to manage the loading behavior of HDF5 * plugins. diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index f5f8d83..0439a3f 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -882,7 +882,7 @@ * * Previous Chapter \ref sec_error - Next Chapter \ref sec_addition * - * \defgroup H5P H5P Properties and Property Lists + * \defgroup H5P H5P * * Use the functions in this module to manage HDF5 property lists and property * list classes. HDF5 property lists are the main vehicle to configure the diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h index 68deefe..d467ffe 100644 --- a/src/H5Rmodule.h +++ b/src/H5Rmodule.h @@ -26,7 +26,7 @@ #define H5_MY_PKG_INIT YES /** - * \defgroup H5R H5R References + * \defgroup H5R H5R * * Use the functions in this module to manage HDF5 references. Referents can * be HDF5 objects, attributes, and selections on datasets a.k.a. dataset diff --git a/src/H5Smodule.h b/src/H5Smodule.h index 877af64..5eeba33 100644 --- a/src/H5Smodule.h +++ b/src/H5Smodule.h @@ -1516,7 +1516,7 @@ */ /** - * \defgroup H5S H5S Dataspaces + * \defgroup H5S H5S * * Use the functions in this module to manage HDF5 dataspaces \Emph{and} selections. * diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h index e9dafa1..a2f6828 100644 --- a/src/H5Tmodule.h +++ b/src/H5Tmodule.h @@ -3859,7 +3859,7 @@ filled according to the value of this property. The padding can be: */ /** - * \defgroup H5T H5T Datatypes + * \defgroup H5T H5T * * Use the functions in this module to manage HDF5 datatypes. * diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h index 214c87b..c3ef881 100644 --- a/src/H5Zmodule.h +++ b/src/H5Zmodule.h @@ -30,7 +30,7 @@ #define H5_MY_PKG_INIT YES /** - * \defgroup H5Z H5Z Filters + * \defgroup H5Z H5Z * * Use the functions in this module to manage HDF5 filters. * -- cgit v0.12