uuid_t: Add uuid_t::equivalent(..) method fo relaxed comparison on different uuid_t; Add API doc to uuid_t::operator==(..) ..

The operator uuid_t::operator==(..) and uuid_t::operator!=(..)
perform strict comparison and will fail on different uuid_t types (TypeSize).

Adding convenient relaxed uuid_t::equivalent(..) method,
allowing conversion to uuid128_t in case of different types
before comparison.

Tested with test_uuid.cpp

3 files changed, 106 insertions, 12 deletions

diff --git a/include/jau/uuid.hpp b/include/jau/uuid.hpp
index 5dd4d52..25be8ef 100644
--- a/include/jau/uuid.hpp
+++ b/include/jau/uuid.hpp
@@ -80,15 +80,43 @@ public:
 
     std::unique_ptr<uuid_t> clone() const noexcept;
 
-    virtual bool operator==(uuid_t const &o) const noexcept {
-        if( this == &o ) {
-            return true;
-        }
-        return type == o.type;
-    }
+    /**
+     * Strict equality operator.
+     *
+     * Only returns true if type and value are equal.
+     *
+     * @param o other comparison argument
+     * @return true if equal, otherwise false.
+     */
+    virtual bool operator==(uuid_t const &o) const noexcept  = 0;
+
+    /**
+     * Strict not-equal operator.
+     *
+     * Returns true if type and/or value are not equal.
+     *
+     * @param o other comparison argument
+     * @return true if equal, otherwise false.
+     */
     bool operator!=(uuid_t const &o) const noexcept
     { return !(*this == o); }
 
+    /**
+     * Relaxed equality operator.
+     *
+     * Returns true if both uuid values are equivalent.
+     *
+     * If their uuid_t type differs, i.e. their TypeSize,
+     * both values will be transformed to uuid128_t before comparison.
+     *
+     * Potential uuid128_t conversion is performed using toUUDI128(),
+     * placing the sub-uuid at index 12 on BT_BASE_UUID (default).
+     *
+     * @param o other comparison argument
+     * @return true if equal, otherwise false.
+     */
+    bool equivalent(uuid_t const &o) const noexcept;
+
     TypeSize getTypeSize() const noexcept { return type; }
     jau::nsize_t getTypeSizeInt() const noexcept { return uuid_t::number(type); }
     std::string getTypeSizeString() const noexcept { return getTypeSizeString(type); }
@@ -97,8 +125,17 @@ public:
 
     /** returns the pointer to the uuid data of size getTypeSize() */
     virtual const uint8_t * data() const noexcept = 0;
+
+    /**
+     * Returns the string representation in BE network order, i.e. `00000000-0000-1000-8000-00805F9B34FB`.
+     */
     virtual std::string toString() const noexcept = 0;
+
+    /**
+     * Returns the uuid128_t string representation in BE network order, i.e. `00000000-0000-1000-8000-00805F9B34FB`.
+     */
     virtual std::string toUUID128String(uuid128_t const & base_uuid=BT_BASE_UUID, jau::nsize_t const le_octet_index=12) const noexcept = 0;
+
     virtual jau::nsize_t put(uint8_t * const buffer, jau::nsize_t const byte_offset, bool const littleEndian) const noexcept = 0;
 };
 
@@ -123,6 +160,14 @@ public:
     uuid16_t& operator=(const uuid16_t &o) noexcept = default;
     uuid16_t& operator=(uuid16_t &&o) noexcept = default;
 
