api: return newly allocated string in functions string_tolower and string_toupper

5 files changed, 148 insertions, 40 deletions

diff --git a/doc/en/weechat_plugin_api.en.adoc b/doc/en/weechat_plugin_api.en.adoc
index 64f2efeb9..e8619b081 100644
--- a/doc/en/weechat_plugin_api.en.adoc
+++ b/doc/en/weechat_plugin_api.en.adoc
@@ -616,25 +616,34 @@ This function is not available in scripting API.
 
 ==== string_tolower
 
-Convert UTF-8 string to lower case.
+_Updated in 3.8._
+
+Return a string with uppercase letters converted to lowercase. +
+This function is locale independent: only letters `A` to `Z` without accents
+are converted to lowercase. All other chars are kept as-is.
 
 Prototype:
 
 [source,c]
 ----
-void weechat_string_tolower (char *string);
+char *weechat_string_tolower (const char *string);
 ----
 
 Arguments:
 
 * _string_: string to convert
 
+Return value:
+
+* string with lowercase letters (must be freed by calling "free" after use)
+
 C example:
 
 [source,c]
 ----
-char str[] = "AbCdé";
-weechat_string_tolower (str);  /* str is now: "abcdé" */
+char *str = weechat_string_tolower ("ABCD_É");  /* result: "abcd_É" */
+/* ... */
+free (str);
 ----
 
 [NOTE]
@@ -642,25 +651,34 @@ This function is not available in scripting API.
 
 ==== string_toupper
 
-Convert UTF-8 string to upper case.
+_Updated in 3.8._
+
+Return a string with lowercase letters converted to uppercase. +
+This function is locale independent: only letters `a` to `z` without accents
+are converted to uppercase. All other chars are kept as-is.
 
 Prototype:
 
 [source,c]
 ----
-void weechat_string_toupper (char *string);
+char *weechat_string_toupper (const char *string);
 ----
 
 Arguments:
 
 * _string_: string to convert
 
+Return value:
+
+* string with uppercase letters (must be freed by calling "free" after use)
+
 C example:
 
 [source,c]
 ----
-char str[] = "AbCdé";
-weechat_string_toupper (str);  /* str is now: "ABCDé" */
+char *str = weechat_string_toupper ("abcd_é");  /* result: "ABCD_é" */
+/* ... */
+free (str);
 ----
 
 [NOTE]
diff --git a/doc/fr/weechat_plugin_api.fr.adoc b/doc/fr/weechat_plugin_api.fr.adoc
index a328da4d2..bac367bed 100644
--- a/doc/fr/weechat_plugin_api.fr.adoc
+++ b/doc/fr/weechat_plugin_api.fr.adoc
@@ -626,25 +626,36 @@ Cette fonction n'est pas disponible dans l'API script.
 
 ==== string_tolower
 
-Convertir une chaîne UTF-8 en minuscules.
+_Mis à jour dans la 3.8._
+
+Retourner une chaîne avec les lettres majuscules converties en minuscules. +
+Cette fonction n'est pas dépendante de la locale : seules les lettres `A` à `Z`
+sans accents sont converties en minuscules. Tous les autres caractères sont
+gardés tels quels.
 
 Prototype :
 
 [source,c]
 ----
-void weechat_string_tolower (char *string);
+char *weechat_string_tolower (const char *string);
 ----
 
 Paramètres :
 
 * _string_ : chaîne à convertir
 
+Valeur de retour :
+
+* chaîne avec les lettres en minuscules (doit être supprimée par un appel à "free"
+  après utilisation)
+
 Exemple en C :
 
 [source,c]
 ----
-char str[] = "AbCdé";
-weechat_string_tolower (str);  /* str vaut maintenant : "abcdé" */
+char *str = weechat_string_tolower ("ABCD_É");  /* résultat : "abcd_É" */
+/* ... */
+free (str);
 ----
 
 [NOTE]
@@ -652,25 +663,36 @@ Cette fonction n'est pas disponible dans l'API script.
 
 ==== string_toupper
 
-Convertir une chaîne UTF-8 en majuscules.
+_Mis à jour dans la 3.8._
+
+Retourner une chaîne avec les lettres minuscules converties en majuscules. +
+Cette fonction n'est pas dépendante de la locale : seules les lettres `a` à `z`
+sans accents sont converties en majuscules. Tous les autres caractères sont
+gardés tels quels.
 
 Prototype :
 
 [source,c]
 ----
