summaryrefslogtreecommitdiffstats
path: root/src/H5Apublic.h
diff options
context:
space:
mode:
authorbljhdf <58825073+bljhdf@users.noreply.github.com>2020-12-16 03:17:41 (GMT)
committerGitHub <noreply@github.com>2020-12-16 03:17:41 (GMT)
commitf09ec2657cb0ab9b646f8a4a1d5302444c38bf72 (patch)
tree5aa8835276ebc6e48f973b6b778167d55ec6a4b8 /src/H5Apublic.h
parentf3629d6148970b43f1625d62e01d57adc7d5fa5d (diff)
downloadhdf5-f09ec2657cb0ab9b646f8a4a1d5302444c38bf72.zip
hdf5-f09ec2657cb0ab9b646f8a4a1d5302444c38bf72.tar.gz
hdf5-f09ec2657cb0ab9b646f8a4a1d5302444c38bf72.tar.bz2
Doxygen - RM entries for H5A, H5S, and H5P APIs (#181)
* Doxygen - RM entries for H5A, H5S, and H5P APIs * fix issues on ubuntu * added missing H5F_fspace_strategy_t_snip
Diffstat (limited to 'src/H5Apublic.h')
-rw-r--r--src/H5Apublic.h872
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 */