Fix and align return values for keyexpr handlers (eclipse-zenoh#143)

* return zero as true

* rustfmt

* Update keyexpr functions

* Update docs

---------

Co-authored-by: Carlos Guimarães <[email protected]>

Author: milyin

include/zenoh_commons.h

@@ -1115,18 +1115,19 @@ struct z_owned_keyexpr_t z_keyexpr_concat(struct z_keyexpr_t left,
  */
 void z_keyexpr_drop(struct z_owned_keyexpr_t *keyexpr);
 /**
- * Returns ``1`` if `left` and `right` define equal sets, ``0`` otherwise.
+ * Returns ``0`` if both ``left`` and ``right`` are equal. Otherwise, it returns a ``-1``, or other ``negative value`` for errors.
  */
-int8_t z_keyexpr_equals(struct z_keyexpr_t left, struct z_keyexpr_t right);
+int8_t z_keyexpr_equals(struct z_keyexpr_t left,
+                        struct z_keyexpr_t right);
 /**
- * Returns ``1`` if the set defined by `left` contains every key belonging to the set defined by `right`, ``0`` if they don't.
- * Returns negative values in case of error (if one of the key expressions is in an invalid state).
+ * Returns ``0`` if ``left`` includes ``right``, i.e. the set defined by ``left`` contains every key belonging to the set
+ * defined by ``right``. Otherwise, it returns a ``-1``, or other ``negative value`` for errors.
  */
 int8_t z_keyexpr_includes(struct z_keyexpr_t left,
                           struct z_keyexpr_t right);
 /**
- * Returns ``1`` if `left` and `right` define sets that have at least one key in common, ``0`` if they don't.
- * Returns negative values in case of error (if one of the key expressions is in an invalid state).
+ * Returns ``0`` if the keyexprs intersect, i.e. there exists at least one key which is contained in both of the
+ * sets defined by ``left`` and ``right``. Otherwise, it returns a ``-1``, or other ``negative value`` for errors.
  */
 int8_t z_keyexpr_intersects(struct z_keyexpr_t left,
                             struct z_keyexpr_t right);

src/keyexpr.rs

@@ -459,29 +459,50 @@ pub extern "C" fn z_undeclare_keyexpr(session: z_session_t, kexpr: &mut z_owned_
 
 #[allow(clippy::missing_safety_doc)]
 #[no_mangle]
-/// Returns ``1`` if `left` and `right` define equal sets, ``0`` otherwise.
+/// Returns ``0`` if both ``left`` and ``right`` are equal. Otherwise, it returns a ``-1``, or other ``negative value`` for errors.
 pub extern "C" fn z_keyexpr_equals(left: z_keyexpr_t, right: z_keyexpr_t) -> i8 {
-    (*left == *right) as i8
+    match (&*left, &*right) {
+        (Some(l), Some(r)) => {
+            if *l == *r {
+                0
+            } else {
+                -1
+            }
+        }
+        _ => i8::MIN,
+    }
 }
 
 #[allow(clippy::missing_safety_doc)]
 #[no_mangle]
-/// Returns ``1`` if `left` and `right` define sets that have at least one key in common, ``0`` if they don't.
-/// Returns negative values in case of error (if one of the key expressions is in an invalid state).
+/// Returns ``0`` if the keyexprs intersect, i.e. there exists at least one key which is contained in both of the
+/// sets defined by ``left`` and ``right``. Otherwise, it returns a ``-1``, or other ``negative value`` for errors.
 pub extern "C" fn z_keyexpr_intersects(left: z_keyexpr_t, right: z_keyexpr_t) -> i8 {
     match (&*left, &*right) {
-        (Some(l), Some(r)) => l.intersects(r) as i8,
+        (Some(l), Some(r)) => {
+            if l.intersects(r) {
+                0
+            } else {
+                -1
+            }
+        }
         _ => i8::MIN,
     }
 }
 
 #[allow(clippy::missing_safety_doc)]
 #[no_mangle]
-/// Returns ``1`` if the set defined by `left` contains every key belonging to the set defined by `right`, ``0`` if they don't.
-/// Returns negative values in case of error (if one of the key expressions is in an invalid state).
+/// Returns ``0`` if ``left`` includes ``right``, i.e. the set defined by ``left`` contains every key belonging to the set
+/// defined by ``right``. Otherwise, it returns a ``-1``, or other ``negative value`` for errors.
 pub extern "C" fn z_keyexpr_includes(left: z_keyexpr_t, right: z_keyexpr_t) -> i8 {
     match (&*left, &*right) {
-        (Some(l), Some(r)) => l.includes(r) as i8,
+        (Some(l), Some(r)) => {
+            if l.includes(r) {
+                0
+            } else {
+                -1
+            }
+        }
         _ => i8::MIN,
     }
 }

tests/z_api_alignment_test.c

@@ -115,23 +115,24 @@ int main(int argc, char **argv) {
     _Bool _ret_bool = z_keyexpr_is_initialized(&key);
     assert(_ret_bool == true);
 
-    _ret_bool = z_keyexpr_includes(z_keyexpr("demo/example/**"), z_keyexpr("demo/example/a"));
-    assert(_ret_bool == true);
+    int8_t _ret_int;
+    _ret_int = z_keyexpr_includes(z_keyexpr("demo/example/**"), z_keyexpr("demo/example/a"));
+    assert(_ret_int == 0);
 #ifdef ZENOH_PICO
     _ret_bool = zp_keyexpr_includes_null_terminated("demo/example/**", "demo/example/a");
-    assert(_ret_bool == true);
+    assert(_ret_int == 0);
 #endif
-    _ret_bool = z_keyexpr_intersects(z_keyexpr("demo/example/**"), z_keyexpr("demo/example/a"));
-    assert(_ret_bool == true);
+    _ret_int = z_keyexpr_intersects(z_keyexpr("demo/example/**"), z_keyexpr("demo/example/a"));
+    assert(_ret_int == 0);
 #ifdef ZENOH_PICO
     _ret_bool = zp_keyexpr_intersect_null_terminated("demo/example/**", "demo/example/a");
-    assert(_ret_bool == true);
+    assert(_ret_int == 0);
 #endif
-    _ret_bool = z_keyexpr_equals(z_keyexpr("demo/example/**"), z_keyexpr("demo/example"));
-    assert(_ret_bool == false);
+    _ret_int = z_keyexpr_equals(z_keyexpr("demo/example/**"), z_keyexpr("demo/example"));
+    assert(_ret_int == -1);
 #ifdef ZENOH_PICO
     _ret_bool = zp_keyexpr_equals_null_terminated("demo/example/**", "demo/example");
-    assert(_ret_bool == false);
+    assert(_ret_int == -1);
 #endif
 
     sleep(SLEEP);

tests/z_api_keyexpr_test.c

@@ -47,21 +47,21 @@ void includes() {
     z_keyexpr_t nul = z_keyexpr(NULL);
     z_keyexpr_t foobar = z_keyexpr("foo/bar");
     z_keyexpr_t foostar = z_keyexpr("foo/*");
-    assert(z_keyexpr_includes(foostar, foobar) == 1);
-    assert(z_keyexpr_includes(foobar, foostar) == 0);
-    assert(z_keyexpr_includes(nul, foobar) < 0);
-    assert(z_keyexpr_includes(foobar, nul) < 0);
+    assert(z_keyexpr_includes(foostar, foobar) == 0);
+    assert(z_keyexpr_includes(foobar, foostar) == -1);
+    assert(z_keyexpr_includes(nul, foobar) < -1);
+    assert(z_keyexpr_includes(foobar, nul) < -1);
 }
 
 void intersects() {
     z_keyexpr_t nul = z_keyexpr(NULL);
     z_keyexpr_t foobar = z_keyexpr("foo/bar");
     z_keyexpr_t foostar = z_keyexpr("foo/*");
     z_keyexpr_t barstar = z_keyexpr("bar/*");
-    assert(z_keyexpr_intersects(foostar, foobar) == 1);
-    assert(z_keyexpr_intersects(barstar, foobar) == 0);
-    assert(z_keyexpr_intersects(nul, foobar) < 0);
-    assert(z_keyexpr_intersects(foobar, nul) < 0);
+    assert(z_keyexpr_intersects(foostar, foobar) == 0);
+    assert(z_keyexpr_intersects(barstar, foobar) == -1);
+    assert(z_keyexpr_intersects(nul, foobar) < -1);
+    assert(z_keyexpr_intersects(foobar, nul) < -1);
 }
 
 void undeclare() {