-void weechat_string_toupper (char *string);
+char *weechat_string_toupper (const char *string);
 ----
 
 Paramètres :
 
 * _string_ : chaîne à convertir
 
+Valeur de retour :
+
+* chaîne avec les lettres en majuscules (doit être supprimée par un appel à "free"
+  après utilisation)
+
 Exemple en C :
 
 [source,c]
 ----
-char str[] = "AbCdé";
-weechat_string_toupper (str);  /* str vaut maintenant : "ABCDé" */
+char *str = weechat_string_toupper ("abcd_é");  /* résultat : "ABCD_é" */
+/* ... */
+free (str);
 ----
 
 [NOTE]
diff --git a/doc/it/weechat_plugin_api.it.adoc b/doc/it/weechat_plugin_api.it.adoc
index 11a22812a..01604d555 100644
--- a/doc/it/weechat_plugin_api.it.adoc
+++ b/doc/it/weechat_plugin_api.it.adoc
@@ -652,25 +652,37 @@ Questa funzione non è disponibile nelle API per lo scripting.
 
 ==== string_tolower
 
-Converte una stringa UTF-8 in minuscolo.
+// TRANSLATION MISSING
+_Updated in 3.8._
+
+// TRANSLATION MISSING
+Return a string with uppercase letters converted to lowercase. +
+This function is locale independent: only letters `A` to `Z` without accents
+are converted to lowercase. All other chars are kept as-is.
 
 Prototipo:
 
 [source,c]
 ----
-void weechat_string_tolower (char *string);
+char *weechat_string_tolower (const char *string);
 ----
 
 Argomenti:
 
 * _string_: stringa da convertire
 
+Valore restituito:
+
+// TRANSLATION MISSING
+* string with lowercase letters (must be freed by calling "free" after use)
+
 Esempio in C:
 
 [source,c]
 ----
-char str[] = "AbCdé";
-weechat_string_tolower (str);  /* str ora è: "abcdé" */
+char *str = weechat_string_tolower ("ABCD_É");  /* result: "abcd_É" */
+/* ... */
+free (str);
 ----
 
 [NOTE]
@@ -678,25 +690,37 @@ Questa funzione non è disponibile nelle API per lo scripting.
 
 ==== string_toupper
 
-Converte una stringa UTF-8 in maiuscolo.
+// TRANSLATION MISSING
+_Updated in 3.8._
+
+// TRANSLATION MISSING
+Return a string with lowercase letters converted to uppercase. +
+This function is locale independent: only letters `a` to `z` without accents
+are converted to uppercase. All other chars are kept as-is.
 
 Prototipo:
 
 [source,c]
 ----
-void weechat_string_toupper (char *string);
+char *weechat_string_toupper (const char *string);
 ----
 
 Argomenti:
 
 * _string_: stringa da convertire
 
+Valore restituito:
+
+// TRANSLATION MISSING
+* string with uppercase letters (must be freed by calling "free" after use)
+
 Esempio in C:
 
 [source,c]
 ----
-char str[] = "AbCdé";
-weechat_string_toupper (str);  /* str ora è: "ABCDé" */
+char *str = weechat_string_toupper ("abcd_é");  /* result: "ABCD_é" */
+/* ... */
+free (str);
 ----
 
 [NOTE]
diff --git a/doc/ja/weechat_plugin_api.ja.adoc b/doc/ja/weechat_plugin_api.ja.adoc
index 6feebc15a..0b5b042bb 100644
--- a/doc/ja/weechat_plugin_api.ja.adoc
+++ b/doc/ja/weechat_plugin_api.ja.adoc
@@ -630,25 +630,36 @@ free (str);
 
 ==== string_tolower
 
-UTF-8 文字列を小文字に変換。
+_WeeChat バージョン 3.8 で更新。_
+
+// TRANSLATION MISSING
+Return a string with uppercase letters converted to lowercase. +
+This function is locale independent: only letters `A` to `Z` without accents
+are converted to lowercase. All other chars are kept as-is.
 
 プロトタイプ:
 
 [source,c]
 ----
