summaryrefslogtreecommitdiffstats
path: root/src/H5Apublic.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/H5Apublic.h')
-rw-r--r--src/H5Apublic.h265
1 files changed, 60 insertions, 205 deletions
diff --git a/src/H5Apublic.h b/src/H5Apublic.h
index 0198668..410eb1e 100644
--- a/src/H5Apublic.h
+++ b/src/H5Apublic.h
@@ -78,11 +78,11 @@ extern "C" {
*
* \return \herr_t
*
- * \details H5Aclose() terminates access to the attribute specified by
- * \p attr_id by releasing the identifier.
+ * \details H5Aclose() terminates access to the attribute through
+ * \p attr_id and releases the identifier.
*
- * \attention Further use of a released attribute identifier is illegal; a
- * function using such an identifier will generate an error.
+ * \par Example
+ * \snippet H5A_examples.c create
*
* \since 1.0.0
*
@@ -110,27 +110,19 @@ H5_DLL herr_t H5Aclose(hid_t attr_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.
+ * \p type_id and \p space_id.
*
- * 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.
+ * \plist_unused{acpl}
*
* The attribute identifier returned by this function must be released
* with H5Aclose() resource leaks will develop.
*
- * \note The \p aapl parameter is 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.
*
+ * \par Example
+ * \snippet H5A_examples.c create
+ *
* \since 1.8.0
*
* \see H5Aclose()
@@ -160,28 +152,19 @@ H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_
* 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).
+ * name relative to \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.
+ * dataspace, \p type_id and \p space_id.
*
- * 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.
+ * \plist_unused{aapl}
*
* 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
*
*/
@@ -200,10 +183,14 @@ H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *a
*
* \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.
+ *
+ * \attention This function should not be used when other attribute identifiers
+ * are open on \p loc_id. This may cause the internal indexes of
+ * the attributes to change and future writes to the open
+ * attributes to produce incorrect results.
+ *
+ * \par Example
+ * \snippet H5A_examples.c delete
*
* \since 1.0.0
*
@@ -230,27 +217,16 @@ H5_DLL herr_t H5Adelete(hid_t loc_id, const char *attr_name);
*
* 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).
+ * \p obj_name, respectively.
*
* 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,
+ * index, \p n. The type of index is specified by \p idx_type.
+ * The order in which the index is to be traversed is specified by
+ * \p 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
+ * respectively, the fifth attribute in lexicographic 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.
@@ -278,9 +254,6 @@ H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t id
* 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.
@@ -329,9 +302,7 @@ H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name);
* \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).
+ * or an absolute name, based in the root group of the file.
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
@@ -355,9 +326,6 @@ H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char *
* 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
*
*/
@@ -374,32 +342,9 @@ H5_DLL hid_t H5Aget_create_plist(hid_t attr_id);
* \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 with an attribute identifier, \p attr_id. 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
*
*/
@@ -427,16 +372,9 @@ H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/);
* 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().
+ * \p order and \p n, respectively.
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
@@ -454,8 +392,7 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t
* \brief Retrieves attribute information, by attribute name
*
* \fgdt_loc_id
- *
- * \param[in] obj_name Name of object to which attribute is attached,
+ * \param[in] obj_name Name of the object to which an attribute is attached,
* relative to location
* \param[in] attr_name Attribute name
* \param[out] ainfo Struct containing returned attribute information
@@ -468,11 +405,6 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t
* 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.
@@ -503,8 +435,8 @@ H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char
* 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
+ * If the user only wants to retrieve the name length, the
+ * values 0 and NULL should be passed for the parameters
* \p bufsize and \p buf.
*
* \since 1.0.0
@@ -515,7 +447,7 @@ 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
+ * \brief Gets an attribute name by attribute index position
*
* \fgdt_loc_id
* \param[in] obj_name Name of object to which attribute is attached,
@@ -536,13 +468,9 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf);
* 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().
+ * \p order and \p n, respectively.
*
* 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
@@ -582,7 +510,7 @@ H5_DLL hid_t H5Aget_space(hid_t attr_id);
/**
* \ingroup H5A
*
- * \brief Returns the amount of storage required for an attribute
+ * \brief Returns the amount of storage used to store an attribute
*
* \attr_id
*
@@ -600,17 +528,16 @@ H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id);
/**
* \ingroup H5A
*
- * \brief Gets an attribute datatype
+ * \brief Gets an attribute's datatype
*
* \attr_id
*
* \return \hid_t{datatype}
*
- * \details H5Aget_type() retrieves a copy of the datatype for an attribute.
+ * \details H5Aget_type() retrieves a copy of the attribute's datatype.
* 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.
+ * are always read-only.
*
* The datatype identifier returned from this function must be
* released with H5Tclose() or resource leaks will develop.
@@ -623,7 +550,7 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
/**
* \ingroup H5A
*
- * \brief Calls user-defined function for each attribute on an object
+ * \brief Calls a user-defined function for each attribute on an object
*
* \fgdt_loc_id
* \param[in] idx_type Type of index
@@ -650,17 +577,6 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
* 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.
*
@@ -677,11 +593,6 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
* the value returned identifies the parameter to be operated on
* in the next step of the iteration.
*
- * \p op is a user-defined function whose prototype is defined
- * as follows:
- * \snippet this H5A_operator2_t_snip
- * \click4more
- *
* \note This function is also available through the H5Aiterate() macro.
*
* \since 1.8.0
@@ -717,24 +628,10 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord
* 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.
*
@@ -751,25 +648,6 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord
* the value returned identifies the parameter to be operated on in
* the next step of the iteration.
*
- * \p op is a user-defined function whose prototype is defined
- * as follows:
- * \snippet this H5A_operator2_t_snip
- * \click4more
- *
- * 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.
@@ -796,8 +674,7 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t
* \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.
+ * \plist_unused{aapl_id}
*
* This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called
* before the attribute can be accessed for any further purpose,
@@ -806,6 +683,9 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t
* The attribute identifier returned by this function must be released
* with H5Aclose() or resource leaks will develop.
*
+ * \par Example
+ * \snippet H5A_examples.c read
+ *
* \since 1.8.0
*
* \see H5Aclose(), H5Acreate()
@@ -830,17 +710,13 @@ H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id);
*
* \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).
+ * \p obj_name, respectively.
*
* 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().
+ * \p n, respectively.
*
- * The attribute access property list, \p aapl_id, is currently
- * unused and should currently be #H5P_DEFAULT.
+ * \plist_unused{aapl_id}
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
@@ -879,11 +755,9 @@ H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_t
*
* \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).
+ * \p loc_id.
*
- * The attribute access property list, \p aapl_id, is currently
- * unused and should currently be #H5P_DEFAULT.
+ * \plist_unused{aapl_id}
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
@@ -920,6 +794,9 @@ H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *att
* Datatype conversion takes place at the time of a read or write and
* is automatic.
*
+ * \par Example
+ * \snippet H5A_examples.c read
+ *
* \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.
@@ -967,15 +844,12 @@ H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name
* 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.
*
+ * \par Example
+ * \snippet H5A_examples.c update
+ *
* \version 1.8.8 Fortran updated to Fortran2003.
* \version 1.4.2 Fortran \p dims parameter added in this release
* \since 1.0.0
@@ -1057,9 +931,9 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam
*
* \return \hid_tv{attribute}
*
- * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT.
+ * \deprecation_note{H5Acreate2()}
*
- * \deprecated Deprecated in favor of H5Acreate2()
+ * \plist_unused{acpl}
*
* \details H5Acreate1() creates an attribute, \p name, which is attached
* to the object specified by the identifier \p loc_id.
@@ -1067,18 +941,7 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam
* 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.
+ * \p type_id and \p space_id.
*
* \since 1.8.0
*
@@ -1100,8 +963,7 @@ H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa
* \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().
+ * \deprecation_note{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.
@@ -1124,8 +986,7 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
*
* \return \herr_t
*
- * \deprecated This function is deprecated in favor of the function
- * H5Aiterate2().
+ * \deprecation_note{H5Aiterate2()}
*
* \details H5Aiterate1() iterates over the attributes of the object
* specified by its identifier, \p loc_id. The object can be a
@@ -1137,10 +998,6 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
* \p op, is returned in \p idx. If \p idx is the null pointer,
* then all attributes are processed.
*
- * \p op is a user-defined function whose prototype is defined as follows:
- * \snippet this H5A_operator1_t_snip
- * \click4more
- *
* \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1()
* and deprecated in this release.
* \since 1.0.0
@@ -1158,8 +1015,7 @@ H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *idx, H5A_operator1_t op, void
*
* \return \hid_tv{attribute}
*
- * \deprecated This function is deprecated in favor of the function
- * H5Aopen_by_idx().
+ * \deprecation_note{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
@@ -1185,8 +1041,7 @@ H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx);
*
* \return \hid_tv{attribute}
*
- * \deprecated This function is deprecated in favor of the function
- * H5Aopen_by_name().
+ * \deprecation_note{H5Aopen_by_name()}
*
* \details H5Aopen_name() opens an attribute specified by its name,
* \p name, which is attached to the object specified with