include/highfive/H5Reference.hpp

0001 /*
0002  *  Copyright (c), 2020, EPFL - Blue Brain Project
0003  *
0004  *  Distributed under the Boost Software License, Version 1.0.
0005  *    (See accompanying file LICENSE_1_0.txt or copy at
0006  *          http://www.boost.org/LICENSE_1_0.txt)
0007  *
0008  */
0009
0010 #pragma once
0011
0012 #include <string>
0013 #include <vector>
0014
0015 #include <H5Ipublic.h>
0016 #include <H5Rpublic.h>
0017
0018 #include "bits/H5_definitions.hpp"
0019
0020 namespace HighFive {
0021
0022 namespace details {
0023 template <typename T>
0024 struct inspector;
0025 }
0026 ///
0027 /// \brief An HDF5 (object) reference type
0028 ///
0029 /// HDF5 object references allow pointing to groups, datasets (and compound types). They
0030 /// differ from links in their ability to be stored and retrieved as data from the HDF5
0031 /// file in datasets themselves.
0032 ///
0033 class Reference {
0034   public:
0035     /// \brief Create an empty Reference to be initialized later
0036     Reference() = default;
0037
0038     /// \brief Create a Reference to an object residing at a given location
0039     ///
0040     /// \param location A File or Group where the object being referenced to resides
0041     /// \param object A Dataset or Group to be referenced
0042     Reference(const Object& location, const Object& object);
0043
0044     /// \brief Retrieve the Object being referenced by the Reference
0045     ///
0046     /// \tparam T the appropriate HighFive Container (either DataSet or Group)
0047     /// \param location the location where the referenced object is to be found (a File)
0048     /// \return the dereferenced Object (either a Group or DataSet)
0049     template <typename T>
0050     T dereference(const Object& location) const;
0051
0052     /// \brief Get only the type of the referenced Object
0053     ///
0054     /// \param location the location where the referenced object is to be found (a File)
0055     /// \return the ObjectType of the referenced object
0056     ObjectType getType(const Object& location) const;
0057
0058   protected:
0059     /// \brief Create a Reference from a low-level HDF5 object reference
0060     inline explicit Reference(const hobj_ref_t h5_ref)
0061         : href(h5_ref){};
0062
0063     /// \brief Create the low-level reference and store it at refptr
0064     ///
0065     /// \param refptr Pointer to a memory location where the created HDF5 reference will
0066     /// be stored
0067     void create_ref(hobj_ref_t* refptr) const;
0068
0069   private:
0070     Object get_ref(const Object& location) const;
0071
0072     hobj_ref_t href{};
0073     std::string obj_name{};
0074     hid_t parent_id{};
0075
0076     friend struct details::inspector<Reference>;
0077 };
0078
0079 }  // namespace HighFive
0080
0081 #include "bits/H5Reference_misc.hpp"