diff options
author | Gerd Heber <gheber@hdfgroup.org> | 2021-04-26 19:07:29 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-04-26 19:07:29 (GMT) |
commit | 1d680fe04c545d601678d876ad22dea7bfc31edd (patch) | |
tree | f84a97c149df9ccf4409c5bfea04a7316c019e8a /src/H5Mpublic.h | |
parent | 12082e728de7481144db7ea3cca6f38acf0a7cac (diff) | |
download | hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.zip hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.tar.gz hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.tar.bz2 |
Merge doxygen2 into develop (#553)
* Fixed warnings and started H5Epublic.h.
* Include H5FD* headers to correctly resolve references.
* Doxygen2 (#330)
* H5Eauto_is_v2.
* Added a few more calls.
* Added a few more H5E calls.
* First cut of H5E v2.
* Added the deprecated v1 calls.
* Updated spacing.
* Once more.
* Taking some inspiration from Eigen3.
* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pen… (#352)
* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pencode1, H5Pget_filter_by_id1,H5Pget_version, H5Pset_file_space,H5Pget_file_space. Someone already adds H5Pget_filter1. Also fixs an extra parameter 'close' call back function for HPregister2.
* doxygen work. fixs format by using clang-format.
* doxgen work for H5Pregister1 etc. Addressed Barbara and Gerd's comments.
For Quincey's comments, since we are not supposed to change the source code.
I leave this to future improvements.
* added documentation for H5P APIs (#350)
* add documenation for H5Pget_buffer,H5Pget_data_transform,H5Pget_edc_check,H5Pget_hyper_vector_size,H5Pget_preserve,H5Pget_type_conv_cb,H5Pget_vlen_mem_manager,H5Pset_btree_ratios
* format corrections
* fixed grammer
* fixed herr_t
* Better name.
* A fresh look.
* add doxygen to H5Ppublic.h
* use attention instead of warning
* Add doxygen comments in H5Ppublic.h (#375)
* Add doxygen comments in H5Ppublic.h
* H5Pset_meta_block_size
* H5Pset_metadata_read_attempts
* H5Pset_multi_type
* H5Pset_object_flush_cb
* H5Pset_sieve_buf_size
* H5Pset_small_data_block_size
* H5Pset_all_coll_metadata_ops
* H5Pget_all_coll_metadata_ops
* Add DOXYGEN_EXAMPLES_DIR to src/CMakeLists.txt
* Fix clang-format errors
* Fix filenames in doxygen/examples
* add doxygen to H5Ppublic.h (#378)
* add doxygen to H5Ppublic.h
* use attention instead of warning
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
* Revert "add doxygen to H5Ppublic.h (#378)"
This reverts commit 2ee1821b138a5c00b15ea57ce9e950367480f5f2.
* Updated Doxygen variables.
* I forgot to copy two images.
* Enable desktop search by default.
* Add my assigned Doxygen documentation.
* Remove whitespace at EOL. Appease clang-format.
* Addressed Chris' comments.
* Added an alias for asynchronous functions.
* One space is enough for all of us.
* Slightly restructured RM page.
* address some issues
* reformatting
* Style external links.
* reformatting
* reformatting
* Added "Metadata Caching in HDF5" as a technical note example.
* Revise this soon!
* Added specification examples.
* Fixed references.
* Added H5AC cache image stuff and file format study.
* Added older FMT versions. Where did 1.0 go?
* Updated C/C++ note and replaced ambiguous labels.
* Reformat source with clang v10.0.1.
* Added the VFL technical note.
* Added what I believe might be called version 1.0 of the format.
* Added the remaining specs.
* Added H5Z callback documentation and fixed a few mistakes.
* Added dox for deprecated H5G calls and fixed a few snippet blockIDs.
* clang-format happy?
* Ok?
* Bonus track: Deprecated H5D functions.
* Carry over the more detailed group description.
* Added documentation for the missing and deprecated H5R calls.
* Life is easier and less repetitive w/ snippets. Use them!
* Eliminate the snippet block ID artifacts in the HTML rendering.
* Fixed snippet HTML artifacts and added a few missing calls.
* Under 20 H5Ps to go!
* Almost complete!
* "This is a form of pedantry up with which I will not put." (Churchill)
* Let's not waste as much space on bulleted lists!
* First complete (?) draft of the Doxygen-based RM.
* Completeness check and minor fixes along the way.
* Pedantry.
* Adding missing H5FD calls checkpoint.
* Pedantry.
* More pedantry.
* Added H5Pset_fapl_log.
* First draft of H5ES.
* Fixed warnings.
* Prep. for map module.
* First cut of the map module.
* Pedantry.
* Possible H5F introduction.
* Fix the indentation.
* Pedantry.
* Ditto.
* Thanks to the reviewers for their comments.
* Added missing images.
* Line numbers are a distraction here.
* More examples, references, and clean-up. Don't repeat yourself!
* Clang pedantry.
* Ditto.
* More reviewer comments...
* Templatized references and cleaned up \todos.
* Committing clang-format changes
* Fixed MANIFEST.
* Addressed Quincey's comments. (OCPLs)
* Fixed a few more \todo items.
* Fixed more \todo items.
* Added attribute life cycle.
* Forgot the examples file.
* Committing clang-format changes
* Pedantry.
* Live and learn!
* Added a sample H5D life cycle.
* Committing clang-format changes
* Pedantry.
Co-authored-by: kyang2014 <kyang2014@users.noreply.github.com>
Co-authored-by: Scot Breitenfeld <brtnfld@hdfgroup.org>
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
Co-authored-by: Christopher Hogan <ChristopherHogan@users.noreply.github.com>
Co-authored-by: jya-kmu <53388330+jya-kmu@users.noreply.github.com>
Co-authored-by: David Young <dyoung@hdfgroup.org>
Co-authored-by: Larry Knox <lrknox@hdfgroup.org>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Diffstat (limited to 'src/H5Mpublic.h')
-rw-r--r-- | src/H5Mpublic.h | 373 |
1 files changed, 368 insertions, 5 deletions
diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h index 4d8bef4..e0be828 100644 --- a/src/H5Mpublic.h +++ b/src/H5Mpublic.h @@ -61,8 +61,12 @@ typedef enum H5VL_map_specific_t { H5VL_MAP_DELETE /* H5Mdelete */ } H5VL_map_specific_t; -/* Callback for H5Miterate() */ +//! <!-- [H5M_iterate_t_snip] --> +/** + * Callback for H5Miterate() + */ typedef herr_t (*H5M_iterate_t)(hid_t map_id, const void *key, void *op_data); +//! <!-- [H5M_iterate_t_snip] --> /********************/ /* Public Variables */ @@ -81,38 +85,397 @@ extern "C" { */ #ifdef H5_HAVE_MAP_API +/** + * \ingroup H5M + * + * \brief Creates a map object + * + * \fgdta_loc_id + * \param[in] name Map object name + * \type_id{key_type_id} + * \type_id{val_type_id} + * \lcpl_id + * \mcpl_id + * \mapl_id + * \returns \hid_t{map object} + * + * \details H5Mcreate() creates a new map object for storing key-value + * pairs. The in-file datatype for keys is defined by \p key_type_id + * and the in-file datatype for values is defined by \p val_type_id. \p + * loc_id specifies the location to create the the map object and \p + * name specifies the name of the link to the map object relative to + * \p loc_id. + * + * \since 1.13.0 + * + */ H5_DLL hid_t H5Mcreate(hid_t loc_id, const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id, hid_t mcpl_id, hid_t mapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mcreate} + */ H5_DLL hid_t H5Mcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id, hid_t mcpl_id, hid_t mapl_id, hid_t es_id); + +/** + * \ingroup H5M + * + * \brief + * + * \details + * + * \since 1.13.0 + * + */ H5_DLL hid_t H5Mcreate_anon(hid_t loc_id, hid_t key_type_id, hid_t val_type_id, hid_t mcpl_id, hid_t mapl_id); + +/** + * \ingroup H5M + * + * \brief Opens a map object + * + * \fgdta_loc_id{loc_id} + * \param[in] name Map object name relative to \p loc_id + * \mapl_id + * \returns \hid_t{map object} + * + * \details H5Mopen() finds a map object specified by \p name under the location + * specified by \p loc_id. The map object should be close with + * H5Mclose() when the application is not longer interested in + * accessing it. + * + * \since 1.13.0 + * + */ H5_DLL hid_t H5Mopen(hid_t loc_id, const char *name, hid_t mapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mopen} + */ H5_DLL hid_t H5Mopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t mapl_id, hid_t es_id); + +/** + * \ingroup H5M + * + * \brief Terminates access to a map object + * + * \map_id + * \returns \herr_t + * + * \details H5Mclose() closes access to a map object specified by \p map_id and + * releases resources used by it. + * + * It is illegal to subsequently use that same map identifier in calls + * to other map functions. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Mclose(hid_t map_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mclose} + */ H5_DLL herr_t H5Mclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id, hid_t es_id); -H5_DLL hid_t H5Mget_key_type(hid_t map_id); -H5_DLL hid_t H5Mget_val_type(hid_t map_id); -H5_DLL hid_t H5Mget_create_plist(hid_t map_id); -H5_DLL hid_t H5Mget_access_plist(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets key datatype for a map object + * + * \map_id + * \returns \hid_t{datatype} + * + * \details H5Mget_key_type() retrieves key datatype as stored in the file for a + * map object specified by \p map_id and returns identifier for the + * datatype. + * + * \since 1.13.0 + * + */ +H5_DLL hid_t H5Mget_key_type(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets value datatype for a map object + * + * \map_id + * \returns \hid_t{datatype} + * + * \details H5Mget_val_type() retrieves value datatype as stored in the file for + * a map object specified by \p map_id and returns identifier for the + * datatype . + * + * \since 1.13.0 + * + */ +H5_DLL hid_t H5Mget_val_type(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets creation property list for a map object + * + * \map_id + * \returns \hid_t{map creation property list} + * + * \details H5Mget_create_plist() returns an identifier for a copy of the + * creation property list for a map object specified by \p map_id. + * + * \since 1.13.0 + * + */ +H5_DLL hid_t H5Mget_create_plist(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets access property list for a map object + * + * \map_id + * \returns \hid_t{map access property list} + * + * \details H5Mget_access_plist() returns an identifier for a copy of the access + * property list for a map object specified by \p map_id. + * + * \since 1.13.0 + * + */ +H5_DLL hid_t H5Mget_access_plist(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Retrieves the number of key-value pairs in a map object + * + * \map_id + * \param[out] count The number of key-value pairs stored in the map object + * \dxpl_id + * \returns \herr_t + * + * \details H5Mget_count() retrieves the number of key-value pairs stored in a + * map specified by map_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Mget_count(hid_t map_id, hsize_t *count, hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Adds a key-value pair to a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \type_id{val_mem_type_id} + * \param[in] value Pointer to value buffer + * \dxpl_id + * \returns \herr_t + * + * \details H5Mput() adds a key-value pair to a map object specified by \p + * map_id, or updates the value for the specified key if one was set + * previously. + * + * \p key_mem_type_id and \p val_mem_type_id specify the datatypes for + * the provided key and value buffers, and if different from those used + * to create the map object, the key and value will be internally + * converted to the datatypes for the map object. + * + * Any further options can be specified through the property list + * \p dxpl_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Mput(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, const void *value, hid_t dxpl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mput} + */ H5_DLL herr_t H5Mput_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, const void *value, hid_t dxpl_id, hid_t es_id); + +/** + * \ingroup H5M + * + * \brief Retrieves a key-value pair from a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \type_id{val_mem_type_id} + * \param[out] value Pointer to value buffer + * \dxpl_id + * \returns \herr_t + * + * \details H5Mget() retrieves from a map object specified by \p map_id, the + * value associated with the provided key \p key. \p key_mem_type_id + * and \p val_mem_type_id specify the datatypes for the provided key + * and value buffers. If if the datatype specified by \p + * key_mem_type_id is different from that used to create the map object + * the key will be internally converted to the datatype for the map + * object for the query, and if the datatype specified by \p + * val_mem_type_id is different from that used to create the map object + * the returned value will be converted to have a datatype as specified + * by \p val_mem_type_id before the function returns. + * + * Any further options can be specified through the property list + * \p dxpl_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Mget(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, void *value, hid_t dxpl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mget} + */ H5_DLL herr_t H5Mget_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, void *value, hid_t dxpl_id, hid_t es_id); + +/** + * \ingroup H5M + * + * \brief Checks if provided key exists in a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \param[out] exists Pointer to a buffer to return the existence status + * \dxpl_id + * \returns \herr_t + * + * \details H5Mexists() checks if the provided key is stored in the map object + * specified by \p map_id. If \p key_mem_type_id is different from that + * used to create the map object the key will be internally converted + * to the datatype for the map object for the query. + * + * Any further options can be specified through the property list + * \p dxpl_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Mexists(hid_t map_id, hid_t key_mem_type_id, const void *key, hbool_t *exists, hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Iterates over all key-value pairs in a map object + * + * \map_id + * \param[in,out] idx iteration index + * \type_id{key_mem_type_id} + * \param[in] op User-defined iterator function + * \op_data + * \dxpl_id + * \returns \herr_t + * + * \details H5Miterate() iterates over all key-value pairs stored in the map + * object specified by \p map_id, making the callback specified by \p + * op for each. The \p idx parameter is an in/out parameter that may be + * used to restart a previously interrupted iteration. At the start of + * iteration \p idx should be set to 0, and to restart iteration at the + * same location on a subsequent call to H5Miterate(), \p idx should be + * the same value as returned by the previous call. Iterate callback is + * defined as: + * \snippet this H5M_iterate_t_snip + * The \p key parameter is the buffer for the key for this iteration, + * converted to the datatype specified by \p key_mem_type_id. The \p + * op_data parameter is a simple pass through of the value passed to + * H5Miterate(), which can be used to store application-defined data for + * iteration. A negative return value from this function will cause + * H5Miterate() to issue an error, while a positive return value will + * cause H5Miterate() to stop iterating and return this value without + * issuing an error. A return value of zero allows iteration to continue. + * + * Any further options can be specified through the property list \p dxpl_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Miterate(hid_t map_id, hsize_t *idx, hid_t key_mem_type_id, H5M_iterate_t op, void *op_data, hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Iterates over all key-value pairs in a map object + * + * \loc_id + * \param[in] map_name Map object name relative to the location specified by \p loc_id + * \param[in,out] idx Iteration index + * \type_id{key_mem_type_id} + * \param[in] op User-defined iterator function + * \op_data + * \dxpl_id + * \lapl_id + * \returns \herr_t + * + * \details H5Miterate_by_name() iterates over all key-value pairs stored in the + * map object specified by \p map_id, making the callback specified by + * \p op for each. The \p idx parameter is an in/out parameter that may + * be used to restart a previously interrupted iteration. At the start + * of iteration \p idx should be set to 0, and to restart iteration at + * the same location on a subsequent call to H5Miterate(), \p idx + * should be the same value as returned by the previous call. Iterate + * callback is defined as: + * \snippet this H5M_iterate_t_snip + * The\p key parameter is the buffer for the key for this iteration, + * converted to the datatype specified by \p key_mem_type_id. The \p + * op_data parameter is a simple pass through of the value passed to + * H5Miterate(), which can be used to store application-defined data + * for iteration. A negative return value from this function will cause + * H5Miterate() to issue an error, while a positive return value will cause + * H5Miterate() to stop iterating and return this value without issuing an + * error. A return value of zero allows iteration to continue. + * + * Any further options can be specified through the property list \p dxpl_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Miterate_by_name(hid_t loc_id, const char *map_name, hsize_t *idx, hid_t key_mem_type_id, H5M_iterate_t op, void *op_data, hid_t dxpl_id, hid_t lapl_id); + +/** + * \ingroup H5M + * + * \brief Deletes a key-value pair from a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \dxpl_id + * \returns \herr_t + * + * \details H5Mdelete() deletes a key-value pair from the map object specified + * by \p map_id. \p key_mem_type_id specifies the datatype for the + * provided key buffer key, and if different from that used to create + * the map object, the key will be internally converted to the datatype + * for the map object. + * + * Any further options can be specified through the property list \p dxpl_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t dxpl_id); /* API Wrappers for async routines */ |