api: add arraylist functions

New functions: - arraylist_new - arraylist_size - arraylist_get - arraylist_search - arraylist_insert - arraylist_add - arraylist_remove - arraylist_clear - arraylist_free
2026-07-09 03:03:12 +02:00 · 2017-03-12 18:26:51 +01:00
parent da0fea8a60
commit 77af4e0a87
6 changed files with 1489 additions and 3 deletions
@@ -3950,6 +3950,374 @@ weechat.list_free(list)
 weechat.list_free(list)
 ----

+[[array_lists]]
+=== Array lists
+
+// TRANSLATION MISSING
+Array list functions.
+
+An array list is a list of pointers with a dynamic size and optional sort.
+
+==== arraylist_new
+
+_WeeChat ≥ 1.8._
+
+// TRANSLATION MISSING
+Create a new array list.
+
+Prototipo:
+
+[source,C]
+----
+struct t_arraylist *weechat_arraylist_new (int initial_size,
+                                           int sorted,
+                                           int allow_duplicates,
+                                           int (*callback_cmp)(void *data,
+                                                               struct t_arraylist *arraylist,
+                                                               void *pointer1,
+                                                               void *pointer2),
+                                           void *callback_cmp_data,
+                                           void (*callback_free)(void *data,
+                                                                 struct t_arraylist *arraylist,
+                                                                 void *pointer),
+                                           void *callback_free_data);
+----
+
+Argomenti:
+
+// TRANSLATION MISSING
+* _initial_size_: initial size of the array list (not the number of items)
+* _sorted_: 1 to sort the array list, 0 for no sort
+* _allow_duplicates_: 1 to allow duplicate entries, 0 to prevent a same entry
+  to be added again
+* _callback_cmp_: callback used to compare two items, arguments and return value:
+** _void *data_: pointer
+** _struct t_arraylist *arraylist_: array list pointer
+** _void *pointer1_: pointer to first item
+** _void *pointer2_: pointer to second item
+** return value:
+*** negative number if first item is less than second item
+*** 0 if first item equals second item
+*** positive number if first item is greater than second item
+* _callback_cmp_data_: pointer given to callback when it is called by WeeChat
+* _callback_free_: callback used to free an item (optional), arguments:
+** _void *data_: pointer
+** _struct t_arraylist *arraylist_: array list pointer
+** _void *pointer_: pointer to item
+* _callback_free_data_: pointer given to callback when it is called by WeeChat
+
+Valore restituito:
+
+// TRANSLATION MISSING
+* pointer to new array list
+
+Esempio in C:
+
+[source,C]
+----
+int
+cmp_cb (void *data, struct t_arraylist *arraylist,
+        void *pointer1, void *pointer2)
+{
+    if (...)
+        return -1;
+    else if (...)
+        return 1;
+    else
+        return 0;
+}
+
+struct t_arraylist *list = weechat_arraylist_new (32, 1, 1,
+                                                  &cmp_cb, NULL, NULL, NULL);
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
+==== arraylist_size
+
+_WeeChat ≥ 1.8._
+
+// TRANSLATION MISSING
+Return size of array list (number of item pointers).
+
+Prototipo:
+
+[source,C]
+----
+int weechat_list_size (struct t_arraylist *arraylist);
+----
+
+Argomenti:
+
+// TRANSLATION MISSING
+* _arraylist_: array list pointer
+
+Valore restituito:
+
+// TRANSLATION MISSING
+* size of array list (number of items), 0 if array list is empty
+
+Esempio in C:
+
+[source,C]
+----
+weechat_printf (NULL, "size of array list: %d", weechat_arraylist_size (arraylist));
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
+==== arraylist_get
+
+_WeeChat ≥ 1.8._
+
+// TRANSLATION MISSING
+Return an item pointer by position.
+
+Prototipo:
+
+[source,C]
+----
+void *weechat_arraylist_get (struct t_arraylist *arraylist, int index);
+----
+
+Argomenti:
+
+// TRANSLATION MISSING
+* _arraylist_: array list pointer
+* _index_: index in list (first pointer is 0)
+
+Valore restituito:
+
+// TRANSLATION MISSING
+* pointer found, NULL if pointer was not found
+
+Esempio in C:
+
+[source,C]
+----
+void *pointer = weechat_arraylist_get (arraylist, 0);  /* first item */
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
+==== arraylist_search
+
+_WeeChat ≥ 1.8._
+
+// TRANSLATION MISSING
+Search an item in an array list.
+
+Prototipo:
+
+[source,C]
+----
+void *weechat_arraylist_search (struct t_arraylist *arraylist, void *pointer,
+                                int *index, int *index_insert);
+----
+
+Argomenti:
+
+// TRANSLATION MISSING
+* _arraylist_: array list pointer
+* _pointer_: pointer to the item to search in array list
+* _index_: pointer to integer that will be set to the index found, or -1 if not found
+  (optional)
+* _index_insert_: pointer to integer that will be set with the index that must be
+  used to insert the element in the arraylist (to keep arraylist sorted) (optional)
+
+Valore restituito:
+
+// TRANSLATION MISSING
+* pointer to item found, NULL if item was not found
+
+Esempio in C:
+
+[source,C]
+----
+int index, index_insert;
+void *item = weechat_arraylist_search (arraylist, pointer, &index, &index_insert);
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
+==== arraylist_insert
+
+_WeeChat ≥ 1.8._
+
+// TRANSLATION MISSING
+Insert an item in an array list.
+
+Prototipo:
+
+[source,C]
+----
+int weechat_arraylist_insert (struct t_arraylist *arraylist, int index, void *pointer);
+----
+
+Argomenti:
+
+// TRANSLATION MISSING
+* _arraylist_: array list pointer
+* _index_: position of the item in array list or -1 to add at the end
+  (this argument is used only if the array list is not sorted, it is ignored if
+  the array list is sorted)
+* _pointer_: pointer to the item to insert
+
+Valore restituito:
+
+// TRANSLATION MISSING
+* index of new item (>= 0), -1 if error.
+
+Esempio in C:
+
+[source,C]
+----
+int index = weechat_arraylist_insert (arraylist, -1, pointer);  /* insert at the end if not sorted */
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
+==== arraylist_add
+
+_WeeChat ≥ 1.8._
+
+// TRANSLATION MISSING
+Add an item in an array list.
+
+Prototipo:
+
+[source,C]
+----
+int weechat_arraylist_add (struct t_arraylist *arraylist, void *pointer);
+----
+
+Argomenti:
+
+// TRANSLATION MISSING
+* _arraylist_: array list pointer
+* _pointer_: pointer to the item to add
+
+Valore restituito:
+
+// TRANSLATION MISSING
+* index of new item (>= 0), -1 if error.
+
+Esempio in C:
+
+[source,C]
+----
+int index = weechat_arraylist_add (arraylist, pointer);
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
+==== arraylist_remove
+
+_WeeChat ≥ 1.8._
+
+// TRANSLATION MISSING
+Remove an item from an array list.
+
+Prototipo:
+
+[source,C]
+----
+int weechat_arraylist_remove (struct t_arraylist *arraylist, int index);
+----
+
+Argomenti:
+
+// TRANSLATION MISSING
+* _arraylist_: array list pointer
+* _index_: index of the item to remove
+
+Valore restituito:
+
+// TRANSLATION MISSING
+* index of item removed, -1 if error.
+
+Esempio in C:
+
+[source,C]
+----
+int index_removed = weechat_arraylist_remove (arraylist, index);
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
+==== arraylist_clear
+
+_WeeChat ≥ 1.8._
+
+// TRANSLATION MISSING
+Remove all items from an array list.
+
+Prototipo:
+
+[source,C]
+----
+int weechat_arraylist_clear (struct t_arraylist *arraylist);
+----
+
+Argomenti:
+
+// TRANSLATION MISSING
+* _arraylist_: array list pointer
+
+Valore restituito:
+
+// TRANSLATION MISSING
+* 1 if OK, 0 if error
+
+Esempio in C:
+
+[source,C]
+----
+if (weechat_arraylist_clear (arraylist))
+{
+    /* OK */
+}
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
+==== arraylist_free
+
+_WeeChat ≥ 1.8._
+
+// TRANSLATION MISSING
+Free an array list.
+
+Prototipo:
+
+[source,C]
+----
+void weechat_arraylist_free (struct t_arraylist *arraylist);
+----
+
+Argomenti:
+
+// TRANSLATION MISSING
+* _arraylist_: array list pointer
+
+Esempio in C:
+
+[source,C]
+----
+weechat_arraylist_free (arraylist);
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
 [[hashtables]]
 === Tabelle hash

@@ -16072,7 +16440,7 @@ weechat_hdata_set (hdata, pointer, "message", "test");
 ----

 [NOTE]
-This function is not available in scripting API.
+Questa funzione non è disponibile nelle API per lo scripting.

 // TRANSLATION MISSING
 ==== hdata_update