From ccf640e622cc1aff7468687f0a2cfaecb423d632 Mon Sep 17 00:00:00 2001 From: Eugen Wintersberger Date: Thu, 2 Nov 2017 11:37:22 +0100 Subject: [PATCH] Done with overview. Update #110 --- design/model.notation | 2390 ++----------------- design/model.uml | 227 +- doc/source/images/CMakeLists.txt | 2 + doc/source/images/hdf5_node_types.svg | 115 + doc/source/images/hdf5_package_overview.svg | 350 +++ doc/source/users_guide/overview.rst | 72 + 6 files changed, 790 insertions(+), 2366 deletions(-) create mode 100644 doc/source/images/hdf5_node_types.svg create mode 100644 doc/source/images/hdf5_package_overview.svg diff --git a/design/model.notation b/design/model.notation index b1159f5705..ab0aa3150c 100644 --- a/design/model.notation +++ b/design/model.notation @@ -1,302 +1,6 @@ - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - -
- - - - - - - - -
- - - - - - - - - - - - -
- - - -
- - - - - - - - -
- - - - - - - - -
- - - - - - - - -
- - - - - - - - -
- - - - - - - - -
- - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-
-
-
-
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -310,15 +14,6 @@
- - - - - - - - - @@ -326,7 +21,7 @@ - + @@ -338,7 +33,7 @@ - + @@ -350,7 +45,7 @@ - + @@ -362,22 +57,7 @@ - - - - -
- - -
- - - - - - - - + @@ -389,309 +69,207 @@ - +
- + - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - + - - -
+ + +
- - - + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - + + - - -
+ + +
- - - + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - + + - - -
+ + +
- - - + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - + + - - -
+ + +
- - - - - - - - - - - - - - - - - - - - - + + + + - - + + - - -
+ + +
- - - + + + - - - - - + + + + + - - - - - - - - - - - - - - + + - - -
+ + +
- - - - - - - - - + + + - - - - - + + + + + - - - - - - - - + + - - -
+ + +
- - - + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - + + - - -
- - - - + + + + - - - - - + + + + + - - - - - + + + + + - - - - - + + + + + - - + + @@ -703,9 +281,9 @@ - + - + @@ -716,1358 +294,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - -
- - - - - - - - - - - - -
- - - - - - - - - - - - - - - -
- - - -
- - - - - - - - -
- - - - - - - - -
- - - - - - - - -
- - - - - - - - -
- - - - - - - - -
- - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - -
- - - - - - -
- - - - - - -
- - - - - - -
- - - - - - -
- - - - - - - - - - - - - -
- - - - - - -
- - - - - - -
- - - - - - -
- - - - - - -
- - - - - - -
- - - - - - - - - - - - - -
- - - - - -
- - - - - -
- - - - - -
- - - - - -
- - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -4699,11 +2925,6 @@ - - - - - @@ -4730,83 +2951,57 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -4844,67 +3039,21 @@ - - - - - - + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -5013,36 +3162,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -5103,32 +3222,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -5275,21 +3368,6 @@ - - - - - - - - - - - - - - - @@ -5347,7 +3425,7 @@ - + @@ -5373,7 +3451,7 @@ - + @@ -5399,7 +3477,7 @@ - + @@ -5425,7 +3503,7 @@ - + @@ -5771,38 +3849,38 @@ - + - + - + - + - + - + - + - - - + + + diff --git a/design/model.uml b/design/model.uml index fea2ae597c..f30c1b9f13 100644 --- a/design/model.uml +++ b/design/model.uml @@ -1,96 +1,8 @@ - - This is a named datatype -and should not mixed up with -an instance of datatype::Datatype. -Though one can construct this one -from the former one. - - - - - Need to overload the following operators and constructor - --> copy constructor --> move constructor --> copy assignment --> move assignment - -This should ensure correct reference counting for an ID. -The destructor ensures that the correct close function is called whenever an instance of id_t losses scope. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - -
- - - - - - -
- - - - - - @@ -342,7 +254,6 @@ Such an approach needs to be discussed to. - @@ -394,7 +305,6 @@ Such an approach needs to be discussed to. - @@ -566,123 +476,31 @@ Such an approach needs to be discussed to. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - + - + - + - + - + - + - + - - - - - - - - - - @@ -894,28 +712,8 @@ Such an approach needs to be discussed to. - - - - - - - - - - - - - - - - - - - - @@ -1090,6 +888,15 @@ Such an approach needs to be discussed to. + + + + + + + + +
diff --git a/doc/source/images/CMakeLists.txt b/doc/source/images/CMakeLists.txt index 2b5d50e7bc..2b464fceeb 100644 --- a/doc/source/images/CMakeLists.txt +++ b/doc/source/images/CMakeLists.txt @@ -6,6 +6,8 @@ set(IMAGES attribute_manager_uml.png hdf5_attributes.svg hdf5_basic_tree.svg hdf5_links.svg + hdf5_package_overview.svg + hdf5_node_types.svg ) add_sphinx_source(${IMAGES}) diff --git a/doc/source/images/hdf5_node_types.svg b/doc/source/images/hdf5_node_types.svg new file mode 100644 index 0000000000..23c6ee1a24 --- /dev/null +++ b/doc/source/images/hdf5_node_types.svg @@ -0,0 +1,115 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Node + + + + + +Dataset + + + +Datatype + + + +Group + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/source/images/hdf5_package_overview.svg b/doc/source/images/hdf5_package_overview.svg new file mode 100644 index 0000000000..2513cf6769 --- /dev/null +++ b/doc/source/images/hdf5_package_overview.svg @@ -0,0 +1,350 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +hdf5 + + + + + + +attribute + + + + + + +dataspace + + + + + + +datatype + + + + + + +node + + + + + + +error + + + + + + +property + + +Path + + + +ObjectHandle + + + +ObjectId + + + + + + + +file + +«Enumeration» + +IterationOrder + + +«Enumeration» + +IterationIndex + + + +IteratorConfig + + + +Dimensions + + + + + diff --git a/doc/source/users_guide/overview.rst b/doc/source/users_guide/overview.rst index c6c2847b28..5b607c6b03 100644 --- a/doc/source/users_guide/overview.rst +++ b/doc/source/users_guide/overview.rst @@ -134,3 +134,75 @@ remains constant once a node has been created within a particular file. *h5cpp* a C++ wrapper for *HDF5* ================================ + +Including a single header file is enough to use *h5cpp* in your code + +.. code-block:: cpp + + #include + +This will pull in everything you need. The entire library is organized in +several namespaces with a top level namespace :cpp:any:`hdf5` + +.. figure:: ../images/hdf5_package_overview.svg + :align: center + :width: 85% + +The most important classes in the top-level namspace might be +:cpp:class:`hdf5::Dimensions` and :cpp:class:`hdf5::Path`. +The former one is merely a type alias + +.. code-block:: cpp + + using Dimensions = std::vector; + +in order to get rid of the rather nasty + +.. code-block:: cpp + + hsize_t *dims; + +which is heavily used throughout the C-API and thus a rather potential source +for memory leaks. Using :cpp:class:`std::vector` for this thus solves a lot +of problems and makes life just easy. + +:cpp:class:`Path` as the name already suggests represents an HDF5 path to +reference a node within a file. We will discuss this class in more detail later. + ++----------------------------+------------------------------------------------+ +| namespace | description | ++============================+================================================+ +| :cpp:any:`hdf5::property` | namespace with property list implementations. | ++----------------------------+------------------------------------------------+ +| :cpp:any:`hdf5::attribute` | contains all classes related to attributes and | +| | attribute management. | ++----------------------------+------------------------------------------------+ +| :cpp:any:`hdf5::datatype` | datatypes and related utility functions. The | +| | classes in this namespace should not be | +| | confused with *commited datatypes* which are | +| | indeed nodes. | ++----------------------------+------------------------------------------------+ +| :cpp:any:`hdf5::node` | the most imporant namespace providing all | +| | functionality to deal with nodes. | ++----------------------------+------------------------------------------------+ +| :cpp:any:`hdf5::dataspace` | dataspaces and related utilities | ++----------------------------+------------------------------------------------+ +| :cpp:any:`hdf5::error` | error management and exceptions | ++----------------------------+------------------------------------------------+ +| :cpp:any:`hdf5::file` | everything releated to files | ++----------------------------+------------------------------------------------+ + +Nodes +----- + +All classes representing nodes are located in the :cpp:any:`hdf5::node` +namespace. The most prominent ones are + +.. figure:: ../images/hdf5_node_types.svg + :align: center + :width: 75% + +As you can see all node classes have a common parent class +:cpp:class:`hdf5::node::Node`. + +