-void weechat_string_tolower (char *string);
+char *weechat_string_tolower (const char *string);
 ----
 
 引数:
 
 * _string_: 変換元の文字列
 
+戻り値:
+
+// TRANSLATION MISSING
+* string with lowercase letters (must be freed by calling "free" after use)
+
 C 言語での使用例:
 
 [source,c]
 ----
-char str[] = "AbCdé";
-weechat_string_tolower (str);  /* str is now: "abcdé" */
+char *str = weechat_string_tolower ("ABCD_É");  /* result: "abcd_É" */
+/* ... */
+free (str);
 ----
 
 [NOTE]
@@ -656,25 +667,36 @@ weechat_string_tolower (str);  /* str is now: "abcdé" */
 
 ==== string_toupper
 
-UTF-8 文字列を大文字に変換。
+_WeeChat バージョン 3.8 で更新。_
+
+// TRANSLATION MISSING
+Return a string with lowercase letters converted to uppercase. +
+This function is locale independent: only letters `a` to `z` without accents
+are converted to uppercase. All other chars are kept as-is.
 
 プロトタイプ:
 
 [source,c]
 ----
-void weechat_string_toupper (char *string);
+char *weechat_string_toupper (const char *string);
 ----
 
 引数:
 
 * _string_: 変換元の文字列
 
+戻り値:
+
+// TRANSLATION MISSING
+* string with uppercase letters (must be freed by calling "free" after use)
+
 C 言語での使用例:
 
 [source,c]
 ----
-char str[] = "AbCdé";
-weechat_string_toupper (str);  /* str is now: "ABCDé" */
+char *str = weechat_string_toupper ("abcd_é");  /* result: "ABCD_é" */
+/* ... */
+free (str);
 ----
 
 [NOTE]
diff --git a/doc/sr/weechat_plugin_api.sr.adoc b/doc/sr/weechat_plugin_api.sr.adoc
index e14da7d95..3ec897791 100644
--- a/doc/sr/weechat_plugin_api.sr.adoc
+++ b/doc/sr/weechat_plugin_api.sr.adoc
@@ -591,25 +591,36 @@ free (str);
 
 ==== string_tolower
 
-Конвертује UTF-8 стринг у мала слова.
+_Ажурирано у верзији 3.8._
+
+// TRANSLATION MISSING
+Return a string with uppercase letters converted to lowercase. +
+This function is locale independent: only letters `A` to `Z` without accents
+are converted to lowercase. All other chars are kept as-is.
 
 Прототип:
 
 [source,c]
 ----
-void weechat_string_tolower (char *string);
+char *weechat_string_tolower (const char *string);
 ----
 
 Аргументи:
 
 * _string_: стринг који се конвертује
 
+Повратна вредност:
+
+// TRANSLATION MISSING
+* string with lowercase letters (must be freed by calling "free" after use)
+
 C пример:
 
 [source,c]
 ----
-char str[] = "AbCdé";
-weechat_string_tolower (str);  /* str је сада: „abcdé” */
+char *str = weechat_string_tolower ("ABCD_É");  /* result: „abcd_É” */
+/* ... */
+free (str);
 ----
 
 [NOTE]
@@ -617,25 +628,36 @@ weechat_string_tolower (str);  /* str је сада: „abcdé” */
 
 ==== string_toupper
 
-Конвертује UTF-8 стринг у велика слова.
+_Ажурирано у верзији 3.8._
+
+// TRANSLATION MISSING
+Return a string with lowercase letters converted to uppercase. +
+This function is locale independent: only letters `a` to `z` without accents
+are converted to uppercase. All other chars are kept as-is.
 
 Прототип:
 
 [source,c]
 ----
-void weechat_string_toupper (char *string);
+char *weechat_string_toupper (const char *string);
 ----
 
 Аргументи:
 
 * _string_: стринг који се конвертује
 
+Повратна вредност:
+
+// TRANSLATION MISSING
+* string with uppercase letters (must be freed by calling "free" after use)
+
 C пример:
 
 [source,c]
 ----
-char str[] = "AbCdé";
-weechat_string_toupper (str);  /* str је сада: „ABCDé” */
+char *str = weechat_string_toupper ("abcd_é");  /* result: „ABCD_é” */
+/* ... */
+free (str);
 ----
 
 [NOTE]