Add a Property for LinkCreationOrder (#683)

Author: Nicolas Cornu

include/highfive/H5PropertyList.hpp

@@ -563,6 +563,42 @@ class MpioNoCollectiveCause {
 };
 #endif
 
+struct CreationOrder {
+    enum _CreationOrder {
+        Tracked = H5P_CRT_ORDER_TRACKED,
+        Indexed = H5P_CRT_ORDER_INDEXED,
+    };
+};
+
+///
+/// \brief Track and index creation order time
+///
+/// Let user retrieve objects by creation order time instead of name.
+///
+class LinkCreationOrder {
+  public:
+    ///
+    /// \brief Create the property
+    /// \param flags Should be a composition of HighFive::CreationOrder.
+    ///
+    explicit LinkCreationOrder(unsigned flags)
+        : _flags(flags) {}
+
+    explicit LinkCreationOrder(const FileCreateProps& fcpl);
+    explicit LinkCreationOrder(const GroupCreateProps& gcpl);
+
+    unsigned getFlags() const;
+
+  protected:
+    void fromPropertyList(hid_t hid);
+
+  private:
+    friend FileCreateProps;
+    friend GroupCreateProps;
+    void apply(hid_t hid) const;
+    unsigned _flags;
+};
+
 }  // namespace HighFive
 
 #include "bits/H5PropertyList_misc.hpp"

include/highfive/bits/H5Node_traits.hpp

@@ -16,6 +16,11 @@
 
 namespace HighFive {
 
+enum class IndexType : std::underlying_type<H5_index_t>::type {
+    NAME = H5_INDEX_NAME,
+    CRT_ORDER = H5_INDEX_CRT_ORDER,
+};
+
 ///
 /// \brief NodeTraits: Base class for Group and File
 ///
@@ -146,8 +151,11 @@ class NodeTraits {
 
     ///
     /// \brief list all leaf objects name of the node / group
+    /// \param idx_type tell if the list should be ordered by Name or CreationOrderTime.
+    /// CreationOrderTime can be use only if the file/group has been created with
+    /// the HighFive::LinkCreationTime property.
     /// \return number of leaf objects
-    std::vector<std::string> listObjectNames() const;
+    std::vector<std::string> listObjectNames(IndexType idx_type = IndexType::NAME) const;
 
     ///
     /// \brief check a dataset or group exists in the current node / group

include/highfive/bits/H5Node_traits_misc.hpp

@@ -219,15 +219,15 @@ inline bool NodeTraits<Derivate>::rename(const std::string& src_path,
 }
 
 template <typename Derivate>
-inline std::vector<std::string> NodeTraits<Derivate>::listObjectNames() const {
+inline std::vector<std::string> NodeTraits<Derivate>::listObjectNames(IndexType idx_type) const {
     std::vector<std::string> names;
     details::HighFiveIterateData iterateData(names);
 
     size_t num_objs = getNumberObjects();
     names.reserve(num_objs);
 
     if (H5Literate(static_cast<const Derivate*>(this)->getId(),
-                   H5_INDEX_NAME,
+                   static_cast<H5_index_t>(idx_type),
                    H5_ITER_INC,
                    NULL,
                    &details::internal_high_five_iterate<H5L_info_t>,

include/highfive/bits/H5PropertyList_misc.hpp

@@ -519,4 +519,28 @@ inline std::pair<uint32_t, uint32_t> MpioNoCollectiveCause::getCause() const {
 }
 #endif
 
+inline LinkCreationOrder::LinkCreationOrder(const FileCreateProps& fcpl) {
+    fromPropertyList(fcpl.getId());
+}
+
+inline LinkCreationOrder::LinkCreationOrder(const GroupCreateProps& gcpl) {
+    fromPropertyList(gcpl.getId());
+}
+
+inline unsigned LinkCreationOrder::getFlags() const {
+    return _flags;
+}
+
+inline void LinkCreationOrder::LinkCreationOrder::apply(const hid_t hid) const {
+    if (H5Pset_link_creation_order(hid, _flags) < 0) {
+        HDF5ErrMapper::ToException<PropertyException>("Error setting LinkCreationOrder.");
+    }
+}
+
+inline void LinkCreationOrder::fromPropertyList(hid_t hid) {
+    if (H5Pget_link_creation_order(hid, &_flags) < 0) {
+        HDF5ErrMapper::ToException<PropertyException>(
+            "Error getting property for link creation order");
+    }
+}
 }  // namespace HighFive

tests/unit/tests_high_five_base.cpp

@@ -1867,6 +1867,63 @@ TEST_CASE("HighFivePropertyObjects") {
     CHECK(plist_g2.isValid());
 }
 
+TEST_CASE("HighFiveLinkCreationOrderProperty") {
+    {  // For file
+        const std::string FILE_NAME("h5_keep_creation_order_file.h5");
+        FileCreateProps keepCreationOrder{};
+        keepCreationOrder.add(LinkCreationOrder(CreationOrder::Tracked | CreationOrder::Indexed));
+
+        File file(FILE_NAME, File::ReadWrite | File::Create | File::Truncate, keepCreationOrder);
+        file.createGroup("1");
+        file.createGroup("2");
+        file.createGroup("10");
+
+        CHECK(file.listObjectNames(IndexType::CRT_ORDER) ==
+              std::vector<std::string>{"1", "2", "10"});
+        CHECK(file.listObjectNames(IndexType::NAME) == std::vector<std::string>{"1", "10", "2"});
+
+        auto fcpl = file.getCreatePropertyList();
+        LinkCreationOrder linkCreationOrder(fcpl);
+        CHECK((linkCreationOrder.getFlags() & CreationOrder::Tracked) != 0);
+        CHECK((linkCreationOrder.getFlags() & CreationOrder::Indexed) != 0);
+    }
+    {  // For groups
+        const std::string FILE_NAME("h5_keep_creation_order_group.h5");
+        GroupCreateProps keepCreationOrder{};
+        keepCreationOrder.add(LinkCreationOrder(CreationOrder::Tracked | CreationOrder::Indexed));
+
+        File file(FILE_NAME, File::ReadWrite | File::Create | File::Truncate);
+        auto group = file.createGroup("group_crt", keepCreationOrder);
+        group.createGroup("1");
+        group.createGroup("2");
+        group.createGroup("10");
+
+        CHECK(group.listObjectNames(IndexType::CRT_ORDER) ==
+              std::vector<std::string>{"1", "2", "10"});
+        CHECK(group.listObjectNames(IndexType::NAME) == std::vector<std::string>{"1", "10", "2"});
+
+        auto group2 = file.createGroup("group_name");
+        group2.createGroup("1");
+        group2.createGroup("2");
+        group2.createGroup("10");
+
+        CHECK(group2.listObjectNames() == std::vector<std::string>{"1", "10", "2"});
+
+        {
+            auto gcpl = group.getCreatePropertyList();
+            LinkCreationOrder linkCreationOrder(gcpl);
+            CHECK((linkCreationOrder.getFlags() & CreationOrder::Tracked) != 0);
+            CHECK((linkCreationOrder.getFlags() & CreationOrder::Indexed) != 0);
+        }
+        {
+            auto gcpl = group2.getCreatePropertyList();
+            LinkCreationOrder linkCreationOrder(gcpl);
+            CHECK((linkCreationOrder.getFlags() & CreationOrder::Tracked) == 0);
+            CHECK((linkCreationOrder.getFlags() & CreationOrder::Indexed) == 0);
+        }
+    }
+}
+
 struct CSL1 {
     int m1;
     int m2;