diff options
| -rw-r--r-- | src/H5Amodule.h | 17 | ||||
| -rw-r--r-- | src/H5Apublic.h | 341 | ||||
| -rw-r--r-- | src/H5Pmodule.h | 43 | ||||
| -rw-r--r-- | src/H5Ppublic.h | 868 | ||||
| -rw-r--r-- | src/H5Smodule.h | 27 | ||||
| -rw-r--r-- | src/H5Spublic.h | 282 |
6 files changed, 1551 insertions, 27 deletions
diff --git a/src/H5Amodule.h b/src/H5Amodule.h index 707fc54..09e6c4a 100644 --- a/src/H5Amodule.h +++ b/src/H5Amodule.h @@ -29,4 +29,21 @@ #define H5_MY_PKG_ERR H5E_ATTR #define H5_MY_PKG_INIT YES +/**\defgroup H5A H5A + * \brief Attribute Interface + * + * \details The Attribute Interface, H5A, provides a mechanism for attaching + * additional information to a dataset, group, or named datatype. + * + * Attributes are accessed by opening the object that they are + * attached to and are not independent objects. Typically an + * attribute is small in size and contains user metadata about the + * object that it is attached to. + * + * Attributes look similar to HDF5 datasets in that they have a + * datatype and dataspace. However, they do not support partial + * I/O operations and cannot be compressed or extended. + * + */ + #endif /* _H5Amodule_H */ diff --git a/src/H5Apublic.h b/src/H5Apublic.h index 89a3b04..3b836e7 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -45,18 +45,306 @@ typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_nam extern "C" { #endif +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Closes the specified attribute + * + * \attr_id + * + * \return \herr_t + * + * \details H5Aclose() terminates access to the attribute specified by + * \p attr_id by releasing the identifier. + * + * \attention Further use of a released attribute identifier is illegal; a + * function using such an identifier will generate an error. + * + * \since 1.0.0 + * + * \see H5Acreate(), H5Aopen() + */ +H5_DLL herr_t H5Aclose(hid_t attr_id); +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Creates an attribute attached to a specified object + * + * \fgdt_loc_id + * \param[in] attr_name Name of attribute + * \param[in] type_id Attribute datatype identifier + * \space_id + * \acpl_id + * \aapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Acreate2() creates an attribute, \p attr_name, which is attached + * to the object specified by the identifier \p loc_id. + * + * The attribute name, \p attr_name, must be unique for the object. + * + * The attribute is created with the specified datatype and dataspace, + * \p type_id and \p space_id, which are created with the H5T and + * H5S interfaces, respectively. + * + * If \p type_id is either a fixed-length or variable-length string, + * it is important to set the string length when defining the + * datatype. String datatypes are derived from #H5T_C_S1 (or + * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in + * size. See H5Tset_size() and Creating variable-length string + * datatypes. + * + * The access property list is currently unused, but will be used in + * the future. This property list should currently be #H5P_DEFAULT. + * + * The attribute identifier returned by this function must be released + * with H5Aclose() resource leaks will develop. + * + * \note The \p acpl and \p aapl parameters are currently not used; specify + * #H5P_DEFAULT. + * \note If \p loc_id is a file identifier, the attribute will be attached + * that file’s root group. + * + * \since 1.8.0 + * + * \see H5Aclose() + * + */ H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Creates an attribute attached to a specified object + * + * \fgdt_loc_id + * \param[in] obj_name Name, relative to \p loc_id, of object that + * attribute is to be attached to + * \param[in] attr_name Attribute name + * \param[in] type_id Attribute datatype identifier + * \space_id + * \acpl_id + * \aapl_id + * \lapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Acreate_by_name() creates an attribute, \p attr_name, which is + * attached to the object specified by \p loc_id and \p obj_name. + * + * \p loc_id is a location identifier; \p obj_name is the object + * name relative to \p loc_id. If \p loc_id fully specifies the + * object to which the attribute is to be attached, \p obj_name + * should be '.' (a dot). + * + * The attribute name, \p attr_name, must be unique for the object. + * + * The attribute is created with the specified datatype and + * dataspace, \p type_id and \p space_id, which are created with + * the H5T and H5S interfaces respectively. + * + * The attribute creation and access property lists are currently + * unused, but will be used in the future for optional attribute + * creation and access properties. These property lists should + * currently be #H5P_DEFAULT. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * The attribute identifier returned by this function must be + * released with H5close() or resource leaks will develop. + * + * \since 1.8.0 + * + */ H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens an attribute for an object specified by object identifier and + * attribute name + * + * \fgdt_loc_id{obj_id} + * \param[in] attr_name Name of attribute to open + * \aapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Aopen() opens an existing attribute, \p attr_name, that is + * attached to object specified by an object identifier, \p obj_id. + * + * The attribute access property list, \p aapl_id, is currently unused + * and should be #H5P_DEFAULT. + * + * This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called + * before the attribute can be accessed for any further purpose, + * including reading, writing, or any modification. + * + * The attribute identifier returned by this function must be released + * with H5Aclose() or resource leaks will develop. + * + * \since 1.8.0 + * + * \see H5Aclose(), H5Acreate() + */ H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id); -H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id, - hid_t lapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens the nth attribute attached to an object + * + * \loc_id + * \param[in] obj_name Name of object to which attribute is attached, + * relative to location + * \param[in] idx_type Type of index + * \param[in] order Index traversal order + * \param[in] n Attribute’s position in index + * \aapl_id + * \lapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Aopen_by_idx() opens an existing attribute that is attached + * to an object specified by location and name, \p loc_id and + * \p obj_name, respectively. If \p loc_id fully specifies the + * object to which the attribute is attached, \p obj_name, should + * be '.' (a dot). + * + * The attribute is identified by an index type, an index traversal + * order, and a position in the index, \p idx_type, \p order and + * \p n, respectively. These parameters and their valid values are + * discussed in the description of H5Aiterate2(). + * + * The attribute access property list, \p aapl_id, is currently + * unused and should currently be #H5P_DEFAULT. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * This function, H5Aopen(), or H5Aopen_by_name() must be called + * before an attribute can be accessed for any further purpose, + * including reading, writing, or any modification. + * + * The attribute identifier returned by this function must be + * released with H5Aclose() or resource leaks will develop. + * + * \since 1.8.0 + * + */ H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t aapl_id, hid_t lapl_id); -H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens an attribute for an object by object name and attribute name + * + * \fgdt_loc_id + * \param[in] obj_name Name of object to which attribute is attached, + * relative to \p loc_id + * \param[in] attr_name Name of attribute to open + * \aapl_id + * \lapl_id + * + * \return \hid_tv{attribute} + * + * \details H5Aopen_by_name() opens an existing attribute, \p attr_name, + * that is attached to an object specified by location and name, + * \p loc_id and \p obj_name, respectively. + * + * \p loc_id specifies a location from which the target object can + * be located and \p obj_name is an object name relative to + * \p loc_id. If \p loc_id fully specifies the object to which the + * attribute is attached, \p obj_name should be '.' (a dot). + * + * The attribute access property list, \p aapl_id, is currently + * unused and should currently be #H5P_DEFAULT. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * This function, H5Aopen(), or H5Aopen_by_idx() must be called + * before an attribute can be accessed for any further purpose, + * including reading, writing, or any modification. + * + * The attribute identifier returned by this function must be + * released with H5Aclose() or resource leaks will develop. + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id, + hid_t lapl_id); +/*-------------------------------------------------------------------------- */ +/** + * \ingroup H5A + * + * \brief Reads the value of an attribute + * + * \attr_id + * \mem_type_id{type_id} + * \param[out] buf Buffer for data to be read + * + * \return \herr_t + * + * \details H5Aread() reads an attribute, specified with \p attr_id. The + * attribute's in-memory datatype is specified with \p type_id. The + * entire attribute is read into \p buf from the file. + * + * Datatype conversion takes place at the time of a read or write and + * is automatic. + * + * \version 1.8.8 Fortran updated to Fortran2003. + * \version 1.4.2 The \p dims parameter was added to the Fortran API in this + * release. + * \since 1.0.0 + * + * \see H5Awrite() + * +*/ H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf); -H5_DLL herr_t H5Aclose(hid_t attr_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Writes data to an attribute + * + * \attr_id + * \mem_type_id{type_id} + * \param[out] buf Data to be written + * + * \return \herr_t + * + * \details H5Awrite() writes an attribute, specified with \p attr_id. The + * attribute's in-memory datatype is specified with \p type_id. + * The entire attribute is written from \p buf to the file. + * + * If \p type_id is either a fixed-length or variable-length string, + * it is important to set the string length when defining the datatype. + * String datatypes are derived from #H5T_C_S1 (or #H5T_FORTRAN_S1 for + * Fortran codes), which defaults to 1 character in size. + * See H5Tset_size() and Creating variable-length string datatypes. + * + * Datatype conversion takes place at the time of a read or write and + * is automatic. + * + * \version 1.8.8 Fortran updated to Fortran2003. + * \version 1.4.2 Fortran \p dims parameter added in this release + * \since 1.0.0 + * \see H5Aread() + * + */ +H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf); H5_DLL hid_t H5Aget_space(hid_t attr_id); H5_DLL hid_t H5Aget_type(hid_t attr_id); H5_DLL hid_t H5Aget_create_plist(hid_t attr_id); @@ -100,6 +388,51 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam void *operator_data /*in,out*/); /* Function prototypes */ +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Creates an attribute attached to a specified object + * + * \fgdt_loc_id + * \param[in] name Name of attribute to locate and open + * \param[in] type_id Identifier of attribute datatype + * \space_id + * \acpl_id + * + * \return \hid_tv{attribute} + * + * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT. + * + * \deprecated Deprecated in favor of H5Acreate2() + * + * \details H5Acreate1() creates an attribute, \p name, which is attached + * to the object specified by the identifier \p loc_id. + * + * The attribute name, \p name, must be unique for the object. + * + * The attribute is created with the specified datatype and dataspace, + * \p type_id and \p space_id, which are created with the H5T and + * H5S interfaces, respectively. + * + * If \p type_id is either a fixed-length or variable-length string, + * it is important to set the string length when defining the + * datatype. String datatypes are derived from #H5T_C_S1 (or + * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in + * size. See H5Tset_size() and Creating variable-length string + * datatypes. + * + * The attribute identifier returned by this function must be released + * with H5Aclose() resource leaks will develop. + * + * \since 1.8.0 + * + * \version 1.8.0 The function H5Acreate() was renamed to H5Acreate1() and + * deprecated in this release. + * + * \see H5Aclose() + * + */ H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t acpl_id); H5_DLL hid_t H5Aopen_name(hid_t loc_id, const char *name); H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx); diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index d8cc430..b9e1180 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -29,4 +29,47 @@ #define H5_MY_PKG_ERR H5E_PLIST #define H5_MY_PKG_INIT YES +/**\defgroup H5P H5P + * \brief Property List Interface + * + * \details The HDF5 Property List Interface provides a mechanism to take + * advantage of more powerful or unusual features in HDF5. + * + * HDF5 objects have properties or characteristics associated with + * them, and there are default properties that handle the most + * common needs. These default properties can be modified using the + * HDF5 Property List Interface. For example, the data storage + * layout property of a dataset is contiguous by default. For better + * performance, the layout can be modified to be chunked or chunked + * and compressed. + * + * \todo Describe concisely what the functions in this module are about. + * \todo Clicking on "more" after "Property List Interface" at the top does not work + * + * \defgroup GPLO General Property List Operations + * \ingroup H5P + * \defgroup GPLOA General Property List Operations (Advanced) + * \ingroup H5P + * \defgroup FCPL File Creation Properties + * \ingroup H5P + * \defgroup FAPL File Access Properties + * \ingroup H5P + * \defgroup GCPL Group Creation Properties + * \ingroup H5P + * \defgroup ALCAPL Attribute and Link Creation Properties + * \ingroup H5P + * \defgroup LAPL Link Access Properties + * \ingroup H5P + * \defgroup DCPL Dataset Creation Properties + * \ingroup H5P + * \defgroup DAPL Dataset Access Properties + * \ingroup H5P + * \defgroup DXPL Dataset Transfer Properties + * \ingroup H5P + * \defgroup OCPL Object Creation Properties + * \ingroup H5P + * \defgroup OCPPL Object Copy Properties + * \ingroup H5P + */ + #endif /* _H5Pmodule_H */ diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index ffcdd99..a978895 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -232,11 +232,153 @@ H5_DLLVAR hid_t H5P_LST_REFERENCE_ACCESS_ID_g; /*********************/ /* Generic property list routines */ + +/** + * \ingroup GPLO + * + * \brief Terminates access to a property list + * + * \plist_id + * + * \return \herr_t + * + * \details H5Pclose() terminates access to a property list. All property + * lists should be closed when the application is finished + * accessing them. This frees resources used by the property + * list. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pclose(hid_t plist_id); +/** + * \ingroup GPLO + * + * \brief Creates a new property list as an instance of a property list class + * + * \plistcls_id{cls_id} + * + * \return \hid_t{property list} + * + * \details H5Pcreate() creates a new property list as an instance of + * some property list class. The new property list is initialized + * with default values for the specified class. The classes are as + * follows: + * + * <table> + * <tr> + * <th>Class Identifier</th> + * <th>Class Name</th> + * <th>Comments</th> + * </tr> + * <tr> + * <td>#H5P_ATTRIBUTE_CREATE</td> + * <td>attribute create</td> + * <td>Properties for attribute creation</td> + * </tr> + * <tr> + * <td>#H5P_DATASET_ACCESS</td> + * <td>dataset access</td> + * <td>Properties for dataset access</td> + * </tr> + * <tr> + * <td>#H5P_DATASET_CREATE</td> + * <td>dataset create</td> + * <td>Properties for dataset creation</td> + * </tr> + * <tr> + * <td>#H5P_DATASET_XFER</td> + * <td>data transfer</td> + * <td>Properties for raw data transfer</td> + * </tr> + * <tr> + * <td>#H5P_DATATYPE_ACCESS</td> + * <td>datatype access</td> + * <td>Properties for datatype access</td> + * </tr> + * <tr> + * <td>#H5P_DATATYPE_CREATE</td> + * <td>datatype create</td> + * <td>Properties for datatype creation</td> + * </tr> + * <tr> + * <td>#H5P_FILE_ACCESS</td> + * <td>file access</td> + * <td>Properties for file access</td> + * </tr> + * <tr> + * <td>#H5P_FILE_CREATE</td> + * <td>file create</td> + * <td>Properties for file creation</td> + * </tr> + * <tr> + * <td>#H5P_FILE_MOUNT</td> + * <td>file mount</td> + * <td>Properties for file mounting</td> + * </tr> + * <tr valign="top"> + * <td>#H5P_GROUP_ACCESS</td> + * <td>group access</td> + * <td>Properties for group access</td> + * </tr> + * <tr> + * <td>#H5P_GROUP_CREATE</td> + * <td>group create</td> + * <td>Properties for group creation</td> + * </tr> + * <tr> + * <td>#H5P_LINK_ACCESS</td> + * <td>link access</td> + * <td>Properties governing link traversal when accessing objects</td> + * </tr> + * <tr> + * <td>#H5P_LINK_CREATE</td> + * <td>link create</td> + * <td>Properties governing link creation</td> + * </tr> + * <tr> + * <td>#H5P_OBJECT_COPY</td> + * <td>object copy</td> + * <td>Properties governing the object copying process</td> + * </tr> + * <tr> + * <td>#H5P_OBJECT_CREATE</td> + * <td>object create</td> + * <td>Properties for object creation</td> + * </tr> + * <tr> + * <td>#H5P_STRING_CREATE</td> + * <td>string create</td> + * <td>Properties for character encoding when encoding strings or + * object names</td> + * </tr> + * <tr> + * <td>#H5P_VOL_INITIALIZE</td> + * <td>vol initialize</td> + * <td>Properties for VOL initialization</td> + * </tr> + * </table> + * + * This property list must eventually be closed with H5Pclose(); + * otherwise, errors are likely to occur. + * + * \version 1.12.0 The #H5P_VOL_INITIALIZE property list class was added + * \version 1.8.15 For each class, the class name returned by + * H5Pget_class_name() was added. + * The list of possible Fortran values was updated. + * \version 1.8.0 The following property list classes were added at this + * release: #H5P_DATASET_ACCESS, #H5P_GROUP_CREATE, + * #H5P_GROUP_ACCESS, #H5P_DATATYPE_CREATE, + * #H5P_DATATYPE_ACCESS, #H5P_ATTRIBUTE_CREATE + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Pcreate(hid_t cls_id); H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func_t cls_create, void *create_data, H5P_cls_copy_func_t cls_copy, void *copy_data, H5P_cls_close_func_t cls_close, void *close_data); H5_DLL char * H5Pget_class_name(hid_t pclass_id); -H5_DLL hid_t H5Pcreate(hid_t cls_id); H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size, void *def_value, H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del, @@ -262,10 +404,80 @@ H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const char *name); H5_DLL herr_t H5Premove(hid_t plist_id, const char *name); H5_DLL herr_t H5Punregister(hid_t pclass_id, const char *name); H5_DLL herr_t H5Pclose_class(hid_t plist_id); -H5_DLL herr_t H5Pclose(hid_t plist_id); H5_DLL hid_t H5Pcopy(hid_t plist_id); /* Object creation property list (OCPL) routines */ + +/** + * \ingroup OCPL + * + * \brief Returns information about a filter in a pipeline + * + * \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in + * H5Ppublic.h + * + * \plist_id{plist_id} + * \param[in] idx Sequence number within the filter pipeline of the filter + * for which information is sought + * \param[out] flags Bit vector specifying certain general properties of the + * filter + * \param[in,out] cd_nelmts Number of elements in \p cd_values + * \param[out] cd_values Auxiliary data for the filter + * \param[in] namelen Anticipated number of characters in \p name + * \param[out] name Name of the filter + * \param[out] filter_config Bit field, as described in H5Zget_filter_info() + * + * \return Returns a negative value on failure, and the filter identifier + * if successful (see #H5Z_filter_t): + * - #H5Z_FILTER_DEFLATE Data compression filter, + * employing the gzip algorithm + * - #H5Z_FILTER_SHUFFLE Data shuffling filter + * - #H5Z_FILTER_FLETCHER32 Error detection filter, employing the + * Fletcher32 checksum algorithm + * - #H5Z_FILTER_SZIP Data compression filter, employing the + * SZIP algorithm + * - #H5Z_FILTER_NBIT Data compression filter, employing the + * N-bit algorithm + * - #H5Z_FILTER_SCALEOFFSET Data compression filter, employing the + * scale-offset algorithm + * + * \details H5Pget_filter2() returns information about a filter specified by + * its filter number, in a filter pipeline specified by the property + * list with which it is associated. + * + * \p plist_id must be a dataset or group creation property list. + * + * \p idx is a value between zero and N-1, as described in + * H5Pget_nfilters(). The function will return a negative value if + * the filter number is out of range. + * + * The structure of the \p flags argument is discussed in + * H5Pset_filter(). + * + * On input, \p cd_nelmts indicates the number of entries in the + * \p cd_values array, as allocated by the caller; on return, + * \p cd_nelmts contains the number of values defined by the filter. + * + * If \p name is a pointer to an array of at least \p namelen bytes, + * the filter name will be copied into that array. The name will be + * null terminated if \p namelen is large enough. The filter name + * returned will be the name appearing in the file, the name + * registered for the filter, or an empty string. + * + * \p filter_config is the bit field described in + * H5Zget_filter_info(). + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * \since 1.8.0 + * + */ +H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned idx, + unsigned int *flags/*out*/, + size_t *cd_nelmts/*out*/, + unsigned cd_values[]/*out*/, + size_t namelen, char name[], + unsigned *filter_config /*out*/); H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, unsigned *min_dense); H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flags); @@ -277,9 +489,6 @@ H5_DLL herr_t H5Pmodify_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int H5_DLL herr_t H5Pset_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts, const unsigned int c_values[]); H5_DLL int H5Pget_nfilters(hid_t plist_id); -H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned filter, unsigned int *flags /*out*/, - size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, - char name[], unsigned *filter_config /*out*/); H5_DLL herr_t H5Pget_filter_by_id2(hid_t plist_id, H5Z_filter_t id, unsigned int *flags /*out*/, size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, char name[] /*out*/, unsigned *filter_config /*out*/); @@ -379,10 +588,592 @@ H5_DLL herr_t H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned unsigned *min_raw_per); /* Dataset creation property list (DCPL) routines */ -H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); + +/** + * \ingroup DCPL + * + * \brief Retrieves the size of chunks for the raw data of a chunked + * layout dataset + * + * \dcpl_id{plist_id} + * \param[in] max_ndims Size of the \p dims array + * \param[out] dim Array to store the chunk dimensions + * + * \return Returns chunk dimensionality if successful; + * otherwise returns a negative value. + * + * \details H5Pget_chunk() retrieves the size of chunks for the raw data + * of a chunked layout dataset. This function is only valid for + * dataset creation property lists. At most, \p max_ndims elements + * of \p dim will be initialized. + * + * \since 1.0.0 + * + */ +H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[]/*out*/); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Retrieves the edge chunk option setting from a dataset creation + * property list + * + * \dcpl_id{plist_id} + * \param[out] opts Edge chunk option flag. Valid values are described in + * H5Pset_chunk_opts(). The option status can be + * retrieved using the bitwise AND operator ( & ). For + * example, the expression + * (opts&#H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS) will + * evaluate to #H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS if + * that option has been enabled. Otherwise, it will + * evaluate to 0 (zero). + * + * \return \herr_t + * + * \details H5Pget_chunk_opts() retrieves the edge chunk option setting + * stored in the dataset creation property list \p plist_id. + * + * \since 1.10.0 + * + */ +H5_DLL herr_t H5Pget_chunk_opts(hid_t plist_id, unsigned *opts); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Retrieves the time when fill values are written to a dataset + * + * \dcpl_id{plist_id} + * \param[out] fill_time Setting for the timing of writing fill values to + * the dataset + * + * \return \herr_t + * + * \details H5Pget_fill_time() examines the dataset creation property list + * \p plist_id to determine when fill values are to be written to + * a dataset. Valid values returned in \p fill_time are as + * follows: + * + * <table> + * <tr> + * <td>#H5D_FILL_TIME_IFSET</td> + * <td>Fill values are written to the dataset when storage + * space is allocated only if there is a user-defined fill + * value, i.e., one set with H5Pset_fill_value(). (Default) + * </td> + * </tr> + * <tr> + * <td>#H5D_FILL_TIME_ALLOC</td> + * <td>Fill values are written to the dataset when storage + * space is allocated.</td> + * </tr> + * <tr> + * <td>#H5D_FILL_TIME_NEVER</td> + * <td>Fill values are never written to the dataset.</td> + * </tr> + * </table> + * + * \note H5Pget_fill_time() is designed to work in coordination with the + * dataset fill value and dataset storage allocation time properties, + * retrieved with the functions H5Pget_fill_value() and + * H5Pget_alloc_time(). + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t + *fill_time/*out*/); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Retrieves a dataset fill value + * + * \dcpl_id{plist_id} + * \param[in] type_id Datatype identifier for the value passed via + * \p value + * \param[out] value Pointer to buffer to contain the returned + * fill value + * + * \return \herr_t + * + * \details H5Pget_fill_value() returns the dataset fill value defined in + * the dataset creation property list \p plist_id. The fill value + * is returned through the \p value pointer and will be converted + * to the datatype specified by \p type_id. This datatype may + * differ from the fill value datatype in the property list, but + * the HDF5 library must be able to convert between the two + * datatypes. + * + * If the fill value is undefined, i.e., set to NULL in the + * property list, H5Pget_fill_value() will return an error. + * H5Pfill_value_defined() should be used to check for this + * condition before H5Pget_fill_value() is called. + * + * Memory must be allocated by the calling application. + * + * \note H5Pget_fill_value() is designed to coordinate with the dataset + * storage allocation time and fill value write time properties, + * which can be retrieved with the functions H5Pget_alloc_time() + * and H5Pget_fill_time(), respectively. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, + void *value/*out*/); +/** + *------------------------------------------------------------------------- + * \ingroup DCPL + * + * \brief Returns the layout of the raw data for a dataset + * + * \dcpl_id{plist_id} + * + * \return Returns the layout type (a non-negative value) of a dataset + * creation property list if successful. Valid return values are: + * - #H5D_COMPACT: Raw data is stored in the object header in the + * file. + * - #H5D_CONTIGUOUS: Raw data is stored separately from the object + * header in one contiguous chunk in the file. + * - #H5D_CHUNKED: Raw data is stored separately from the object + * header in chunks in separate locations in the + * file. + * - #H5D_VIRTUAL: Raw data is drawn from multiple datasets in + * different files. + * \return + * Otherwise, returns a negative value indicating failure. + * + * \details H5Pget_layout() returns the layout of the raw data for a + * dataset. This function is only valid for dataset creation + * property lists. + * + * Note that a compact storage layout may affect writing data to + * the dataset with parallel applications. See the H5Dwrite() + * documentation for details. + * + * \version 1.10.0 #H5D_VIRTUAL added in this release. + * + * \since 1.0.0 + * + */ H5_DLL H5D_layout_t H5Pget_layout(hid_t plist_id); -H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*/]); -H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[] /*out*/); +/** + *------------------------------------------------------------------------- + * \ingroup DCPL + * + * \brief Sets the size of the chunks used to store a chunked layout + * dataset + * + * \dcpl_id{plist_id} + * \param[in] ndims The number of dimensions of each chunk + * \param[in] dim An array defining the size, in dataset elements, of + * each chunk + * + * \return \herr_t + * \details H5Pset_chunk() sets the size of the chunks used to store a + * chunked layout dataset. This function is only valid for dataset + * creation property lists. + * + * The \p ndims parameter currently must be the same size as the + * rank of the dataset. + * + * The values of the \p dim array define the size of the chunks + * to store the dataset's raw data. The unit of measure for \p dim + * values is dataset elements. + * + * As a side-effect of this function, the layout of the dataset is + * changed to #H5D_CHUNKED, if it is not already so set. + * + * \note Chunk size cannot exceed the size of a fixed-size dataset. For + * example, a dataset consisting of a 5x4 fixed-size array cannot be + * defined with 10x10 chunks. Chunk maximums: + * - The maximum number of elements in a chunk is 2<sup>32</sup>-1 which + * is equal to 4,294,967,295. If the number of elements in a chunk is + * set via H5Pset_chunk() to a value greater than 2<sup>32</sup>-1, + * then H5Pset_chunk() will fail. + * - The maximum size for any chunk is 4GB. If a chunk that is larger + * than 4GB attempts to be written with H5Dwrite(), then H5Dwrite() + * will fail. + * + * \see H5Pset_layout(), H5Dwrite() + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*/]); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Sets the edge chunk option in a dataset creation property list + * + * \dcpl_id{plist_id} + * \param[in] opts Edge chunk option flag. Valid values are: + * \li #H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS + * When enabled, filters are not applied to partial + * edge chunks. When disabled, partial edge chunks are + * filtered. Enabling this option will improve + * performance when appending to the dataset and, when + * compression filters are used, prevent reallocation + * of these chunks. Datasets created with this option + * enabled will be inaccessible with HDF5 library + * versions before Release 1.10. Default: \e Disabled + * \li 0 (zero) Disables option; partial edge chunks + * will be compressed. + * + * \return \herr_t + * + * \details H5Pset_chunk_opts() sets the edge chunk option in the + * dataset creation property list \p dcpl_id. + * + * The available option is detailed in the parameters section. + * Only chunks that are not completely filled by the dataset’s + * dataspace are affected by this option. Such chunks are + * referred to as partial edge chunks. + * + * \note \b Motivation: H5Pset_chunk_opts() is used to specify storage + * options for chunks on the edge of a dataset’s dataspace. This + * capability allows the user to tune performance in cases where + * the dataset size may not be a multiple of the chunk size and + * the handling of partial edge chunks can impact performance. + * + * \since 1.10.0 + * + */ +H5_DLL herr_t H5Pset_chunk_opts(hid_t plist_id, unsigned opts); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Sets the time when fill values are written to a dataset + * + * \dcpl_id{plist_id} + * \param[in] fill_time When to write fill values to a dataset + * + * \return \herr_t + * + * \details H5Pset_fill_time() sets up the timing for writing fill values + * to a dataset. This property is set in the dataset creation + * property list \p plist_id. Timing is specified in \p fill_time + * with one of the following values: + * + * <table> + * <tr> + * <td>#H5D_FILL_TIME_IFSET</td> + * <td>Write fill values to the dataset when storage space is + * allocated only if there is a user-defined fill value, + * i.e.,one set with H5Pset_fill_value(). (Default)</td> + * </tr> + * <tr> + * <td>#H5D_FILL_TIME_ALLOC</td> + * <td>Write fill values to the dataset when storage space is + * allocated.</td> + * </tr> + * <tr> + * <td>#H5D_FILL_TIME_NEVER</td> + * <td>Never write fill values to the dataset.</td> + * </tr> + * </table> + * + * \note H5Pset_fill_time() is designed for coordination with the dataset + * fill value and dataset storage allocation time properties, set + * with the functions H5Pset_fill_value() and H5Pset_alloc_time(). + * See H5Dcreate() for further cross-references. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Sets the fill value for a dataset + * + * \dcpl_id{plist_id} + * \param[in] type_id Datatype of \p value + * \param[in] value Pointer to buffer containing value to use as + * fill value + * + * \return \herr_t + * + * \details H5Pset_fill_value() sets the fill value for a dataset in the + * dataset creation property list. \p value is interpreted as + * being of datatype \p type_id. This datatype may differ from + * that of the dataset, but the HDF5 library must be able to + * convert \p value to the dataset datatype when the dataset is + * created. + * + * The default fill value is 0 (zero), which is interpreted + * according to the actual dataset datatype. + * + * Setting \p value to NULL indicates that the fill value is to + * be undefined. + * + * \note Applications sometimes write data only to portions of an allocated + * dataset. It is often useful in such cases to fill the unused space + * with a known fill value. This function allows the user application + * to set that fill value; the functions H5Dfill() and + * H5Pset_fill_time(), respectively, provide the ability to apply the + * fill value on demand or to set up its automatic application. + * + * \note A fill value should be defined so that it is appropriate for the + * application. While the HDF5 default fill value is 0 (zero), it is + * often appropriate to use another value. It might be useful, for + * example, to use a value that is known to be impossible for the + * application to legitimately generate. + * + * \note H5Pset_fill_value() is designed to work in concert with + * H5Pset_alloc_time() and H5Pset_fill_time(). H5Pset_alloc_time() + * and H5Pset_fill_time() govern the timing of dataset storage + * allocation and fill value write operations and can be important in + * tuning application performance. + * + * \note See H5Dcreate() for further cross-references. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, + const void *value); +/** + *------------------------------------------------------------------------- + * + * \ingroup DCPL + * + * \brief Sets up use of the shuffle filter + * + * \dcpl_id{plist_id} + * + * \return \herr_t + * + * \details H5Pset_shuffle() sets the shuffle filter, #H5Z_FILTER_SHUFFLE, + * in the dataset creation property list \p plist_id. The shuffle + * filter de-interlaces a block of data by reordering the bytes. + * All the bytes from one consistent byte position of each data + * element are placed together in one block; all bytes from a + * second consistent byte position of each data element are placed + * together a second block; etc. For example, given three data + * elements of a 4-byte datatype stored as 012301230123, shuffling + * will re-order data as 000111222333. This can be a valuable step + * in an effective compression algorithm because the bytes in each + * byte position are often closely related to each other and + * putting them together can increase the compression ratio. + * + * As implied above, the primary value of the shuffle filter lies + * in its coordinated use with a compression filter; it does not + * provide data compression when used alone. When the shuffle + * filter is applied to a dataset immediately prior to the use of + * a compression filter, the compression ratio achieved is often + * superior to that achieved by the use of a compression filter + * without the shuffle filter. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_shuffle(hid_t plist_id); +/** + *------------------------------------------------------------------------- + * \ingroup DCPL + * + * \brief Sets the type of storage used to store the raw data for a dataset + * + * \dcpl_id{plist_id} + * \param[in] layout Type of storage layout for raw data + * + * \return \herr_t + * \details H5Pset_layout() sets the type of storage used to store the raw + * data for a dataset. This function is only valid for dataset + * creation property lists. + * + * Valid values for \p layout are: + * - #H5D_COMPACT: Store raw data in the dataset object header + * in file. This should only be used for datasets + * with small amounts of raw data. The raw data + * size limit is 64K (65520 bytes). Attempting + * to create a dataset with raw data larger than + * this limit will cause the H5Dcreate() call to + * fail. + * - #H5D_CONTIGUOUS: Store raw data separately from the object + * header in one large chunk in the file. + * - #H5D_CHUNKED: Store raw data separately from the object header + * as chunks of data in separate locations in + * the file. + * - #H5D_VIRTUAL: Draw raw data from multiple datasets in + * different files. + * + * Note that a compact storage layout may affect writing data to + * the dataset with parallel applications. See the note in + * H5Dwrite() documentation for details. + * \version 1.10.0 #H5D_VIRTUAL added in this release. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); +/** + *------------------------------------------------------------------------- + * \ingroup DCPL + * + * \brief Sets up use of the SZIP compression filter + * + * \dcpl_id{plist_id} + * \param[in] options_mask A bit-mask conveying the desired SZIP options; + * Valid values are #H5_SZIP_EC_OPTION_MASK and + * #H5_SZIP_NN_OPTION_MASK. + * \param[in] pixels_per_block The number of pixels or data elements in each + * data block + * + * \return \herr_t + * + * \details H5Pset_szip() sets an SZIP compression filter, #H5Z_FILTER_SZIP, + * for a dataset. SZIP is a compression method designed for use with + * scientific data. + * + * Before proceeding, all users should review the “Limitations” + * section below. + * + * Users familiar with SZIP outside the HDF5 context may benefit + * from reviewing the Note “For Users Familiar with SZIP in Other + * Contexts” below. + * + * In the text below, the term pixel refers to an HDF5 data element. + * This terminology derives from SZIP compression's use with image + * data, where pixel referred to an image pixel. + * + * The SZIP \p bits_per_pixel value (see Note, below) is automatically + * set, based on the HDF5 datatype. SZIP can be used with atomic + * datatypes that may have size of 8, 16, 32, or 64 bits. + * Specifically, a dataset with a datatype that is 8-, 16-, 32-, or + * 64-bit signed or unsigned integer; char; or 32- or 64-bit float + * can be compressed with SZIP. See Note, below, for further + * discussion of the the SZIP \p bits_per_pixel setting. + * + * SZIP options are passed in an options mask, \p options_mask, + * as follows. + * + * <table> + * <tr> + * <th>Option</th> + * <th>Description (Mutually exclusive; select one.)</th> + * </tr> + * <tr> + * <td>#H5_SZIP_EC_OPTION_MASK</td> + * <td>Selects entropy coding method</td> + * </tr> + * <tr> + * <td>#H5_SZIP_NN_OPTION_MASK</td> + * <td>Selects nearest neighbor coding method</td> + * </tr> + * </table> + * + * The following guidelines can be used in determining which + * option to select: + * + * - The entropy coding method, the EC option specified by + * #H5_SZIP_EC_OPTION_MASK, is best suited for data that has been + * processed. The EC method works best for small numbers. + * - The nearest neighbor coding method, the NN option specified + * by #H5_SZIP_NN_OPTION_MASK, preprocesses the data then the + * applies EC method as above. + * + * Other factors may affect results, but the above criteria + * provides a good starting point for optimizing data compression. + * + * SZIP compresses data block by block, with a user-tunable block + * size. This block size is passed in the parameter + * \p pixels_per_block and must be even and not greater than 32, + * with typical values being 8, 10, 16, or 32. This parameter + * affects compression ratio; the more pixel values vary, the + * smaller this number should be to achieve better performance. + * + * In HDF5, compression can be applied only to chunked datasets. + * If \p pixels_per_block is bigger than the total number of + * elements in a dataset chunk, H5Pset_szip() will succeed but + * the subsequent call to H5Dcreate() will fail; the conflict + * can be detected only when the property list is used. + * + * To achieve optimal performance for SZIP compression, it is + * recommended that a chunk's fastest-changing dimension be equal + * to N times \p pixels_per_block where N is the maximum number of + * blocks per scan line allowed by the SZIP library. In the + * current version of SZIP, N is set to 128. + * + * SZIP compression is an optional HDF5 filter. + * + * \b Limitations: + * + * - SZIP compression cannot be applied to compound, array, + * variable-length, enumeration, or any other user-defined + * datatypes. If an SZIP filter is set in a dataset creation + * property list used to create a dataset containing a + * non-allowed datatype, the call to H5Dcreate() will fail; the + * conflict can be detected only when the property list is used. + * - Users should be aware that there are factors that affect one’s + * rights and ability to use SZIP compression by reviewing the + * SZIP copyright notice. + * + * \note \b For \b Users \b Familiar \b with \b SZIP \b in \b Other \b Contexts: + * + * \note The following notes are of interest primarily to those who have + * used SZIP compression outside of the HDF5 context. + * In non-HDF5 applications, SZIP typically requires that the user + * application supply additional parameters: + * - \p pixels_in_object, the number of pixels in the object to + * be compressed + * - \p bits_per_pixel, the number of bits per pixel + * - \p pixels_per_scanline, the number of pixels per scan line + * + * \note These values need not be independently supplied in the HDF5 + * environment as they are derived from the datatype and dataspace, + * which are already known. In particular, HDF5 sets + * \p pixels_in_object to the number of elements in a chunk and + * \p bits_per_pixel to the size of the element or pixel datatype. + * + * \note The following algorithm is used to set \p pixels_per_scanline: + * - If the size of a chunk's fastest-changing dimension, size, + * is greater than 4K, set \p pixels_per_scanline to 128 times + * \p pixels_per_block. + * - If size is less than 4K but greater than \p pixels_per_block, + * set \p pixels_per_scanline to the minimum of size and 128 + * times \p pixels_per_block. + * - If size is less than \p pixels_per_block but greater than the + * number elements in the chunk, set \p pixels_per_scanline to + * the minimum of the number elements in the chunk and 128 times + * \p pixels_per_block. + * + * \note The HDF5 datatype may have precision that is less than the full + * size of the data element, e.g., an 11-bit integer can be defined + * using H5Tset_precision(). To a certain extent, SZIP can take + * advantage of the precision of the datatype to improve compression: + * - If the HDF5 datatype size is 24-bit or less and the offset of + * the bits in the HDF5 datatype is zero (see H5Tset_offset() or + * H5Tget_offset()), the data is the in lowest N bits of the data + * element. In this case, the SZIP \p bits_per_pixel is set to the + * precision of the HDF5 datatype. + * - If the offset is not zero, the SZIP \p bits_per_pixel will be + * set to the number of bits in the full size of the data element. + * - If the HDF5 datatype precision is 25-bit to 32-bit, the SZIP + * \p bits_per_pixel will be set to 32. + * - If the HDF5 datatype precision is 33-bit to 64-bit, the SZIP + * \p bits_per_pixel will be set to 64. + * + * \note HDF5 always modifies the options mask provided by the user to set up + * usage of RAW_OPTION_MASK, ALLOW_K13_OPTION_MASK, and one of + * LSB_OPTION_MASK or MSB_OPTION_MASK, depending on endianness of the + * datatype. + * + * \since 1.6.0 + * + *-------------------------------------------------------------------------- + */ +H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block); H5_DLL herr_t H5Pset_virtual(hid_t dcpl_id, hid_t vspace_id, const char *src_file_name, const char *src_dset_name, hid_t src_space_id); H5_DLL herr_t H5Pget_virtual_count(hid_t dcpl_id, size_t *count /*out*/); @@ -391,22 +1182,14 @@ H5_DLL hid_t H5Pget_virtual_srcspace(hid_t dcpl_id, size_t index); H5_DLL ssize_t H5Pget_virtual_filename(hid_t dcpl_id, size_t index, char *name /*out*/, size_t size); H5_DLL ssize_t H5Pget_virtual_dsetname(hid_t dcpl_id, size_t index, char *name /*out*/, size_t size); H5_DLL herr_t H5Pset_external(hid_t plist_id, const char *name, off_t offset, hsize_t size); -H5_DLL herr_t H5Pset_chunk_opts(hid_t plist_id, unsigned opts); -H5_DLL herr_t H5Pget_chunk_opts(hid_t plist_id, unsigned *opts); H5_DLL int H5Pget_external_count(hid_t plist_id); H5_DLL herr_t H5Pget_external(hid_t plist_id, unsigned idx, size_t name_size, char *name /*out*/, off_t *offset /*out*/, hsize_t *size /*out*/); -H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block); -H5_DLL herr_t H5Pset_shuffle(hid_t plist_id); H5_DLL herr_t H5Pset_nbit(hid_t plist_id); H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, int scale_factor); -H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value); -H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, void *value /*out*/); H5_DLL herr_t H5Pfill_value_defined(hid_t plist, H5D_fill_value_t *status); H5_DLL herr_t H5Pset_alloc_time(hid_t plist_id, H5D_alloc_time_t alloc_time); H5_DLL herr_t H5Pget_alloc_time(hid_t plist_id, H5D_alloc_time_t *alloc_time /*out*/); -H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time); -H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t *fill_time /*out*/); H5_DLL herr_t H5Pget_dset_no_attrs_hint(hid_t dcpl_id, hbool_t *minimize); H5_DLL herr_t H5Pset_dset_no_attrs_hint(hid_t dcpl_id, hbool_t minimize); @@ -526,6 +1309,59 @@ H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, vo H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close); H5_DLL herr_t H5Pencode1(hid_t plist_id, void *buf, size_t *nalloc); +/** + *------------------------------------------------------------------------- + * \ingroup OCPL + * + * \brief Returns information about a filter in a pipeline (DEPRECATED) + * + * \todo H5Pget_filter1() prototype does not match source in H5Pocpl.c. + * Also, it is not in a deprecated file. Is that okay? + * + * \plist_id{plist_id} + * \param[in] filter Sequence number within the filter pipeline of the filter + * for which information is sought + * \param[out] flags Bit vector specifying certain general properties of + * the filter + * \param[in,out] cd_nelmts Number of elements in \p cd_values + * \param[out] cd_values Auxiliary data for the filter + * \param[in] namelen Anticipated number of characters in \p name + * \param[out] name Name of the filter + * + * \return Returns the filter identifier if successful; Otherwise returns + * a negative value. See: #H5Z_filter_t + * + * \details H5Pget_filter1() returns information about a filter, specified + * by its filter number, in a filter pipeline, specified by the + * property list with which it is associated. + * + * \p plist_id must be a dataset or group creation property list. + * + * \p filter is a value between zero and N-1, as described in + * H5Pget_nfilters(). The function will return a negative value + * if the filter number is out of range. + * + * The structure of the \p flags argument is discussed in + * H5Pset_filter(). + * + * On input, \p cd_nelmts indicates the number of entries in the + * \p cd_values array, as allocated by the caller; on return, + * \p cd_nelmts contains the number of values defined by the filter. + * + * If \p name is a pointer to an array of at least \p namelen + * bytes, the filter name will be copied into that array. The name + * will be null terminated if \p namelen is large enough. The + * filter name returned will be the name appearing in the file, the + * name registered for the filter, or an empty string. + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * \version 1.8.0 N-bit and scale-offset filters added. + * \version 1.8.0 Function H5Pget_filter() renamed to H5Pget_filter1() and + * deprecated in this release. + * \version 1.6.4 \p filter parameter type changed to unsigned. + * + */ H5_DLL H5Z_filter_t H5Pget_filter1(hid_t plist_id, unsigned filter, unsigned int *flags /*out*/, size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, char name[]); diff --git a/src/H5Smodule.h b/src/H5Smodule.h index 11494ee..6e8208b 100644 --- a/src/H5Smodule.h +++ b/src/H5Smodule.h @@ -29,4 +29,31 @@ #define H5_MY_PKG_ERR H5E_DATASPACE #define H5_MY_PKG_INIT YES +/**\defgroup H5S H5S + * \brief Dataspace Interface + * + * \details The Dataspace Interface provides functions for creating and + * working with dataspaces. + * + * A dataspace has two roles: + * + * \li It contains the spatial information (logical layout) of a + * dataset stored in a file. + * \li It describes an application’s data buffers and data elements + * participating in I/O. In other words, it can be used to + * select a portion or subset of a dataset. + * + * The spatial information of a dataset in a file includes the + * rank and dimensions of the dataset, which are a permanent part + * of the dataset definition. It can have dimensions that are fixed + * (unchanging) or unlimited, which means they can grow in size + * (or are extendible). + * + * A dataspace can consist of: + * \li no elements (NULL) + * \li a single element (scalar), or + * \li a simple array. + * + */ + #endif /* _H5Smodule_H */ diff --git a/src/H5Spublic.h b/src/H5Spublic.h index f0aa6dc..c16af93 100644 --- a/src/H5Spublic.h +++ b/src/H5Spublic.h @@ -120,17 +120,288 @@ typedef enum { extern "C" { #endif -/* Operations on dataspaces */ +/* Operations on dataspaces and dataspace selections */ + +/** + * \ingroup H5S + * + * \brief Releases and terminates access to a dataspace + * + * \space_id + * + * \return \herr_t + * + * \details H5Sclose() releases a dataspace. Further access through the + * dataspace identifier is illegal. Failure to release a dataspace with this + * call will result in resource leaks. + * + * \version 1.4.0 Fortran subroutine introduced in this release. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Sclose(hid_t space_id); +/** + * \ingroup H5S + * + * \brief Creates a new dataspace of a specified type + * + * \param[in] type Type of dataspace to be created + * + * \return \hid_t{dataspace} + * + * \details H5Screate() creates a new dataspace of a particular type. Currently + * supported types are #H5S_SCALAR, #H5S_SIMPLE, and #H5S_NULL. + * + * Further dataspace types may be added later. + * + * A scalar dataspace, #H5S_SCALAR, has a single element, though that + * element may be of a complex datatype, such as a compound or array + * datatype. By convention, the rank of a scalar dataspace is always \p 0 + * (zero); think of it geometrically as a single, dimensionless point, + * though that point can be complex. + * + * A simple dataspace, #H5S_SIMPLE, consists of a regular array of elements. + * + * A null dataspace, #H5S_NULL, has no data elements. + * + * The dataspace identifier returned by this function can be released with + * H5Sclose() so that resource leaks will not occur. + * + * \version 1.4.0 Fortran subroutine introduced. + * \since 1.0.0 + * + */ H5_DLL hid_t H5Screate(H5S_class_t type); +/** + * \ingroup H5S + * \brief Creates a new simple dataspace and opens it for access + * + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims Array specifying the size of each dimension + * \param[in] maxdims Array specifying the maximum size of each dimension + * + * \return \hid_t{dataspace} + * + * \details H5Screate_simple() creates a new simple dataspace and opens it + * for access, returning a dataspace identifier. + * + * \p rank is the number of dimensions used in the dataspace. + * + * \p dims is a one-dimensional array of size rank specifying the + * size of each dimension of the dataset. \p maxdims is an array of the + * same size specifying the upper limit on the size of each dimension. + * + * Any element of \p dims can be \p 0 (zero). Note that no data can + * be written to a dataset if the size of any dimension of its current + * dataspace is \p 0. This is sometimes a useful initial state for a dataset. + * + * \p maxdims may be the null pointer, in which case the upper limit is + * the same as \p dims. Otherwise, no element of \p maxdims + * should be smaller than the corresponding element of \p dims. + * + * If an element of \p maxdims is #H5S_UNLIMITED, the maximum size of the + * corresponding dimension is unlimited. + * + * Any dataset with an unlimited dimension must also be chunked; see + * H5Pset_chunk(). Similarly, a dataset must be chunked if \p dims does + * not equal \p maxdims. + * + * The dataspace identifier returned from this function must be released with + * H5Sclose() or resource leaks will occur. + * + * \note Once a dataspace has been created, specific regions or elements in + * the dataspace can be selected and selections can be removed, as well. + * For example, H5Sselect_hyperslab() selects a region in a dataspace and + * H5Sselect_elements() selects array elements in a dataspace. These + * functions are used for subsetting. H5Sselect_none() removes all + * selections from a dataspace and is used in Parallel HDF5 when a process + * does not have or need to write data. + * + * \version 1.4.0 Fortran subroutine introduced. + * + * \since 1.0.0 + * + */ H5_DLL hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[]); +/*--------------------------------------------------------------------------*/ +/**\ingroup H5S + * + * \brief Determines the number of elements in a dataspace selection + * + * \space_id{spaceid} + * + * \return Returns the number of elements in the selection if successful; + * otherwise returns a negative value. + * + * \details H5Sget_select_npoints() determines the number of elements in + * the current selection of a dataspace. It works with any + * selection type, and is the correct way to retrieve the number + * of elements in a selection. + * + * \version 1.4.0 Fortran subroutine introduced in this release. + * \since 1.0.0 + * + */ +H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid); +/*-------------------------------------------------------------------------*/ +/**\ingroup H5S + * + * \brief Retrieves dataspace dimension size and maximum size + * + * \space_id + * \param[out] dims Pointer to array to store the size of each dimension + * \param[out] maxdims Pointer to array to store the maximum size of each + * dimension + * + * \return Returns the number of dimensions in the dataspace if successful; + * otherwise returns a negative value. + * + * \details H5Sget_simple_extent_dims() returns the size and maximum sizes + * of each dimension of a dataspace \p space_id through the \p dims + * and \p maxdims parameters. + * + * Either or both of \p dims and \p maxdims may be NULL. + * + * If a value in the returned array \p maxdims is #H5S_UNLIMITED (-1), + * the maximum size of that dimension is unlimited. + * + * \version 1.4.0 Fortran subroutine introduced. + * \since 1.0.0 + * + */ +H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], + hsize_t maxdims[]); +/*-------------------------------------------------------------------------*/ +/**\ingroup H5S + * + * \brief Determines the dimensionality of a dataspace + * + * \space_id + * + * \return Returns the number of dimensions in the dataspace if successful; + * otherwise returns a negative value. + * + * \details H5Sget_simple_extent_ndims() determines the dimensionality (or + * rank) of a dataspace. + * + * \version 1.4.0 Fortran subroutine introduced. + * \since 1.0.0 + * + */ +H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id); +/*--------------------------------------------------------------------------*/ +/**\ingroup H5S + * + * \brief Selects a hyperslab region to add to the current selected region + * + * \space_id + * \param[in] op Operation to perform on current selection + * \param[in] start Offset of start of hyperslab + * \param[in] stride Hyperslab stride + * \param[in] count Number of blocks included in hyperslab + * \param[in] block Size of block in hyperslab + * + * \return \herr_t + * + * \details H5Sselect_hyperslab() selects a hyperslab region to add to the + * current selected region for the dataspace specified by + * \p space_id. + * + * The \p start, \p stride, \p count, and \p block arrays must be the + * same size as the rank of the dataspace. For example, if the + * dataspace is 4-dimensional, each of these parameters must be a + * 1-dimensional array of size 4. + * + * The selection operator \p op determines how the new selection + * is to be combined with the already existing selection for the + * dataspace. The following operators are supported: + * + * <table> + * <tr> + * <td>#H5S_SELECT_SET</td> + * <td>Replaces the existing selection with the + * parameters from this call. Overlapping blocks + * are not supported with this operator.</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_OR</td> + * <td>Adds the new selection to the existing selection. + * (Binary OR)</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_AND</td> + * <td>Retains only the overlapping portions of the + * new selection and the existing selection. + * (Binary AND)</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_XOR</td> + * <td>Retains only the elements that are members of + * the new selection or the existing selection, + * excluding elements that are members of both + * selections. (Binary exclusive-OR, XOR) + * </td> + * </tr> + * <tr> + * <td>#H5S_SELECT_NOTB</td> + * <td>Retains only elements of the existing selection + * that are not in the new selection.</td> + * </tr> + * <tr> + * <td>#H5S_SELECT_NOTA</td> + * <td>Retains only elements of the new selection that + * are not in the existing selection.</td> + * </tr> + * </table> + * + * The \p start array specifies the offset of the starting element + * of the specified hyperslab. + * + * The \p stride array chooses array locations from the dataspace with + * each value in the \p stride array determining how many elements to + * move in each dimension. Setting a value in the \p stride array to + * \p 1 moves to each element in that dimension of the dataspace; + * setting a value of \p 2 in allocation in the \p stride array moves + * to every other element in that dimension of the dataspace. In + * other words, the \p stride determines the number of elements to + * move from the \p start location in each dimension. Stride values + * of \p 0 are not allowed. If the \p stride parameter is NULL, a + * contiguous hyperslab is selected (as if each value in the \p stride + * array were set to \p 1). + * + * The \p count array determines how many blocks to select from the + * dataspace, in each dimension. + * + * The \p block array determines the size of the element block + * selected from the dataspace. If the \p block parameter is set to + * NULL, the block size defaults to a single element in each dimension + * (as if each value in the \p block array were set to \p 1). + * + * For example, consider a 2-dimensional dataspace with hyperslab + * selection settings as follows: the \p start offset is specified as + * [1,1], \p stride is [4,4], \p count is [3,7], and \p block is [2,2]. + * In C, these settings will specify a hyperslab consisting of 21 + * 2x2 blocks of array elements starting with location (1,1) with the + * selected blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.; + * in Fortran, they will specify a hyperslab consisting of 21 2x2 + * blocks of array elements starting with location (2,2) with the + * selected blocks at locations (2,2), (6,2), (10,2), (2,6), (6,6), etc. + * + * Regions selected with this function call default to C order + * iteration when I/O is performed. + * + * \version 1.4.0 Fortran subroutine introduced in this release. + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, + const hsize_t start[], const hsize_t stride[], const hsize_t count[], + const hsize_t block[]); H5_DLL herr_t H5Sset_extent_simple(hid_t space_id, int rank, const hsize_t dims[], const hsize_t max[]); H5_DLL hid_t H5Scopy(hid_t space_id); -H5_DLL herr_t H5Sclose(hid_t space_id); H5_DLL herr_t H5Sencode2(hid_t obj_id, void *buf, size_t *nalloc, hid_t fapl); H5_DLL hid_t H5Sdecode(const void *buf); H5_DLL hssize_t H5Sget_simple_extent_npoints(hid_t space_id); -H5_DLL int H5Sget_simple_extent_ndims(hid_t space_id); -H5_DLL int H5Sget_simple_extent_dims(hid_t space_id, hsize_t dims[], hsize_t maxdims[]); H5_DLL htri_t H5Sis_simple(hid_t space_id); H5_DLL H5S_class_t H5Sget_simple_extent_type(hid_t space_id); H5_DLL herr_t H5Sset_extent_none(hid_t space_id); @@ -139,7 +410,6 @@ H5_DLL htri_t H5Sextent_equal(hid_t sid1, hid_t sid2); /* Operations on dataspace selections */ H5_DLL H5S_sel_type H5Sget_select_type(hid_t spaceid); -H5_DLL hssize_t H5Sget_select_npoints(hid_t spaceid); H5_DLL herr_t H5Sselect_copy(hid_t dst_id, hid_t src_id); H5_DLL htri_t H5Sselect_valid(hid_t spaceid); H5_DLL herr_t H5Sselect_adjust(hid_t spaceid, const hssize_t *offset); @@ -153,8 +423,6 @@ H5_DLL herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op, size_t num_ H5_DLL hssize_t H5Sget_select_elem_npoints(hid_t spaceid); H5_DLL herr_t H5Sget_select_elem_pointlist(hid_t spaceid, hsize_t startpoint, hsize_t numpoints, hsize_t buf[/*numpoints*/]); -H5_DLL herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], - const hsize_t _stride[], const hsize_t count[], const hsize_t _block[]); H5_DLL hid_t H5Scombine_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], const hsize_t _stride[], const hsize_t count[], const hsize_t _block[]); H5_DLL herr_t H5Smodify_select(hid_t space1_id, H5S_seloper_t op, hid_t space2_id); |