api: add function string_cut

5 files changed, 193 insertions, 0 deletions

diff --git a/doc/en/weechat_plugin_api.en.adoc b/doc/en/weechat_plugin_api.en.adoc
index f59599ca2..8a6f43ea4 100644
--- a/doc/en/weechat_plugin_api.en.adoc
+++ b/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.
diff --git a/doc/fr/weechat_plugin_api.fr.adoc b/doc/fr/weechat_plugin_api.fr.adoc
index 05cde620b..6dd686f8a 100644
--- a/doc/fr/weechat_plugin_api.fr.adoc
+++ b/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.
diff --git a/doc/it/weechat_plugin_api.it.adoc b/doc/it/weechat_plugin_api.it.adoc
index e0b4bf071..6840f374f 100644
--- a/doc/it/weechat_plugin_api.it.adoc
+++ b/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.
diff --git a/doc/ja/weechat_plugin_api.ja.adoc b/doc/ja/weechat_plugin_api.ja.adoc
index 14ca95693..13b95e648 100644
--- a/doc/ja/weechat_plugin_api.ja.adoc
+++ b/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 文字列を小文字に変換。
diff --git a/doc/sr/weechat_plugin_api.sr.adoc b/doc/sr/weechat_plugin_api.sr.adoc
index a646c004b..b114f2b34 100644
--- a/doc/sr/weechat_plugin_api.sr.adoc
+++ b/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 стринг у мала слова.