api: add function list_user_data (issue #666)

ChangeLog.adoc

@@ -22,6 +22,7 @@ New features::
 
   * core: add support of 32767 color pairs (issue #1343, issue #1345)
   * core: add option "close" in command /window (issue #853)
+  * api: add function list_user_data (issue #666)
   * api: add argument "strip_items" in function string_split
   * buflist: add infolist "buflist" with list of buffer pointers (issue #1375)
   * exec: evaluate option exec.command.shell, change default value to "${env:SHELL}" (issue #1356)

doc/en/weechat_plugin_api.en.adoc

@@ -4071,6 +4071,37 @@ value = weechat.list_string(item)
 weechat.prnt("", "value of item: %s" % weechat.list_string(item))
 ----
 
+==== list_user_data
+
+_WeeChat ≥ 2.6._
+
+Return pointer to the user data of an item.
+
+Prototype:
+
+[source,C]
+----
+void *weechat_list_user_data (struct t_weelist_item *item);
+----
+
+Arguments:
+
+* _item_: item pointer
+
+Return value:
+
+* pointer to the user data of item
+
+C example:
+
+[source,C]
+----
+weechat_printf (NULL, "user data of item: 0x%lx", weechat_list_user_data (item));
+----
+
+[NOTE]
+This function is not available in scripting API.
+
 ==== list_size
 
 Return size of list (number of items).

doc/fr/weechat_plugin_api.fr.adoc

@@ -4123,7 +4123,7 @@ Exemple en C :
 
 [source,C]
 ----
-weechat_printf (NULL, "valeur de l'item : %s", weechat_list_string (item));
+weechat_printf (NULL, "valeur de l'élément : %s", weechat_list_string (item));
 ----
 
 Script (Python) :
@@ -4134,9 +4134,41 @@ Script (Python) :
 value = weechat.list_string(item)
 
 # exemple
-weechat.prnt("", "valeur de l'item : %s" % weechat.list_string(item))
+weechat.prnt("", "valeur de l'élément : %s" % weechat.list_string(item))
 ----
 
+==== list_user_data
+
+_WeeChat ≥ 2.6._
+
+// TRANSLATION MISSING
+Retourner le pointeur vers les données utilisateur de l'élément.
+
+Prototype :
+
+[source,C]
+----
+void *weechat_list_user_data (struct t_weelist_item *item);
+----
+
+Paramètres :
+
+* _item_ : pointeur vers l'élément
+
+Valeur de retour :
+
+* pointeur vers les données utilisateur de l'élément
+
+Exemple en C :
+
+[source,C]
+----
+weechat_printf (NULL, "données utilisateur de l'élément : 0x%lx", weechat_list_user_data (item));
+----
+
+[NOTE]
+Cette fonction n'est pas disponible dans l'API script.
+
 ==== list_size
 
 Retourner la taille de la liste (nombre d'éléments).
@@ -4416,7 +4448,7 @@ Exemple en C :
 
 [source,C]
 ----
-void *pointer = weechat_arraylist_get (arraylist, 0);  /* first item */
+void *pointer = weechat_arraylist_get (arraylist, 0);  /* premier élément */
 ----
 
 [NOTE]
@@ -4763,7 +4795,7 @@ Paramètres :
 
 Valeur de retour :
 
-* pointeur vers l'item créé/mis à jour, NULL en cas d'erreur
+* pointeur vers l'entrée créée/mise à jour, NULL en cas d'erreur
 
 Exemple en C :
 

doc/it/weechat_plugin_api.it.adoc

@@ -4230,6 +4230,39 @@ value = weechat.list_string(item)
 weechat.prnt("", "valore dell'elemento: %s" % weechat.list_string(item))
 ----
 
+==== list_user_data
+
+_WeeChat ≥ 2.6._
+
+// TRANSLATION MISSING
+Return pointer to the user data of an item.
+
+Prototipo:
+
+[source,C]
+----
+void *weechat_list_user_data (struct t_weelist_item *item);
+----
+
+Argomenti:
+
+* _item_: puntatore all'elemento
+
+Valore restituito:
+
+// TRANSLATION MISSING
+* pointer to the user data of item
+
+Esempio in C:
+
+[source,C]
+----
+weechat_printf (NULL, "user data of item: 0x%lx", weechat_list_user_data (item));
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
 ==== list_size
 
 Restituisce la dimensione della lista (numero di elementi).

doc/ja/weechat_plugin_api.ja.adoc

@@ -4081,6 +4081,40 @@ value = weechat.list_string(item)
 weechat.prnt("", "value of item: %s" % weechat.list_string(item))
 ----
 
+==== list_user_data
+
+_WeeChat バージョン 2.6 以上で利用可_
+
+// TRANSLATION MISSING
+Return pointer to the user data of an item.
+
+プロトタイプ:
+
+[source,C]
+----
+void *weechat_list_user_data (struct t_weelist_item *item);
+----
+
+引数:
+
+* _item_: 要素へのポインタ
+
+戻り値:
+
+// TRANSLATION MISSING
+* pointer to the user data of item
+
+C 言語での使用例:
+
+// TRANSLATION MISSING
+[source,C]
+----
+weechat_printf (NULL, "user data of item: 0x%lx", weechat_list_user_data (item));
+----
+
+[NOTE]
+スクリプト API ではこの関数を利用できません。
+
 ==== list_size
 
 リストのサイズ (要素の個数) を返す。

src/core/wee-list.c

@@ -349,6 +349,19 @@ weelist_string (struct t_weelist_item *item)
     return NULL;
 }
 
+/*
+ * Gets user data pointer to item data.
+ */
+
+void *
+weelist_user_data (struct t_weelist_item *item)
+{
+    if (item)
+        return item->user_data;
+
+    return NULL;
+}
+
 /*
  * Gets size of list.
  */

src/core/wee-list.h

@@ -51,6 +51,7 @@ extern void weelist_set (struct t_weelist_item *item, const char *value);
 extern struct t_weelist_item *weelist_next (struct t_weelist_item *item);
 extern struct t_weelist_item *weelist_prev (struct t_weelist_item *item);
 extern const char *weelist_string (struct t_weelist_item *item);
+extern void *weelist_user_data (struct t_weelist_item *item);
 extern int weelist_size (struct t_weelist *weelist);
 extern void weelist_remove (struct t_weelist *weelist,
                             struct t_weelist_item *item);

src/plugins/plugin.c

@@ -672,6 +672,7 @@ plugin_load (const char *filename, int init_plugin, int argc, char **argv)
         new_plugin->list_next = &weelist_next;
         new_plugin->list_prev = &weelist_prev;
         new_plugin->list_string = &weelist_string;
+        new_plugin->list_user_data = &weelist_user_data;
         new_plugin->list_size = &weelist_size;
         new_plugin->list_remove = &weelist_remove;
         new_plugin->list_remove_all = &weelist_remove_all;

src/plugins/weechat-plugin.h

@@ -67,7 +67,7 @@ struct timeval;
  * please change the date with current one; for a second change at same
  * date, increment the 01, otherwise please keep 01.
  */
-#define WEECHAT_PLUGIN_API_VERSION "20190624-01"
+#define WEECHAT_PLUGIN_API_VERSION "20190810-01"
 
 /* macros for defining plugin infos */
 #define WEECHAT_PLUGIN_NAME(__name)                                     \
@@ -409,6 +409,7 @@ struct t_weechat_plugin
     struct t_weelist_item *(*list_next) (struct t_weelist_item *item);
     struct t_weelist_item *(*list_prev) (struct t_weelist_item *item);
     const char *(*list_string) (struct t_weelist_item *item);
+    void *(*list_user_data) (struct t_weelist_item *item);
     int (*list_size) (struct t_weelist *weelist);
     void (*list_remove) (struct t_weelist *weelist,
                          struct t_weelist_item *item);
@@ -1357,6 +1358,8 @@ extern int weechat_plugin_end (struct t_weechat_plugin *plugin);
     (weechat_plugin->list_prev)(__item)
 #define weechat_list_string(__item)                                     \
     (weechat_plugin->list_string)(__item)
+#define weechat_list_user_data(__item)                                  \
+    (weechat_plugin->list_user_data)(__item)
 #define weechat_list_size(__list)                                       \
     (weechat_plugin->list_size)(__list)
 #define weechat_list_remove(__list, __item)                             \

tests/unit/core/test-core-list.cpp

@@ -31,6 +31,10 @@ extern "C"
 #define LIST_VALUE_XYZ  "xyz"
 #define LIST_VALUE_ZZZ  "zzz"
 
+int list_value_user_data_test;
+int list_value_user_data_xyz;
+int list_value_user_data_zzz;
+
 TEST_GROUP(CoreList)
 {
 };
@@ -46,9 +50,12 @@ test_list_new ()
 
     list = weelist_new ();
 
-    weelist_add (list, LIST_VALUE_ZZZ, WEECHAT_LIST_POS_END, NULL);
-    weelist_add (list, LIST_VALUE_TEST, WEECHAT_LIST_POS_BEGINNING, NULL);
-    weelist_add (list, LIST_VALUE_XYZ, WEECHAT_LIST_POS_SORT, NULL);
+    weelist_add (list, LIST_VALUE_ZZZ, WEECHAT_LIST_POS_END,
+                 &list_value_user_data_zzz);
+    weelist_add (list, LIST_VALUE_TEST, WEECHAT_LIST_POS_BEGINNING,
+                 &list_value_user_data_test);
+    weelist_add (list, LIST_VALUE_XYZ, WEECHAT_LIST_POS_SORT,
+                 &list_value_user_data_xyz);
 
     return list;
 }
@@ -231,6 +238,7 @@ TEST(CoreList, Search)
  * Tests functions:
  *   weelist_get
  *   weelist_string
+ *   weelist_user_data
  */
 
 TEST(CoreList, Get)
@@ -273,6 +281,18 @@ TEST(CoreList, Get)
     ptr_item = weelist_get(list, 2);
     STRCMP_EQUAL(LIST_VALUE_ZZZ, weelist_string (ptr_item));
 
+    /* get user_data value of an element */
+    POINTERS_EQUAL(NULL, weelist_user_data (NULL));
+
+    ptr_item = weelist_get(list, 0);
+    POINTERS_EQUAL(&list_value_user_data_test, weelist_user_data (ptr_item));
+
+    ptr_item = weelist_get(list, 1);
+    POINTERS_EQUAL(&list_value_user_data_xyz, weelist_user_data (ptr_item));
+
+    ptr_item = weelist_get(list, 2);
+    POINTERS_EQUAL(&list_value_user_data_zzz, weelist_user_data (ptr_item));
+
     /* free list */
     weelist_free (list);
 }