api: add function string_cut

doc/en/weechat_plugin_api.en.adoc

@@ -573,6 +573,44 @@ free (str);
 [NOTE]
 This function is not available in scripting API.
 
+==== string_cut
+
+_WeeChat ≥ 3.3._
+
+Cut a string after a given number of chars, add an optional suffix after the
+string if it is cut.
+
+Prototype:
+
+[source,C]
+----
+char *weechat_string_cut (const char *string, int length, int count_suffix, int screen, const char *cut_suffix);
+----
+
+Arguments:
+
+* _string_: string to cut
+* _length_: max chars
+* _count_suffix_: if 1, the length of suffix is counter in the max length
+* _screen_: if 1, the cut is based on width of chars displayed
+* _cut_suffix_: the suffix added after the string if it is cut
+
+Return value:
+
+* cut string (must be freed by calling "free" after use)
+
+C example:
+
+[source,C]
+----
+char *str = weechat_string_cut ("this is a test", 5, 1, 1, "…");  /* result: "this…" */
+/* ... */
+free (str);
+----
+
+[NOTE]
+This function is not available in scripting API.
+
 ==== string_tolower
 
 Convert UTF-8 string to lower case.

doc/fr/weechat_plugin_api.fr.adoc

@@ -583,6 +583,44 @@ free (str);
 [NOTE]
 Cette fonction n'est pas disponible dans l'API script.
 
+==== string_cut
+
+_WeeChat ≥ 3.3._
+
+Couper une chaîne après un nombre donné de caractères, ajouter un suffixe
+facultatif après la chaîne si elle est coupée.
+
+Prototype :
+
+[source,C]
+----
+char *weechat_string_cut (const char *string, int length, int count_suffix, int screen, const char *cut_suffix);
+----
+
+Paramètres :
+
+* _string_ : chaîne à couper
+* _length_ : nombre maximum de caractères
+* _count_suffix_ : si 1, la longueur du suffixe est comptée dans la longueur maximale
+* _screen_ : si 1, le découpage est basé sur la largeur des caractères affichés
+* _cut_suffix_ : le suffixe ajouté à la fin de la chaîne si elle est découpée
+
+Valeur de retour :
+
+* chaîne coupée (doit être supprimée par un appel à "free" après utilisation)
+
+Exemple en C :
+
+[source,C]
+----
+char *str = weechat_string_cut ("ceci est un test", 5, 1, 1, "…");  /* résultat : "ceci…" */
+/* ... */
+free (str);
+----
+
+[NOTE]
+Cette fonction n'est pas disponible dans l'API script.
+
 ==== string_tolower
 
 Convertir une chaîne UTF-8 en minuscules.

doc/it/weechat_plugin_api.it.adoc

@@ -605,6 +605,45 @@ free (str);
 [NOTE]
 Questa funzione non è disponibile nelle API per lo scripting.
 
+// TRANSLATION MISSING
+==== string_cut
+
+_WeeChat ≥ 3.3._
+
+Cut a string after a given number of chars, add an optional suffix after the
+string if it is cut.
+
+Prototipo:
+
+[source,C]
+----
+char *weechat_string_cut (const char *string, int length, int count_suffix, int screen, const char *cut_suffix);
+----
+
+Argomenti:
+
+* _string_: string to cut
+* _length_: max chars
+* _count_suffix_: if 1, the length of suffix is counter in the max length
+* _screen_: if 1, the cut is based on width of chars displayed
+* _cut_suffix_: the suffix added after the string if it is cut
+
+Valore restituito:
+
+* cut string (must be freed by calling "free" after use)
+
+Esempio in C:
+
+[source,C]
+----
+char *str = weechat_string_cut ("this is a test", 5, 1, 1, "…");  /* result: "this…" */
+/* ... */
+free (str);
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
 ==== string_tolower
 
 Converte una stringa UTF-8 in minuscolo.

doc/ja/weechat_plugin_api.ja.adoc

@@ -582,6 +582,45 @@ free (str);
 [NOTE]
 スクリプト API ではこの関数を利用できません。
 
