Merge branch 'armem/dev' of https://gitlab.com/ArmarX/RobotAPI into aron/dev

source/RobotAPI/libraries/armem/core/MemoryID.cpp

 #include "MemoryID.h"
 
-#include <SimoxUtility/algorithm/string.h>
-
 #include "error/ArMemError.h"
 
+#include <SimoxUtility/algorithm/advanced.h>
+#include <SimoxUtility/algorithm/string/string_tools.h>
+
+#include <boost/algorithm/string.hpp>
+
+#include <forward_list>
+
 
 namespace armarx::armem
 {
 
+    const std::string MemoryID::delimiter = "/";
+
+
     MemoryID::MemoryID()
     {
     }
 
     MemoryID::MemoryID(const std::string& string)
     {
-        std::vector<std::string> items = simox::alg::split(string, "/", false, false);
+        std::forward_list<std::string> items;
+        boost::split(items, string, boost::is_any_of(delimiter));
+
+        // Handle escaped /'s
+        for (auto it = items.begin(); it != items.end(); ++it)
+        {
+            while (it->size() > 0 && it->back() == '\\')
+            {
+                // The / causing the split was escaped. Merge the items together.
+                auto next = simox::alg::advanced(it, 1);
+                if (next != items.end())
+                {
+                    // "it\" + "next" => "it/next"
+                    *it = it->substr(0, it->size() - 1) + delimiter + *next;
+                    items.erase_after(it); // Invalidates `next`, but not `it`.
+                }
+            }
+        }
 
         auto it = items.begin();
         if (it == items.end())
@@ -55,19 +80,19 @@ namespace armarx::armem
     }
 
 
-    std::string MemoryID::str() const
+    std::string MemoryID::str(bool escapeDelimiters) const
     {
-        return str("/");
+        return str(delimiter, escapeDelimiters);
     }
 
-    std::string MemoryID::str(const std::string& delimeter) const
+    std::string MemoryID::str(const std::string& delimiter, bool escapeDelimiter) const
     {
-        std::vector<std::string> items = getAllItems();
+        std::vector<std::string> items = getAllItems(escapeDelimiter);
         while (items.size() > 0 && items.back().empty())
         {
             items.pop_back();
         }
-        return simox::alg::join(items, delimeter, false, false);
+        return simox::alg::join(items, delimiter, false, false);
     }
 
     std::string MemoryID::getLeafItem() const
@@ -86,52 +111,55 @@ namespace armarx::armem
     bool MemoryID::hasGap() const
     {
         bool emptyFound = false;
-        for (const std::string& name : getAllItems())
+        for (const std::string& item : getAllItems())
         {
-            if (name.empty())
+            if (item.empty())
             {
                 emptyFound = true;
             }
-            else
+            else if (emptyFound)
             {
-                if (emptyFound)
-                {
-                    return true;
-                }
+                // Found a non-empty item after an empty item.
+                return true;
             }
         }
         return false;
     }
 
+    bool MemoryID::isWellDefined() const
+    {
+        return !hasGap();
+    }
+
 
     MemoryID MemoryID::fromString(const std::string& string)
     {
         return MemoryID(string);
     }
 
-    std::vector<std::string> MemoryID::getItems() const
+    std::vector<std::string> MemoryID::getItems(bool escapeDelimiters) const
     {
         std::vector<std::string> items;
 
-        items.push_back(memoryName);
+        items.push_back(escape(memoryName, escapeDelimiters));
 
         if (!hasCoreSegmentName())
         {
             return items;
         }
-        items.push_back(coreSegmentName);
+        items.push_back(escape(coreSegmentName, escapeDelimiters));
 
         if (!hasProviderSegmentName())
         {
             return items;
         }
-        items.push_back(providerSegmentName);
+        items.push_back(escape(providerSegmentName, escapeDelimiters));
 
         if (!hasEntityName())
         {
             return items;
         }
-        items.push_back(entityName);
+        items.push_back(escape(entityName, escapeDelimiters));
 
         if (!hasTimestamp())
         {
@@ -148,11 +176,12 @@ namespace armarx::armem
         return items;
     }
 
-    std::vector<std::string> MemoryID::getAllItems() const
+    std::vector<std::string> MemoryID::getAllItems(bool escapeDelimiters) const
     {
         return
         {
-            memoryName, coreSegmentName, providerSegmentName, entityName,
+            escape(memoryName, escapeDelimiters), escape(coreSegmentName, escapeDelimiters),
+            escape(providerSegmentName, escapeDelimiters), escape(entityName, escapeDelimiters),
             timestampStr(), instanceIndexStr()
         };
     }
@@ -276,6 +305,7 @@ namespace armarx::armem
         return id;
     }
 
+
     std::string MemoryID::timestampStr() const
     {
         return hasTimestamp() ? std::to_string(timestamp.toMicroSeconds()) : "";
@@ -306,8 +336,46 @@ namespace armarx::armem
                and instanceIndex == other.instanceIndex;
     }
 
+    bool MemoryID::operator<(const MemoryID& rhs) const
+    {
+        int c = memoryName.compare(rhs.memoryName);
+        if (c != 0)
+        {
+            return c < 0;
+        }
+        // Equal memory name
+        c = coreSegmentName.compare(rhs.coreSegmentName);
+        if (c != 0)
+        {
+            return c < 0;
+        }
+        // Equal core segment ID
+        c = providerSegmentName.compare(rhs.providerSegmentName);
+        if (c != 0)
+        {
+            return c < 0;
+        }
+        // Equal provider segment ID
+        c = entityName.compare(rhs.entityName);
+        if (c != 0)
+        {
+            return c < 0;
+        }
+        // Equal entity ID
+        if (timestamp != rhs.timestamp)
+        {
+            return timestamp < rhs.timestamp;
+        }
+        // Equal entity snapshot ID
+        return instanceIndex < rhs.instanceIndex;
+    }
+
     long long MemoryID::parseInteger(const std::string& string, const std::string& semanticName)
     {
+        if (string.empty())
+        {
+            return -1;
+        }
         try
         {
             return std::stoll(string);
@@ -322,15 +390,44 @@ namespace armarx::armem
         }
     }
 
+    std::string MemoryID::escapeDelimiter(const std::string& name)
+    {
+        return simox::alg::replace_all(name, delimiter, "\\" + delimiter);
+    }
+
+    std::string MemoryID::escape(const std::string& name, bool escapeDelimiters)
+    {
+        if (escapeDelimiters)
+        {
+            return escapeDelimiter(name);
+        }
+        else
+        {
+            return name;
+        }
+    }
+
     std::ostream& operator<<(std::ostream& os, const MemoryID id)
     {
         return os << "'" << id.str() << "'";
     }
 
 
-    bool
-    contains(const MemoryID& general, const MemoryID& specific)
+    bool contains(const MemoryID& general, const MemoryID& specific)
     {
+        if (!general.isWellDefined())
+        {
+            std::stringstream ss;
+            ss << "ID `general` is not well-defined, which is required for `" << __FUNCTION__ << "()`.";
+            throw error::InvalidMemoryID(general, ss.str());
+        }
+        if (!specific.isWellDefined())
+        {
+            std::stringstream ss;
+            ss << "ID `specific` is not well-defined, which is required for `" << __FUNCTION__ << "()`.";
+            throw error::InvalidMemoryID(specific, ss.str());
+        }
+
         if (general.memoryName.empty())
         {
             return true;

source/RobotAPI/libraries/armem/core/MemoryID.h

@@ -12,11 +12,37 @@ namespace armarx::armem
     /**
      * @brief A memory ID.
      *
-     * Structure:
-     * `MemoryName/CoreSegmentName/ProviderSegmentName/EntityName/Timestamp/InstanceIndex`
+     * A memory ID is an index into the hierarchical memory structure.
+     * It specifies the keys for the different levels, starting from the
+     * memory name and ending at the instance index.
      *
-     * Example:
-     * `VisionMemory/RGBImages/PrimesenseRGB/image/1245321323/0`
+     * A memory ID need not be complete, e.g. it may specify only the memory
+     * and core segment names (thus representing a core segment ID).
+     * A memory ID that fully identifies a level starting from the memory is
+     * called well-defined.
+     * @see `isWellDefined()`
+     *
+     * Memory IDs can be encoded in strings using a delimiter:
+     * - Structure: "MemoryName/CoreSegmentName/ProviderSegmentName/EntityName/Timestamp/InstanceIndex"
+     * - Example:   "Vision/RGBImages/Primesense/image/1245321323/0"
+     * @see `str()`
+     *
+     * If an ID does not specify the lower levels, these parts can be omitted.
+     * Thus, an entity ID could look like:
+     * - Structure: "MemoryName/CoreSegmentName/ProviderSegmentName/EntityName"
+     * - Example:   "Vision/RGBImages/Primesense/image"
+     *
+     * If a name contains a "/", it will be escaped:
+     * - Example:   "Vision/RGBImages/Primesense/my\/entity\/with\/slashes"
+     *
+     * Memory IDs may be not well-defined. This can occur e.g. when preparing
+     * an entity instance ID which is still pending the timestamp.
+     * It could look like (note the missing timestamp):
+     * - Example:   "Vision/RGBImages/Primesense/image//0"
+     *
+     * These IDs are still valid and can be handled (encoded as string etc.).
+     * However, some operations may not be well-defined for non-well-defined IDs
+     * (such as `contains()`).
      */
     class MemoryID
     {
@@ -30,26 +56,37 @@ namespace armarx::armem
         int instanceIndex = -1;
 
 
-
     public:
 
+        /// Construct a default (empty) memory ID.
         MemoryID();
+        /// (Re-)Construct a memory ID from a string representation as returned by `str()`.
         explicit MemoryID(const std::string& string);
 
 
-        std::string str() const;
-        std::string str(const std::string& delimeter) const;
-        static MemoryID fromString(const std::string& string);
-
-        std::string timestampStr() const;
-        std::string instanceIndexStr() const;
-
-
-        /// Get all levels as string.
-        std::vector<std::string> getAllItems() const;
-        /// Get the levels from root to first not defined level (excluding).
-        std::vector<std::string> getItems() const;
-
+        /**
+         * @brief Indicate whether this ID is well-defined.
+         *
+         * A well-defined ID has no specified level after a non-specified level (i.e., no gaps).
+         *
+         * Well-defined examples:
+         * - "" (empty, but well-defined)
+         * - "Memory" (a memory ID)
+         * - "Memory/Core" (a core segment ID)
+         * - "Memory/Core/Provider" (a provider segment ID)
+         *
+         * Non-well-defined examples:
+         * - "Memory//Provider" (no core segment name)
+         * - "/Core" (no memory name)
+         * - "Mem/Core/Prov/entity//0" (no timestamp)
+         * - "///entity//0" (no memory, core segment and provider segment names)
+         *
+         * @return True if `*this` is a well-defined memory ID.
+         */
+        bool isWellDefined() const;
+
+
+        // Checks whether a specific level is specified.
 
         bool hasMemoryName() const
         {
@@ -113,15 +150,49 @@ namespace armarx::armem
         MemoryID withInstanceIndex(int index) const;
 
 
+        // String conversion
+
+        /**
+         * @brief Get a string representation of this memory ID.
+         *
+         * Items are separated by a delimiter. If `escapeDelimiter` is true,
+         * delimiters occuring inside names are escaped with backward slashes.
+         * This allows to reconstruct the memory ID from the result of `str()`
+         * in these cases.
+         *
+         * @param escapeDelimiter If true, escape delimiters inside names
+         * @return A string representation of this MemoryID.
+         */
+        std::string str(bool escapeDelimiters = true) const;
+
+        /// Get the timestamp as string.
+        std::string timestampStr() const;
+        /// Get the instance index as string.
+        std::string instanceIndexStr() const;
+
+        /// Alias for constructor from string.
+        static MemoryID fromString(const std::string& string);
+        /// Reconstruct a timestamp from a string as returned by `timestampStr()`.
+        static Time timestampFromStr(const std::string& timestamp);
+        /// Reconstruct an instance index from a string as returned by `instanceIndexStr()`.
+        static int instanceIndexFromStr(const std::string& index);
+
+
+        /// Get all levels as strings.
+        std::vector<std::string> getAllItems(bool escapeDelimiters = false) const;
+        /// Get the levels from root to first not defined level (excluding).
+        std::vector<std::string> getItems(bool escapeDelimiters = false) const;
+
+
+        // Other utility.
+
         /// Indicate whether this ID has a gap such as in 'Memory//MyProvider' (no core segment name).
         bool hasGap() const;
         /// Get the lowest defined level (or empty string if there is none).
         std::string getLeafItem() const;
 
 
-        static Time timestampFromStr(const std::string& timestamp);
-        static int instanceIndexFromStr(const std::string& index);
-
+        // Operators
 
         bool operator ==(const MemoryID& other) const;
         inline bool operator !=(const MemoryID& other) const
@@ -129,18 +200,59 @@ namespace armarx::armem
             return !(*this == other);
         }
 
+        bool operator< (const MemoryID& rhs) const;
+        inline bool operator> (const MemoryID& rhs) const
+        {
+            return rhs < (*this);
+        }
+        inline bool operator<=(const MemoryID& rhs) const
+        {
+            return !operator> (rhs);
+        }
+        inline bool operator>=(const MemoryID& rhs) const
+        {
+            return !operator< (rhs);
+        }
+
         friend std::ostream& operator<<(std::ostream& os, const MemoryID id);
 
 
     private:
 
         static long long parseInteger(const std::string& string, const std::string& semanticName);
+        static std::string escapeDelimiter(const std::string& name);
+        static std::string escape(const std::string& name, bool escapeDelimiters);
+
+        static const std::string delimiter;
+
+
+        // Do not allow specifying the delimiter from outside.
+        std::string str(const std::string& delimiter, bool escapeDelimiter) const;
 
     };
 
 
-    bool
-    contains(const MemoryID& general, const MemoryID& specific);
+    /**
+     * @brief Indicates whether `general` is "less specific" than, or equal to, `specific`,
+     * i.e. `general` "contains" `specific`.
+     *
+     * A memory ID A is said to be less specific than B, if B the same values as A
+     * for all levels specified in A, but potentially also specifies the lower levels.
+     *
+     * Examples:
+     * - "" contains ""
+     * - "m" contains "m" and "m/c", but not "n" and "n/c"
+     * - "m/c" contains "m/c" and "m/c/p", but not "m/d" and "m/c/q"
+     *
+     * If a memory ID has a gap (`@see MemoryID::hasGap()`), such as "m//p",
+     * the levels after the gap are ignored.
+     * - "m//p" contains "m", "m/c" and "m/c/p".
+     *
+     * @param general The less specific memory ID
+     * @param specific The more specific memory ID
+     * @return True if `general` is less specific than `specific`.
+     */
+    bool contains(const MemoryID& general, const MemoryID& specific);
 
 }
 

source/RobotAPI/libraries/armem/test/ArMemMemoryIDTest.cpp

@@ -26,6 +26,7 @@
 
 #include <RobotAPI/Test.h>
 #include "../core/MemoryID.h"
+#include "../core/error.h"
 
 #include <iostream>
 
@@ -33,22 +34,106 @@
 namespace armem = armarx::armem;
 
 
-BOOST_AUTO_TEST_CASE(test_memoryid_contains)
+BOOST_AUTO_TEST_CASE(test_MemoryID_contains)
 {
     armem::MemoryID general, specific;
 
-    BOOST_CHECK(armem::contains(general, specific));
+    // Both empty.
+    BOOST_TEST_CONTEXT(VAROUT(general) << " | " << VAROUT(specific))
+    {
+        BOOST_CHECK(armem::contains(general, specific));
+    }
 
+    // Diverging.
     general.memoryName = "a";
     specific.memoryName = "b";
 
-    BOOST_CHECK(not armem::contains(general, specific));
+    BOOST_TEST_CONTEXT(VAROUT(general) << " | " << VAROUT(specific))
+    {
+        BOOST_CHECK(not armem::contains(general, specific));
+        BOOST_CHECK(not armem::contains(specific, general));
+    }
 
+    // Identical.
     specific.memoryName = "a";
 
-    BOOST_CHECK(armem::contains(general, specific));
+    BOOST_TEST_CONTEXT(VAROUT(general) << " | " << VAROUT(specific))
+    {
+        BOOST_CHECK(armem::contains(general, specific));
+        BOOST_CHECK(armem::contains(specific, general));
+    }
 
-    specific.providerSegmentName = "aa";
+    // general contains specific
+    specific.coreSegmentName = "c";
+
+    BOOST_TEST_CONTEXT(VAROUT(general) << " | " << VAROUT(specific))
+    {
+        BOOST_CHECK(armem::contains(general, specific));
+        BOOST_CHECK(not armem::contains(specific, general));
+    }
+
+    // general contains specific
+    specific.providerSegmentName = "d";
+
+    BOOST_TEST_CONTEXT(VAROUT(general) << " | " << VAROUT(specific))
+    {
+        BOOST_CHECK(armem::contains(general, specific));
+        BOOST_CHECK(not armem::contains(specific, general));
+    }
+
+    // Not well-defined ID - throw an exception.
+    specific.coreSegmentName.clear();
+
+    BOOST_TEST_CONTEXT(VAROUT(general) << " | " << VAROUT(specific))
+    {
+        BOOST_CHECK_THROW(armem::contains(general, specific), armem::error::InvalidMemoryID);
+        BOOST_CHECK_THROW(armem::contains(specific, general), armem::error::InvalidMemoryID);
+    }
+}
+
+
+
+BOOST_AUTO_TEST_CASE(test_MemoryID_from_to_string)
+{
+    armem::MemoryID idIn {"Memory/Core/Prov/entity/2810381/2"};
+
+    BOOST_CHECK_EQUAL(idIn.memoryName, "Memory");
+    BOOST_CHECK_EQUAL(idIn.coreSegmentName, "Core");
+    BOOST_CHECK_EQUAL(idIn.providerSegmentName, "Prov");
+    BOOST_CHECK_EQUAL(idIn.entityName, "entity");
+    BOOST_CHECK_EQUAL(idIn.timestamp, IceUtil::Time::microSeconds(2810381));
+    BOOST_CHECK_EQUAL(idIn.instanceIndex, 2);
+
+
+    BOOST_TEST_CONTEXT(VAROUT(idIn.str()))
+    {
+        armem::MemoryID idOut(idIn.str());
+        BOOST_CHECK_EQUAL(idOut, idIn);
+    }
+
+    idIn.entityName = "KIT/Amicelli/0";  // Like an ObjectID
+    BOOST_CHECK_EQUAL(idIn.entityName, "KIT/Amicelli/0");
+
+    BOOST_TEST_CONTEXT(VAROUT(idIn.str()))
+    {
+        armem::MemoryID idOut(idIn.str());
+        BOOST_CHECK_EQUAL(idOut.entityName, "KIT/Amicelli/0");
+        BOOST_CHECK_EQUAL(idOut, idIn);
+    }
+
+    idIn = armem::MemoryID {"InThe\\/Mid/AtTheEnd\\//\\/AtTheStart/YCB\\/sugar\\/-1//2"};
+    BOOST_CHECK_EQUAL(idIn.memoryName, "InThe/Mid");
+    BOOST_CHECK_EQUAL(idIn.coreSegmentName, "AtTheEnd/");
+    BOOST_CHECK_EQUAL(idIn.providerSegmentName, "/AtTheStart");
+    BOOST_CHECK_EQUAL(idIn.entityName, "YCB/sugar/-1");
+    BOOST_CHECK_EQUAL(idIn.timestamp, IceUtil::Time::microSeconds(-1));
+    BOOST_CHECK_EQUAL(idIn.instanceIndex, 2);
+
+    BOOST_TEST_CONTEXT(VAROUT(idIn.str()))
+    {
+        armem::MemoryID idOut(idIn.str());
+        BOOST_CHECK_EQUAL(idOut, idIn);
+    }
 
-    BOOST_CHECK(armem::contains(general, specific));
 }
+