diff --git a/doc/source/users_guide/CMakeLists.txt b/doc/source/users_guide/CMakeLists.txt index ce1d1582e8..4450c63037 100644 --- a/doc/source/users_guide/CMakeLists.txt +++ b/doc/source/users_guide/CMakeLists.txt @@ -1,6 +1,8 @@ set(SOURCES index.rst using.rst - files.rst) + files.rst + groups.rst + overview.rst) add_sphinx_source(${SOURCES}) copy_to_current_build(${SOURCES}) diff --git a/doc/source/users_guide/files.rst b/doc/source/users_guide/files.rst index 2dfe63b909..2ea1056bd9 100644 --- a/doc/source/users_guide/files.rst +++ b/doc/source/users_guide/files.rst @@ -190,6 +190,4 @@ using the :cpp:func:`File::root()` method of a file instance and :cpp:class:`hdf5::node::Group` is worth the additional effort. -sdfsdfdsf werwer wesdf - diff --git a/doc/source/users_guide/groups.rst b/doc/source/users_guide/groups.rst index be3a745963..ccdfa8112e 100644 --- a/doc/source/users_guide/groups.rst +++ b/doc/source/users_guide/groups.rst @@ -2,59 +2,31 @@ Working with groups =================== +Groups are the basic containers within an HDF5 file. The entry point to the +HDF5 group hierarchy is the root group of a file. It can be accessed from the +:cpp:func:`root` method of a :cpp:class:`hdf5::file::File` instance. + .. code-block:: cpp - h5::group_t g = root_group.create("new_group",....); + using namespace hdf5; + + file::File f = ....; + node::Group root_group = f.root(); -Need to find a good way how to handle group creation property lists. +Groups act like STL container in a very general sense. With an HDF5 group you +can iterate either over the links directly attached to it or over the +objects referenced by those links. You can access links via the publik +:cpp:member:`hdf5::node::Group::links` member or the objects via the +:cpp:member:`hdf5::node::Group::nodes` member. They are instances of +:cpp:class:`hdf5::node::LinkView` and :cpp:class:`hdf5::node::LinkView` +respectively. -Groups should provide a STL compliant iterator interface. -.. code-block:: cpp - - class group_iterator_t - { - ..... - }; - - class recursive_group_iterator_t - { - ..... - }; - - class group_t - { - public: - - // - // access a direct child by its index - // - object_t operator()[size_t index] const; - // - // returns the number of direct children below the group - // - size_t size() const; - - // - // provides access to a child by its name - // - // As the name can be an arbitrary path with this method - // an arbitrary child can be accessed from this group. - // - object_t operator()[const std::string &name] const; - - // - // provides access to an arbitrary object - // - object_t operator()[const h5::path_t &path] const; - - group_iterator_t begin() const; - group_iterator_t end() const; - - recursive_group_iterator_t rbegin() const; - recursive_group_iterator_t rend() const; - }; +Iterating over nodes +==================== +Iterating over links +==================== Accessing a groups children =========================== diff --git a/doc/source/users_guide/index.rst b/doc/source/users_guide/index.rst index 2b9f2c8641..9edb62f27b 100644 --- a/doc/source/users_guide/index.rst +++ b/doc/source/users_guide/index.rst @@ -10,4 +10,7 @@ Still need to add a table of contents here. :maxdepth: 1 using - files \ No newline at end of file + overview + files + groups + diff --git a/doc/source/users_guide/overview.rst b/doc/source/users_guide/overview.rst new file mode 100644 index 0000000000..d75244fdc8 --- /dev/null +++ b/doc/source/users_guide/overview.rst @@ -0,0 +1,23 @@ +=============== +Design overview +=============== + +In this chapter we will have a brief view on the design of *h5cpp*. We will +not dive into the details here but hopfully provide enough insight into the +concepts behind *h5cpp*. + +.. attention:: + + If you are new to *h5cpp* please read this chapter carefully as it is the + basement for everthing else in this manual. If you do not understand the + terminology introduced by this chapter it is most probably difficult + to understand the rest of the manual. + + +A high level view on HDF5 +========================= + + + +Nodes and links +===============