Add z_string_array documentation (#684)

eclipse-zenoh · Sep 20, 2024 · 84c6d4f · 84c6d4f
1 parent eefc89f
commit 84c6d4f
Show file tree

Hide file tree

Showing 3 changed files with 60 additions and 7 deletions.
diff --git a/docs/api.rst b/docs/api.rst
@@ -441,6 +441,12 @@ Primitives
 .. autocfunction:: primitives.h::z_keyexpr_from_substr
 .. autocfunction:: primitives.h::z_keyexpr_from_str_autocanonize
 .. autocfunction:: primitives.h::z_keyexpr_from_substr_autocanonize
+.. autocfunction:: primitives.h::z_string_array_new
+.. autocfunction:: primitives.h::z_string_array_push_by_alias
+.. autocfunction:: primitives.h::z_string_array_push_by_copy
+.. autocfunction:: primitives.h::z_string_array_get
+.. autocfunction:: primitives.h::z_string_array_len
+.. autocfunction:: primitives.h::z_string_array_is_empty
 .. autocfunction:: primitives.h::z_declare_keyexpr
 .. autocfunction:: primitives.h::z_undeclare_keyexpr
 .. autocfunction:: primitives.h::z_subscriber_options_default

diff --git a/include/zenoh-pico/api/primitives.h b/include/zenoh-pico/api/primitives.h
@@ -2142,6 +2142,60 @@ z_result_t z_declare_keyexpr(z_owned_keyexpr_t *declared_keyexpr, const z_loaned
  */
 z_result_t z_undeclare_keyexpr(z_moved_keyexpr_t *keyexpr, const z_loaned_session_t *zs);
 
+/**
+ * Constructs a new empty string array.
+ *
+ * Parameters:
+ *   a: Pointer to an uninitialized :c:type:`z_owned_string_array_t` to store the array of strings.
+ */
+void z_string_array_new(z_owned_string_array_t *a);
+
+/**
+ * Appends specified value to the end of the string array by alias.
+ *
+ * Parameters:
+ *   a: Pointer to :c:type:`z_loaned_string_array_t`.
+ *   value: Pointer to the string to be add.
+ *
+ * Return:
+ *   the new length of the array.
+ */
+size_t z_string_array_push_by_alias(z_loaned_string_array_t *a, const z_loaned_string_t *value);
+
+/**
+ * Appends specified value to the end of the string array by copying.
+ *
+ * Parameters:
+ *   a: Pointer to :c:type:`z_loaned_string_array_t`.
+ *   value: Pointer to the string to be add.
+ *
+ * Return:
+ *   the new length of the array.
+ */
+size_t z_string_array_push_by_copy(z_loaned_string_array_t *a, const z_loaned_string_t *value);
+
+/**
+ * Returns the value at the position of index in the string array.
+ *
+ * Parameters:
+ *   a: Pointer to :c:type:`z_loaned_string_array_t`.
+ *   k: index value.
+ *
+ * Return:
+ *   `NULL` if the index is out of bounds.
+ */
+const z_loaned_string_t *z_string_array_get(const z_loaned_string_array_t *a, size_t k);
+
+/**
+ * Returns number of elements in the array.
+ */
+size_t z_string_array_len(const z_loaned_string_array_t *a);
+
+/**
+ * Returns ``true`` if the array is empty, ``false`` otherwise.
+ */
+bool z_string_array_is_empty(const z_loaned_string_array_t *a);
+
 #if Z_FEATURE_SUBSCRIPTION == 1
 /**
  * Builds a :c:type:`z_subscriber_options_t` with default values.

diff --git a/include/zenoh-pico/api/types.h b/include/zenoh-pico/api/types.h
@@ -487,13 +487,6 @@ _Z_OWNED_TYPE_VALUE(_z_reply_t, reply)
 _Z_OWNED_TYPE_VALUE(_z_string_svec_t, string_array)
 _Z_VIEW_TYPE(_z_string_svec_t, string_array)
 
-void z_string_array_new(z_owned_string_array_t *a);
-size_t z_string_array_push_by_alias(z_loaned_string_array_t *a, const z_loaned_string_t *value);
-size_t z_string_array_push_by_copy(z_loaned_string_array_t *a, const z_loaned_string_t *value);
-const z_loaned_string_t *z_string_array_get(const z_loaned_string_array_t *a, size_t k);
-size_t z_string_array_len(const z_loaned_string_array_t *a);
-bool z_string_array_is_empty(const z_loaned_string_array_t *a);
-
 typedef void (*z_dropper_handler_t)(void *arg);
 typedef _z_data_handler_t z_data_handler_t;