+// TRANSLATION MISSING
+==== string_cut
+
+_WeeChat バージョン 3.3 以上で利用可。_
+
+Cut a string after a given number of chars, add an optional suffix after the
+string if it is cut.
+
+プロトタイプ:
+
+[source,C]
+----
+char *weechat_string_cut (const char *string, int length, int count_suffix, int screen, const char *cut_suffix);
+----
+
+引数:
+
+* _string_: string to cut
+* _length_: max chars
+* _count_suffix_: if 1, the length of suffix is counter in the max length
+* _screen_: if 1, the cut is based on width of chars displayed
+* _cut_suffix_: the suffix added after the string if it is cut
+
+戻り値:
+
+* cut string (must be freed by calling "free" after use)
+
+C 言語での使用例:
+
+[source,C]
+----
+char *str = weechat_string_cut ("this is a test", 5, 1, 1, "…");  /* result: "this…" */
+/* ... */
+free (str);
+----
+
+[NOTE]
+スクリプト API ではこの関数を利用できません。
+
 ==== string_tolower
 
 UTF-8 文字列を小文字に変換。

doc/sr/weechat_plugin_api.sr.adoc

@@ -547,6 +547,45 @@ free (str);
 [NOTE]
 Ова функција није доступна у API скриптовања.
 
+// TRANSLATION MISSING
+==== string_cut
+
+_WeeChat ≥ 3.3._
+
+Cut a string after a given number of chars, add an optional suffix after the
+string if it is cut.
+
+Прототип:
+
+[source,C]
+----
+char *weechat_string_cut (const char *string, int length, int count_suffix, int screen, const char *cut_suffix);
+----
+
+Аргументи:
+
+* _string_: string to cut
+* _length_: max chars
+* _count_suffix_: if 1, the length of suffix is counter in the max length
+* _screen_: if 1, the cut is based on width of chars displayed
+* _cut_suffix_: the suffix added after the string if it is cut
+
+Повратна вредност:
+
+* cut string (must be freed by calling "free" after use)
+
+C пример:
+
+[source,C]
+----
+char *str = weechat_string_cut ("this is a test", 5, 1, 1, "…");  /* result: "this…" */
+/* ... */
+free (str);
+----
+
+[NOTE]
+Ова функција није доступна у API скриптовања.
+
 ==== string_tolower
 
 Конвертује UTF-8 стринг у мала слова.

src/plugins/plugin.c

@@ -602,6 +602,7 @@ plugin_load (const char *filename, int init_plugin, int argc, char **argv)
         new_plugin->gettext = &plugin_api_gettext;
         new_plugin->ngettext = &plugin_api_ngettext;
         new_plugin->strndup = &string_strndup;
+        new_plugin->string_cut = &string_cut;
         new_plugin->string_tolower = &string_tolower;
         new_plugin->string_toupper = &string_toupper;
         new_plugin->strcasecmp = &string_strcasecmp;

src/plugins/weechat-plugin.h

@@ -68,7 +68,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 "20210703-01"
+#define WEECHAT_PLUGIN_API_VERSION "20210704-01"
 
 /* macros for defining plugin infos */
 #define WEECHAT_PLUGIN_NAME(__name)                                     \
@@ -285,6 +285,8 @@ struct t_weechat_plugin
     const char *(*gettext) (const char *string);
     const char *(*ngettext) (const char *single, const char *plural, int count);
     char *(*strndup) (const char *string, int length);
+    char *(*string_cut) (const char *string, int length, int count_suffix,
+                         int screen, const char *cut_suffix);
     void (*string_tolower) (char *string);
     void (*string_toupper) (char *string);
     int (*strcasecmp) (const char *string1, const char *string2);
@@ -1192,6 +1194,10 @@ extern int weechat_plugin_end (struct t_weechat_plugin *plugin);
     (weechat_plugin->ngettext)(single, plural, number)
 #define weechat_strndup(__string, __length)                             \
     (weechat_plugin->strndup)(__string, __length)
+#define weechat_string_cut(__string, __length, __count_suffix,          \
+                           __screen, __cut_suffix)                      \
+    (weechat_plugin->string_cut)(__string, __length, __count_suffix,    \
+                                 __screen, __cut_suffix)
 #define weechat_string_tolower(__string)                                \
     (weechat_plugin->string_tolower)(__string)
 #define weechat_string_toupper(__string)                                \