Hdf5 1 10 doxygen merges (#684)

* HDFFV-10865 - merge from dev, HDFArray perf fix.

* Remove duplicate setting

* Whitespace changes after clang format

* Undo version 11 clang format changes

* Merge CMake changes from develop

* test testing script merge from develop

* Update supported platforms

* PR#3 merge from develop

* Merge gcc 10 diagnostics option from develop

* Merge #318 OSX changes from develop

* Merge small changes from develop

* Minor non-space formatting changes

* #386 copyright corrections for java folder

* Merges from develop

#358 patches from vtk
#361 fix header guard spelling

* Merge updates

#358 patches from vtk
#361 fix header guard spelling

* format fix

* Fix missing underscore and make H5public.h closer to dev

* Merges from develop

#340 clang -Wformat-security warnings
#360 Fixed uninitialized warnings
header guard underscore cleanup
JNI cleanup

* format alignment

* Add missing test ref file

* Merge #380 from develop

* Finish java merges from develop

* Fix java issues with tests and javadoc

* Correct use of attribute access plist

* Remove debug code

* Remove unused variable

* Change file access to read only for java tests

* Split clang format operations.

* More javadoc comments

* Remove pre-split setting

* format source

* Change windows TS to use older VS.

* Mostly all javadoc fixes, one argument rename.

* synch file

* Merge of long double fix and compiler flags

* HDFFV-11229 merge changes from develop

* HDFFV-11229 correct test script

* HDFFV-11229 update autotools test script for two ref files

* HDFFV-11229 merge dev changes for long double display in tools

* Committing clang-format changes

* minor whitespace

* remove unneeded macro

* Committing clang-format changes

* Add "option" command for clang options

* Rework CMake add_custom to use the BYPRODUCTS argument

Update pkgconfig scripts for parallel builds.
Fix install COPYING file reference.
Remove unused round defines.
Change CMake default setting of BUILD_CPP to off.

* Fortran target depends

* Remove incorrect source attribute

* Revert define removal

* printf specifiers and VS2015 min changes

* Committing clang-format changes

* Add time struct

* TRILAB-227 and tools debug merges from develop

* Merge various changes from dev

* Issue #669 remove version from pkgcfg filename

* remove version from h5cc script

* doxygen changes merged from develop

* Committing clang-format changes

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

1 files changed, 173 insertions, 0 deletions

diff --git a/doxygen/examples/H5D_examples.c b/doxygen/examples/H5D_examples.c
new file mode 100644
index 0000000..aad057d
--- /dev/null
+++ b/doxygen/examples/H5D_examples.c
@@ -0,0 +1,173 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+#include "hdf5.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+
+int
+main(void)
+{
+    int ret_val = EXIT_SUCCESS;
+
+    //! <!-- [create] -->
+    {
+        __label__ fail_lcpl, fail_dset, fail_file;
+        hid_t file, lcpl, fspace, dset;
+
+        unsigned mode        = H5F_ACC_TRUNC;
+        char     file_name[] = "d1.h5";
+        // link names can be arbitrary Unicode strings
+        char dset_name[] = "σύνολο/δεδομένων";
+
+        if ((file = H5Fcreate(file_name, mode, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_file;
+        }
+        if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_lcpl;
+        }
+        // use UTF-8 encoding for link names
+        if (H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) {
+            ret_val = EXIT_FAILURE;
+            goto fail_fspace;
+        }
+        // create intermediate groups as needed
+        if (H5Pset_create_intermediate_group(lcpl, 1) < 0) {
+            ret_val = EXIT_FAILURE;
+            goto fail_fspace;
+        }
+        // create a 1D dataspace
+        if ((fspace = H5Screate_simple(1, (hsize_t[]){10}, NULL)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_fspace;
+        }
+        // create a 32-bit integer dataset
+        if ((dset = H5Dcreate2(file, dset_name, H5T_STD_I32LE, fspace, lcpl, H5P_DEFAULT, H5P_DEFAULT)) ==
+            H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_dset;
+        }
+
+        H5Dclose(dset);
+fail_dset:
+        H5Sclose(fspace);
+fail_fspace:
+        H5Pclose(lcpl);
+fail_lcpl:
+        H5Fclose(file);
+fail_file:;
+    }
+    //! <!-- [create] -->
+
+    //! <!-- [read] -->
+    {
+        __label__ fail_dset, fail_file;
+        hid_t file, dset;
+
+        unsigned mode        = H5F_ACC_RDONLY;
+        char     file_name[] = "d1.h5";
+        // assume a priori knowledge of dataset name and size
+        char dset_name[] = "σύνολο/δεδομένων";
+        int  elts[10];
+
+        if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_file;
+        }
+        if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_dset;
+        }
+        // read all dataset elements
+        if (H5Dread(dset, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, elts) < 0)
+            ret_val = EXIT_FAILURE;
+
+        // do something w/ the dataset elements
+
+        H5Dclose(dset);
+fail_dset:
+        H5Fclose(file);
+fail_file:;
+    }
+    //! <!-- [read] -->
+
+    //! <!-- [update] -->
+    {
+        __label__ fail_update, fail_fspace, fail_dset, fail_file;
+        hid_t file, dset, fspace;
+
+        unsigned mode           = H5F_ACC_RDWR;
+        char     file_name[]    = "d1.h5";
+        char     dset_name[]    = "σύνολο/δεδομένων";
+        int      new_elts[6][2] = {{-1, 1}, {-2, 2}, {-3, 3}, {-4, 4}, {-5, 5}, {-6, 6}};
+
+        if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_file;
+        }
+        if ((dset = H5Dopen2(file, dset_name, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_dset;
+        }
+        // get the dataset's dataspace
+        if ((fspace = H5Dget_space(dset)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_fspace;
+        }
+        // select the first 5 elements in odd positions
+        if (H5Sselect_hyperslab(fspace, H5S_SELECT_SET, (hsize_t[]){1}, (hsize_t[]){2}, (hsize_t[]){5},
+                                NULL) < 0) {
+            ret_val = EXIT_FAILURE;
+            goto fail_update;
+        }
+
+        // (implicitly) select and write the first 5 elements of the second column of NEW_ELTS
+        if (H5Dwrite(dset, H5T_NATIVE_INT, H5S_ALL, fspace, H5P_DEFAULT, new_elts) < 0)
+            ret_val = EXIT_FAILURE;
+
+fail_update:
+        H5Sclose(fspace);
+fail_fspace:
+        H5Dclose(dset);
+fail_dset:
+        H5Fclose(file);
+fail_file:;
+    }
+    //! <!-- [update] -->
+
+    //! <!-- [delete] -->
+    {
+        __label__ fail_delete, fail_file;
+        hid_t file;
+
+        unsigned mode         = H5F_ACC_RDWR;
+        char     file_name[]  = "d1.h5";
+        char     group_name[] = "σύνολο";
+        char     dset_name[]  = "σύνολο/δεδομένων";
+
+        if ((file = H5Fopen(file_name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) {
+            ret_val = EXIT_FAILURE;
+            goto fail_file;
+        }
+        // delete (unlink) the dataset
+        if (H5Ldelete(file, dset_name, H5P_DEFAULT) < 0) {
+            ret_val = EXIT_FAILURE;
+            goto fail_delete;
+        }
+        // the previous call deletes (unlinks) only the dataset
+        if (H5Ldelete(file, group_name, H5P_DEFAULT) < 0) {
+            ret_val = EXIT_FAILURE;
+            goto fail_delete;
+        }
+
+fail_delete:
+        H5Fclose(file);
+fail_file:;
+    }
+
+    //! <!-- [delete] -->
+
+    return ret_val;
+}