diff options
Diffstat (limited to 'src/H5Apublic.h')
| -rw-r--r-- | src/H5Apublic.h | 872 |
1 files changed, 819 insertions, 53 deletions
diff --git a/src/H5Apublic.h b/src/H5Apublic.h index 847f053..993961f 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -23,12 +23,14 @@ #include "H5Tpublic.h" /* Datatypes */ /* Information struct for attribute (for H5Aget_info/H5Aget_info_by_idx) */ +//! [H5A_info_t_snip] typedef struct { hbool_t corder_valid; /* Indicate if creation order is valid */ H5O_msg_crt_idx_t corder; /* Creation order */ H5T_cset_t cset; /* Character set of attribute name */ hsize_t data_size; /* Size of raw data */ } H5A_info_t; +//! [H5A_info_t_snip] /* Typedef for H5Aiterate2() callbacks */ typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_name /*in*/, @@ -45,6 +47,27 @@ 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 @@ -92,8 +115,8 @@ extern "C" { * \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); +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); H5_DLL hid_t H5Acreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t es_id); @@ -144,8 +167,626 @@ H5_DLL hid_t H5Acreate_async(const char *app_file, const char *app_func, unsigne * \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); +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 Deletes an attribute from a specified location + * + * \fgdt_loc_id + * \param[in] attr_name Name of the attribute to delete + * + * \return \herr_t + * + * \details H5Adelete() removes the attribute specified by its name, + * \p attr_name, from a file, dataset, group, or named datatype. + * This function should not be used when attribute identifiers + * are open on \p loc_id as it may cause the internal indexes of + * the attributes to change and future writes to the open + * attributes to produce incorrect results. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Adelete(hid_t loc_id, const char *attr_name); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Deletes an attribute from an object according to index order + * + * \fgdt_loc_id + * \param[in] obj_name Name of object, relative to location, from which + * attribute is to be removed + * \param[in] idx_type Type of index + * \param[in] order Order in which to iterate over index + * \param[in] n Offset within index + * \lapl_id + * + * \return \herr_t + * + * \details H5Adelete_by_idx() removes an attribute, specified by its + * location in an index, from an object. + * + * The object from which the attribute is to be removed is + * specified by a location identifier and name, \p loc_id and + * \p obj_name, respectively. If \p loc_id fully specifies the + * object from which the attribute is to be removed, \p obj_name + * should be '.' (a dot). + * + * The attribute to be removed is specified by a position in an + * index, \p n. The type of index is specified by \p idx_type and + * may be #H5_INDEX_NAME, for an alpha-numeric index by name, or + * #H5_INDEX_CRT_ORDER, for an index by creation order. The order + * in which the index is to be traversed is specified by \p order + * and may be #H5_ITER_INC (increment) for top-down iteration, + * #H5_ITER_DEC (decrement) for bottom-up iteration, or + * #H5_ITER_NATIVE, in which case HDF5 will iterate in the + * fastest-available order. For example, if \p idx_type, \p order, + * and \p n are set to #H5_INDEX_NAME, #H5_ITER_INC, and 5, + * respectively, the fifth attribute by alpha-numeric order of + * attribute names will be removed. + * + * For a discussion of \p idx_type and \p order, the valid values + * of those parameters, and the use of \p n, see the description + * of H5Aiterate2(). + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Adelete_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 lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Removes an attribute from a specified location + * + * \fgdt_loc_id + * \param[in] obj_name Name of object, relative to location, from which + * attribute is to be removed + * \param[in] attr_name Name of attribute to delete + * \lapl_id + * + * \return \herr_t + * + * \details H5Adelete_by_name() removes the attribute \p attr_name + * from an object specified by location and name, \p loc_id and + * \p obj_name, respectively. + * + * If \p loc_id fully specifies the object from which the + * attribute is to be removed, \p obj_name should be '.' (a dot). + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to + * access the object, \p obj_name. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Adelete_by_name(hid_t loc_id, const char *obj_name, + const char *attr_name, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Determines whether an attribute with a given name exists on an + * object + * + * \fgdt_loc_id{obj_id} + * \param[in] attr_name Attribute name + * + * \return \htri_t + * + * \details H5Aexists() determines whether the attribute \p attr_name + * exists on the object specified by \p obj_id. + * + * \since 1.8.0 + * + */ +H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Determines whether an attribute with a given name exists on an + * object + * + * \fgdt_loc_id{obj_id} + * \param[in] obj_name Object name + * \param[in] attr_name Attribute name + * \lapl_id + * + * \return \htri_t + * + * \details H5Aexists_by_name() determines whether the attribute + * \p attr_name exists on an object. That object is specified by + * its location and name, \p loc_id and \p obj_name, respectively. + * + * \p loc_id specifies a location in the file containing the object. + * \p obj_name is the name of the object to which the attribute is + * attached and can be a relative name, relative to \p loc_id, + * or an absolute name, based in the root group of the file. If + * \p loc_id fully specifies the object, \p obj_name should be '.' + * (a dot). + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * \p obj_name. + * + * \since 1.8.0 + * + */ +H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, + const char *attr_name, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Gets an attribute creation property list identifier + * + * \attr_id + * + * \return \hid_tv{attribute's creation property list} + * + * \details H5Aget_create_plist() returns an identifier for the attribute + * creation property list associated with the attribute specified + * by \p attr_id. + * + * The creation property list identifier should be released with + * H5Pclose(). + * + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Aget_create_plist(hid_t attr_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Retrieves attribute information, by attribute identifier + * + * \attr_id + * \param[out] ainfo Attribute information struct + * + * \return \herr_t + * + * \details H5Aget_info() retrieves attribute information, locating the + * attribute with an attribute identifier, \p attr_id, which is + * the identifier returned by H5Aopen() or H5Aopen_by_idx(). The + * attribute information is returned in the \p ainfo struct. + * + * The \p ainfo struct is defined as follows: + * \snippet this H5A_info_t_snip + * + * \p corder_valid indicates whether the creation order data is + * valid for this attribute. Note that if creation order is not + * being tracked, no creation order data will be valid. Valid + * values are \c TRUE and \c FALSE. + * + * \p corder is a positive integer containing the creation + * order of the attribute. This value is 0-based, so, for + * example, the third attribute created will have a \p corder + * value of 2. + * + * \p cset indicates the character set used for the attribute’s + * name; valid values are defined in H5Tpublic.h and include + * the following: + * \csets + * This value is set with H5Pset_char_encoding(). + * + * \p data_size indicates the size, in the number of characters, + * of the attribute. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Retrieves attribute information by attribute index position + * + * \fgdt_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 + * \param[out] ainfo Struct containing returned attribute information + * \lapl_id + * + * \return \herr_t + * + * \details H5Aget_info_by_idx() retrieves information for an attribute + * that is attached to an object, which is specified by its + * location and name, \p loc_id and \p obj_name, respectively. + * The attribute is located by its index position and the attribute + * information is returned in the \p ainfo struct. + * + * If \p loc_id fully specifies the object to which the attribute + * is attached, \p obj_name should be '.' (a dot). + * + * The attribute is located by means of 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 \p ainfo struct, which will contain the returned attribute + * information, is described in H5Aget_info(). + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, + H5_index_t idx_type, H5_iter_order_t order, hsize_t n, + H5A_info_t *ainfo /*out*/, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Retrieves attribute information, by attribute name + * + * \fgdt_loc_id + * + * \param[in] obj_name Name of object to which attribute is attached, + * relative to location + * \param[in] attr_name Attribute name + * \param[out] ainfo Struct containing returned attribute information + * \lapl_id + * + * \return \herr_t + * + * \details H5Aget_info_by_name() retrieves information for an attribute, + * \p attr_name, that is attached to an object specified by its + * location and name, \p loc_id and \p obj_name, respectively. + * The attribute information is returned in the \p ainfo struct. + * + * If \p loc_id fully specifies the object to which the attribute + * is attached, \p obj_name should be '.' (a dot). + * + * The \p ainfo struct is described in H5Aget_info(). + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to + * access the object, \p obj_name. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, + const char *attr_name, H5A_info_t *ainfo /*out*/, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Gets an attribute name + * + * \attr_id + * \param[in] buf_size The size of the buffer to store the name in + * \param[out] buf Buffer to store name in + * + * \return Returns the length of the attribute's name, which may be longer + * than \p buf_size, if successful. Otherwise returns a negative + * value. + * + * \details H5Aget_name() retrieves the name of an attribute specified by + * the identifier, \p attr_id. Up to \p buf_size characters are + * stored in \p buf followed by a \0 string terminator. If the + * name of the attribute is longer than (\p buf_size -1), the + * string terminator is stored in the last position of the buffer + * to properly terminate the string. + * + * If the user only wants to find out the size of this name, the + * values 0 and NULL can be passed in for the parameters + * \p bufsize and \p buf. + * + * \since 1.0.0 + * + */ +H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Gets an attribute name, by attribute index position + * + * \fgdt_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 + * \param[out] name Attribute name + * \param[in] size Size, in bytes, of attribute name + * \lapl_id + * + * \return Returns attribute name size, in bytes, if successful; + * otherwise returns a negative value. + * + * \details H5Aget_name_by_idx() retrieves the name of an attribute that is + * attached to an object, which is specified by its location and + * name, \p loc_id and \p obj_name, respectively. The attribute is + * located by its index position, the size of the name is specified + * in \p size, and the attribute name is returned in \p name. + * + * If \p loc_id fully specifies the object to which the attribute + * is attached, \p obj_name should be '.' (a dot). + * + * The attribute is located by means of 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(). + * + * If the attribute name’s size is unknown, the values 0 and NULL + * can be passed in for the parameters \p size and \p name. The + * function’s return value will provide the correct value for + * \p size. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * \since 1.8.0 + * + */ +H5_DLL ssize_t H5Aget_name_by_idx(hid_t loc_id, const char *obj_name, + H5_index_t idx_type, H5_iter_order_t order, hsize_t n, + char *name /*out*/, size_t size, hid_t lapl_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Gets a copy of the dataspace for an attribute + * + * \attr_id + * + * \return \hid_tv{attribute dataspace} + * + * \details H5Aget_space() retrieves a copy of the dataspace for an + * attribute. The dataspace identifier returned from this + * function must be released with H5Sclose() or resource leaks + * will develop. + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Aget_space(hid_t attr_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Returns the amount of storage required for an attribute + * + * \attr_id + * + * \return Returns the amount of storage size allocated for the attribute; + * otherwise returns 0 (zero). + * + * \details H5Aget_storage_size() returns the amount of storage that is + * required for the specified attribute, \p attr_id. + * + * \since 1.6.0 + * + */ +H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Gets an attribute datatype + * + * \attr_id + * + * \return \hid_t{datatype} + * + * \details H5Aget_type() retrieves a copy of the datatype for an attribute. + * The datatype is reopened if it is a named type before returning + * it to the application. The datatypes returned by this function + * are always read-only. If an error occurs when atomizing the + * return datatype, then the datatype is closed. + * + * The datatype identifier returned from this function must be + * released with H5Tclose() or resource leaks will develop. + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Aget_type(hid_t attr_id); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Calls user-defined function for each attribute on an object + * + * \fgdt_loc_id + * \param[in] idx_type Type of index + * \param[in] order Order in which to iterate over index + * \param[in,out] idx Initial and returned offset within index + * \param[in] op User-defined function to pass each attribute to + * \param[in,out] op_data User data to pass through to and to be returned + * by iterator operator function + * + * \return \herr_t + * Further note that this function returns the return value of the + * last operator if it was non-zero, which can be a negative value, + * zero if all attributes were processed, or a positive value + * indicating short-circuit success. + * + * \details H5Aiterate2() iterates over the attributes attached to a + * dataset, named datatype, or group, as specified by \p loc_id. + * For each attribute, user-provided data, \p op_data, with + * additional information as defined below, is passed to a + * user-defined function, \p op, which operates on that + * attribute. + * + * The order of the iteration and the attributes iterated over + * are specified by three parameters: the index type, + * \p idx_type; the order in which the index is to be traversed, + * \p order; and the attribute’s position in the index, \p idx. + * + * The type of index specified by \p idx_type can be one of the + * following: + * + * \indexes + * + * The order in which the index is to be traversed, as specified + * by \p order, can be one of the following: + * + * \orders + * + * The next attribute to be operated on is specified by \p idx, + * a position in the index. + * + * For example, if \p idx_type, \p order, and \p idx are set to + * #H5_INDEX_NAME, #H5_ITER_INC, and 5, respectively, the attribute + * in question is the fifth attribute from the beginning of the + * alpha-numeric index of attribute names. If \p order were set to + * #H5_ITER_DEC, it would be the fifth attribute from the end of + * the index. + * + * The parameter \p idx is passed in on an H5Aiterate2() call with + * one value and may be returned with another value. The value + * passed in identifies the parameter to be operated on first; + * the value returned identifies the parameter to be operated on + * in the next step of the iteration. + * + * The #H5A_operator2_t prototype for the \p op parameter is a + * user defined function where: + * The operation receives the location identifier for the group or + * dataset being iterated over, \p location_id; the name of the + * current object attribute, \p attr_name; the attribute’s info + * struct, \p ainfo; and a pointer to the operator data passed + * into H5Aiterate2(), \p op_data. + * + * Valid return values from an operator and the resulting + * H5Aiterate2() and \p op behavior are as follows: + * + * \li Zero causes the iterator to continue, returning zero when + * all attributes have been processed. + * \li A positive value causes the iterator to immediately return + * that positive value, indicating short-circuit success. The + * iterator can be restarted at the next attribute, as + * indicated by the return value of \p idx. + * \li A negative value causes the iterator to immediately return + * that value, indicating failure. The iterator can be + * restarted at the next attribute, as indicated by the return + * value of \p idx. + * + * \note This function is also available through the H5Aiterate() macro. + * \todo Add snippet for H5A_operator2_t + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, + H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Calls user-defined function for each attribute on an object + * + * \fgdt_loc_id + * \param[in] obj_name Name of object, relative to location + * \param[in] idx_type Type of index + * \param[in] order Order in which to iterate over index + * \param[in,out] idx Initial and returned offset within index + * \param[in] op User-defined function to pass each attribute to + * \param[in,out] op_data User data to pass through to and to be returned + * by iterator operator function + * \lapl_id + * + * \return \herr_t + * Further note that this function returns the return value of + * the last operator if it was non-zero, which can be a negative + * value, zero if all attributes were processed, or a positive value + * indicating short-circuit success. + * + * \details H5Aiterate_by_name() iterates over the attributes attached + * to the dataset or group specified with \p loc_id and \p obj_name. + * For each attribute, user-provided data, \p op_data, with + * additional information as defined below, is passed to a + * user-defined function, \p op, which operates on that attribute. + * + * If \p loc_id fully specifies the object to which these + * attributes are attached, \p obj_name should be '.' (a dot). + * + * The order of the iteration and the attributes iterated over + * are specified by three parameters: the index type, \p idx_type; + * the order in which the index is to be traversed, \p order; + * and the attribute’s position in the index, \p idx. + * + * The type of index specified by \p idx_type can be one of the + * following: + * + * \indexes + * + * The order in which the index is to be traversed, as specified + * by \p order, can be one of the following: + * + * \orders + * + * The next attribute to be operated on is specified by \p idx, + * a position in the index. + * + * For example, if \p idx_type, \p order, and \p idx are set to + * #H5_INDEX_NAME, #H5_ITER_INC, and 5, respectively, the attribute + * in question is the fifth attribute from the beginning of the + * alpha-numeric index of attribute names. If \p order were set to + * #H5_ITER_DEC, it would be the fifth attribute from the end of + * the index. + * + * The parameter \p idx is passed in on an H5Aiterate_by_name() + * call with one value and may be returned with another value. The + * value passed in identifies the parameter to be operated on first; + * the value returned identifies the parameter to be operated on in + * the next step of the iteration. + * + * The #H5A_operator2_t prototype for the \p op parameter is a + * user defined function where: + * The operation receives the location identifier for the group or + * dataset being iterated over, \p location_id; the name of the + * current object attribute, \p attr_name; the attribute’s info + * struct, \p ainfo; and a pointer to the operator data passed + * into H5Aiterate_by_name(), \p op_data. + * + * Valid return values from an operator and the resulting + * H5Aiterate_by_name() and \p op behavior are as follows: + * + * \li Zero causes the iterator to continue, returning zero when + * all attributes have been processed. + * \li A positive value causes the iterator to immediately return + * that positive value, indicating short-circuit success. + * The iterator can be restarted at the next attribute, as + * indicated by the return value of \p idx. + * \li A negative value causes the iterator to immediately return + * that value, indicating failure. The iterator can be + * restarted at the next attribute, as indicated by the return + * value of \p idx. + * + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to access + * the object, \p obj_name. + * + * \todo Add snippet to show H5Aoperator2_t. + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type, + H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data, + hid_t lapl_id); H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func, unsigned app_line, 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, @@ -180,7 +821,7 @@ H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func, * * \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(hid_t obj_id, const char *attr_name, hid_t aapl_id); H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id, const char *attr_name, hid_t aapl_id, hid_t es_id); /*--------------------------------------------------------------------------*/ @@ -228,8 +869,8 @@ H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned * \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 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 hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, unsigned app_line, 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, hid_t es_id); @@ -274,8 +915,8 @@ H5_DLL hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, un * \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); +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); H5_DLL hid_t H5Aopen_by_name_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id, hid_t lapl_id, hid_t es_id); @@ -305,8 +946,30 @@ H5_DLL hid_t H5Aopen_by_name_async(const char *app_file, const char *app_func, u * * \see H5Awrite() * +*/ +H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf); +/*-------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Renames an attribute + * + * \fgdt_loc_id + * \param[in] old_name Name of the attribute to be changed + * \param[in] new_name New name for the attribute + * + * \return \herr_t + * + * \details H5Arename() changes the name of the attribute located at + * \p loc_id. + * + * The old name, \p old_name, is changed to the new name, + * \p new_name. + * + * \since 1.6.0 + * */ -H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf); +H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name); H5_DLL herr_t H5Aread_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id, hid_t dtype_id, void *buf, hid_t es_id); /*--------------------------------------------------------------------------*/ @@ -343,40 +1006,13 @@ H5_DLL herr_t H5Aread_async(const char *app_file, const char *app_func, unsigned H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf); H5_DLL herr_t H5Awrite_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id, hid_t type_id, const void *buf, hid_t es_id); -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); -H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf); -H5_DLL ssize_t H5Aget_name_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, - H5_iter_order_t order, hsize_t n, char *name /*out*/, size_t size, - hid_t lapl_id); -H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id); -H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/); -H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, - H5A_info_t *ainfo /*out*/, hid_t lapl_id); -H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, - H5_iter_order_t order, hsize_t n, H5A_info_t *ainfo /*out*/, hid_t lapl_id); -H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name); H5_DLL herr_t H5Arename_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *old_name, const char *new_name, hid_t es_id); -H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char *old_attr_name, - const char *new_attr_name, hid_t lapl_id); H5_DLL herr_t H5Arename_by_name_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *obj_name, const char *old_attr_name, const char *new_attr_name, hid_t lapl_id, hid_t es_id); -H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, - H5A_operator2_t op, void *op_data); -H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type, - H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data, - hid_t lapd_id); -H5_DLL herr_t H5Adelete(hid_t loc_id, const char *name); -H5_DLL herr_t H5Adelete_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t lapl_id); -H5_DLL herr_t H5Adelete_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 lapl_id); -H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name); H5_DLL herr_t H5Aexists_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id, const char *attr_name, hbool_t *exists, hid_t es_id); -H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char *attr_name, hid_t lapl_id); H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *obj_name, const char *attr_name, hbool_t *exists, hid_t lapl_id, hid_t es_id); @@ -384,23 +1020,27 @@ H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func /** * \ingroup H5A * - * \brief Closes the specified attribute - * - * \attr_id - * - * \return \herr_t + * \fgdt_loc_id + * \param[in] obj_name Name of object, relative to location, whose + * attribute is to be renamed + * \param[in] old_attr_name Prior attribute name + * \param[in] new_attr_name New attribute name + * \lapl_id * - * \details H5Aclose() terminates access to the attribute specified by - * \p attr_id by releasing the identifier. + * \details H5Arename_by_name() changes the name of attribute that is + * attached to the object specified by \p loc_id and \p obj_name. + * The attribute named \p old_attr_name is renamed + * \p new_attr_name. * - * \attention Further use of a released attribute identifier is illegal; a - * function using such an identifier will generate an error. + * The link access property list, \p lapl_id, may provide + * information regarding the properties of links required to + * access the object, \p obj_name. * - * \since 1.0.0 + * \since 1.8.0 * - * \see H5Acreate(), H5Aopen() */ -H5_DLL herr_t H5Aclose(hid_t attr_id); +H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, + const char *old_attr_name, const char *new_attr_name, hid_t lapl_id); H5_DLL herr_t H5Aclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id, hid_t es_id); @@ -499,10 +1139,136 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam * */ 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); -H5_DLL int H5Aget_num_attrs(hid_t loc_id); -H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *attr_num, H5A_operator1_t op, void *op_data); +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Determines the number of attributes attached to an object + * + * \fgdt_loc_id + * + * \return Returns the number of attributes if successful; otherwise returns + * a negative value. + * + * \deprecated This function is deprecated in favor of the functions + * H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx(). + * + * \details H5Aget_num_attrs() returns the number of attributes attached to + * the object specified by its identifier, \p loc_id. + * + * \since 1.0.0 + * + */ +H5_DLL int H5Aget_num_attrs(hid_t loc_id); +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Calls a user’s function for each attribute on an object + * + * \todo make prototype parameter match function (idx vs attr_num) + * + * \loc_id + * \param[in,out] idx Starting (in) and ending (out) attribute index + * \param[in] op User's function to pass each attribute to + * \param[in,out] op_data User's data to pass through to iterator operator + * function + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function + * H5Aiterate2(). + * + * \details H5Aiterate1() iterates over the attributes of the object + * specified by its identifier, \p loc_id. The object can be a + * group, dataset, or named datatype. For each attribute of the + * object, the \p op_data and some additional information specified + * below are passed to the operator function \p op. The iteration + * begins with the attribute specified by its index, \p idx; the + * index for the next attribute to be processed by the operator, + * \p op, is returned in \p idx. If \p idx is the null pointer, + * then all attributes are processed. + * + * The prototype for #H5A_operator1_t is a user defined function + * where: + * The operation receives the identifier for the group, dataset + * or named datatype being iterated over, \p loc_id, the name of + * the current object attribute, \p attr_name, and the pointer to + * the operator data passed in to H5Aiterate1(), \p op_data. + * + * The return values from an operator are: + * + * \li Zero causes the iterator to continue, returning zero when + * all attributes have been processed. + * \li Positive causes the iterator to immediately return that + * positive value, indicating short-circuit success. The + * iterator can be restarted at the next attribute. + * \li Negative causes the iterator to immediately return that value, + * indicating failure. The iterator can be restarted at the next + * attribute. + * + * \todo Add snippet to show H5A_operator1_t. + * + * \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1() + * and deprecated in this release. + * + * \since 1.0.0 + * + */ +H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *idx, H5A_operator1_t op, + void *op_data); +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens the attribute specified by its index + * + * \loc_id + * \param[in] idx Index of the attribute to open + * + * \return \hid_tv{attribute} + * + * \deprecated This function is deprecated in favor of the function + * H5Aopen_by_idx(). + * + * \details H5Aopen_idx() opens an attribute which is attached to the + * object specified with \p loc_id . The location object may be + * either a group, dataset, or named datatype, all of which may + * have any sort of attribute. The attribute specified by the index, + * \p idx , indicates the attribute to access. The value of \p idx + * is a 0-based, non-negative integer. The attribute identifier + * returned from this function must be released with H5Aclose() + * or resource leaks will develop. + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx); +/* --------------------------------------------------------------------------*/ +/** + * \ingroup H5A + * + * \brief Opens an attribute specified by name + * + * \loc_id + * \param[in] name Attribute name + * + * \return \hid_tv{attribute} + * + * \deprecated This function is deprecated in favor of the function + * H5Aopen_by_name(). + * + * \details H5Aopen_name() opens an attribute specified by its name, + * \p name, which is attached to the object specified with + * \p loc_id. The location object may be either a group, dataset, + * or named datatype, which may have any sort of attribute. The + * attribute identifier returned from this function must be + * released with H5Aclose() or resource leaks will develop. + * + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Aopen_name(hid_t loc_id, const char *name); #endif /* H5_NO_DEPRECATED_SYMBOLS */ |