+    /**
+     * Strict equality operator.
+     *
+     * Only returns true if type and value are equal.
+     *
+     * @param o other comparison argument
+     * @return true if equal, otherwise false.
+     */
     bool operator==(uuid_t const &o) const noexcept override {
         if( this == &o ) {
             return true;
@@ -157,6 +202,14 @@ public:
     uuid32_t& operator=(const uuid32_t &o) noexcept = default;
     uuid32_t& operator=(uuid32_t &&o) noexcept = default;
 
+    /**
+     * Strict equality operator.
+     *
+     * Only returns true if type and value are equal.
+     *
+     * @param o other comparison argument
+     * @return true if equal, otherwise false.
+     */
     bool operator==(uuid_t const &o) const noexcept override {
         if( this == &o ) {
             return true;
@@ -197,6 +250,14 @@ public:
     uuid128_t& operator=(const uuid128_t &o) noexcept = default;
     uuid128_t& operator=(uuid128_t &&o) noexcept = default;
 
+    /**
+     * Strict equality operator.
+     *
+     * Only returns true if type and value are equal.
+     *
+     * @param o other comparison argument
+     * @return true if equal, otherwise false.
+     */
     bool operator==(uuid_t const &o) const noexcept override {
         if( this == &o ) {
             return true;
diff --git a/src/uuid.cpp b/src/uuid.cpp
index 879ba57..8bd954b 100644
--- a/src/uuid.cpp
+++ b/src/uuid.cpp
@@ -91,6 +91,16 @@ std::unique_ptr<uuid_t> uuid_t::clone() const noexcept {
     abort(); // never reached
 }
 
+bool uuid_t::equivalent(uuid_t const &o) const noexcept {
+    if( this == &o ) {
+        return true;
+    }
+    if( getTypeSize() == o.getTypeSize() ) {
+        return *this == o;
+    }
+    return toUUID128() == o.toUUID128();
+}
+
 uuid128_t uuid_t::toUUID128(uuid128_t const & base_uuid, jau::nsize_t const uuid32_le_octet_index) const noexcept {
     switch(type) {
         case TypeSize::UUID16_SZ:  return uuid128_t( *( static_cast<const uuid16_t*>(this)  ), base_uuid, uuid32_le_octet_index);
diff --git a/test/test_uuid.cpp b/test/test_uuid.cpp
index e3174bf..ae2b351 100644
--- a/test/test_uuid.cpp
+++ b/test/test_uuid.cpp
@@ -63,11 +63,29 @@ TEST_CASE( "UUID Test 01", "[datatype][uuid]" ) {
 
 
     {
+        const uuid128_t v01("00001234-5678-100A-800B-00805F9B34FB");
+        REQUIRE(v01.getTypeSizeInt() == uuid_t::number( uuid_t::TypeSize::UUID128_SZ) );
+        REQUIRE(v01.getTypeSizeInt() == sizeof(v01.value));
+        REQUIRE("00001234-5678-100a-800b-00805f9b34fb" == v01.toString());
+        REQUIRE(uuid128_t("00001234-5678-100a-800b-00805f9b34fb") == v01);
+        REQUIRE(uuid128_t("00001234-5678-100a-800b-00805f9b34fc") != v01);
+    }
+    {
         const uuid16_t v01("1234");
         REQUIRE(v01.getTypeSizeInt() == uuid_t::number( uuid_t::TypeSize::UUID16_SZ ));
         REQUIRE(v01.getTypeSizeInt() == sizeof(v01.value));
         REQUIRE(0x1234 == v01.value);
         REQUIRE("1234" == v01.toString());
+
+        const uuid16_t v01_copy = v01;
+        REQUIRE(v01_copy == v01);
+        REQUIRE(uuid16_t("1235") != v01);
+
+        const uuid128_t v01_128 = v01.toUUID128();
+        const uuid128_t v02("00001234-0000-1000-8000-00805F9B34FB");
+        REQUIRE(v01_128 == v02);
+        REQUIRE(v01 != v02);
+        REQUIRE(v01.equivalent(v02));
     }
     {
         const uuid32_t v01("12345678");
@@ -75,12 +93,17 @@ TEST_CASE( "UUID Test 01", "[datatype][uuid]" ) {
         REQUIRE(v01.getTypeSizeInt() == sizeof(v01.value));
         REQUIRE(0x12345678 == v01.value);
         REQUIRE("12345678" == v01.toString());
-    }
-    {
-        const uuid128_t v01("00001234-5678-100A-800B-00805F9B34FB");
-        REQUIRE(v01.getTypeSizeInt() == uuid_t::number( uuid_t::TypeSize::UUID128_SZ) );
-        REQUIRE(v01.getTypeSizeInt() == sizeof(v01.value));
-        REQUIRE("00001234-5678-100a-800b-00805f9b34fb" == v01.toString());
+
+        const uuid32_t v01_copy = v01;
+        REQUIRE(v01_copy == v01);
+        REQUIRE(uuid32_t("12345679") != v01);
+
+        const uuid128_t v01_128 = v01.toUUID128();
+        const uuid128_t v02("12345678-0000-1000-8000-00805F9B34FB");
+        REQUIRE(v01_128 == v02);
+
+        REQUIRE(v01 != v02);
+        REQUIRE(v01.equivalent(v02));
     }