doc: add function string_convert_escaped_chars in plugin API reference

4 files changed, 206 insertions, 0 deletions

diff --git a/doc/en/weechat_plugin_api.en.txt b/doc/en/weechat_plugin_api.en.txt
index 9d3d8ebc5..6db28bd8c 100644
--- a/doc/en/weechat_plugin_api.en.txt
+++ b/doc/en/weechat_plugin_api.en.txt
@@ -995,6 +995,56 @@ free (str);
 [NOTE]
 This function is not available in scripting API.
 
+==== weechat_string_convert_escaped_chars
+
+_WeeChat ≥ 0.4.4._
+
+Convert escaped chars to their value:
+
+* `\"`: double quote
+* `\\`: backslash
+* `\a`: alert (BEL)
+* `\b`: backspace
+* `\e`: escape
+* `\f`: form feed
+* `\n`: new line
+* `\r`: carriage return
+* `\t`: horizontal tab
+* `\v`: vertical tab
+* `\0ooo`: char as octal value (ooo is 0 to 3 digits)
+* `\xhh`: char as hexadecimal value (hh is 1 to 2 digits)
+* `\uhhhh`: unicode char as hexadecimal value (hhhh is 1 to 4 digits)
+* `\Uhhhhhhhh`: unicode char as hexadecimal value (hhhhhhhh is 1 to 8 digits)
+
+Prototype:
+
+[source,C]
+----
+char *weechat_string_convert_escaped_chars (const char *string);
+----
+
+Arguments:
+
+* 'string': string
+
+Return value:
+
+* string with escaped chars replaced by their value (must be freed by calling
+  "free" after use)
+
+C example:
+
+[source,C]
+----
+char *str = weechat_string_convert_escaped_chars ("snowman: \\u2603");
+/* str == "snowman: ☃" */
+/* ... */
+free (str);
+----
+
+[NOTE]
+This function is not available in scripting API.
+
 ==== weechat_string_mask_to_regex
 
 Return a regex, built with a mask, where only special char is "`*`". All other
diff --git a/doc/fr/weechat_plugin_api.fr.txt b/doc/fr/weechat_plugin_api.fr.txt
index 5f09302d2..117d25031 100644
--- a/doc/fr/weechat_plugin_api.fr.txt
+++ b/doc/fr/weechat_plugin_api.fr.txt
@@ -1005,6 +1005,58 @@ free (str);
 [NOTE]
 Cette fonction n'est pas disponible dans l'API script.
 
+==== weechat_string_convert_escaped_chars
+
+_WeeChat ≥ 0.4.4._
+
+Convertir les caractères échappés par leur valeur :
+
+* `\"` : double guillemet droit
+* `\\` : barre oblique inversée
+* `\a` : alerte (BEL)
+* `\b` : retour arrière
+* `\e` : échappement
+* `\f` : saut de page
+* `\n` : nouvelle ligne
+* `\r` : retour chariot
+* `\t` : tabulation horizontale
+* `\v` : tabulation verticale
+* `\0ooo` : caractère sous forme de valeur octale (ooo a 0 à 3 chiffres)
+* `\xhh` : caractère sous forme de valeur hexadécimale (hh a 1 à 2 chiffres)
+* `\uhhhh` : caractère unicode sous forme de valeur hexadécimale (hhhh a 1 à 4
+  chiffres)
+* `\Uhhhhhhhh` : caractère unicode sous forme de valeur hexadécimale (hhhhhhhh
+  a 1 à 8 chiffres)
+
+Prototype :
+
+[source,C]
+----
+char *weechat_string_convert_escaped_chars (const char *string);
+----
+
+Paramètres :
+
+* 'string' : chaîne
+
+Valeur de retour :
+
+* chaîne avec les caractères échappés remplacés par leur valeur (doit être
+  supprimée par un appel à "free" après utilisation)
+
+Exemple en C :
+
+[source,C]
+----
+char *str = weechat_string_convert_escaped_chars ("snowman: \\u2603");
+/* str == "snowman: ☃" */
+/* ... */
+free (str);
+----
+
+[NOTE]
+Cette fonction n'est pas disponible dans l'API script.
+
 ==== weechat_string_mask_to_regex
 
 Retourner une expression régulière ("regex"), construite avec un masque où le
diff --git a/doc/it/weechat_plugin_api.it.txt b/doc/it/weechat_plugin_api.it.txt
index 363a62654..3bde8d1d2 100644
--- a/doc/it/weechat_plugin_api.it.txt
+++ b/doc/it/weechat_plugin_api.it.txt
@@ -1012,6 +1012,58 @@ free (str);
 [NOTE]
 Questa funzione non è disponibile nelle API per lo scripting.
 
+==== weechat_string_convert_escaped_chars
+
+_WeeChat ≥ 0.4.4._
+
+// TRANSLATION MISSING
+Convert escaped chars to their value:
+
+* `\"`: double quote
+* `\\`: backslash
+* `\a`: alert (BEL)
+* `\b`: backspace
+* `\e`: escape
+* `\f`: form feed
+* `\n`: new line
+* `\r`: carriage return
+* `\t`: horizontal tab
+* `\v`: vertical tab
+* `\0ooo`: char as octal value (ooo is 0 to 3 digits)
+* `\xhh`: char as hexadecimal value (hh is 1 to 2 digits)
+* `\uhhhh`: unicode char as hexadecimal value (hhhh is 1 to 4 digits)
+* `\Uhhhhhhhh`: unicode char as hexadecimal value (hhhhhhhh is 1 to 8 digits)
+
+Prototipo:
+
+[source,C]
+----
+char *weechat_string_convert_escaped_chars (const char *string);
+----
+
+Argomenti:
+
+* 'string': stringa
+
+Valore restituito:
+
+// TRANSLATION MISSING
+* string with escaped chars replaced by their value (deve essere liberata
+  chiamando "free" dopo l'uso)
+
+Esempio in C:
+
+[source,C]
+----
+char *str = weechat_string_convert_escaped_chars ("snowman: \\u2603");
+/* str == "snowman: ☃" */
+/* ... */
+free (str);
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
 ==== weechat_string_mask_to_regex
 
 Restituisce una espressione regolare con una mask, dove l'unico carattere
diff --git a/doc/ja/weechat_plugin_api.ja.txt b/doc/ja/weechat_plugin_api.ja.txt
index e634409ca..060bdccb3 100644
--- a/doc/ja/weechat_plugin_api.ja.txt
+++ b/doc/ja/weechat_plugin_api.ja.txt
@@ -994,6 +994,58 @@ free (str);
 [NOTE]
 スクリプト API ではこの関数を利用できません。
 
+==== weechat_string_convert_escaped_chars
+
+_WeeChat バージョン 0.4.4 以上で利用可。_
+
+// TRANSLATION MISSING
+Convert escaped chars to their value:
+
+* `\"`: double quote
+* `\\`: backslash
+* `\a`: alert (BEL)
+* `\b`: backspace
+* `\e`: escape
+* `\f`: form feed
+* `\n`: new line
+* `\r`: carriage return
+* `\t`: horizontal tab
+* `\v`: vertical tab
+* `\0ooo`: char as octal value (ooo is 0 to 3 digits)
+* `\xhh`: char as hexadecimal value (hh is 1 to 2 digits)
+* `\uhhhh`: unicode char as hexadecimal value (hhhh is 1 to 4 digits)
+* `\Uhhhhhhhh`: unicode char as hexadecimal value (hhhhhhhh is 1 to 8 digits)
+
+プロトタイプ:
+
+[source,C]
+----
+char *weechat_string_convert_escaped_chars (const char *string);
+----
+
+引数:
+
+* 'string': 文字列
+
+戻り値:
+
+// TRANSLATION MISSING
+* string with escaped chars replaced by their value
+  (使用後には必ず "free" を呼び出して領域を開放してください)
+
+C 言語での使用例:
+
+[source,C]
+----
+char *str = weechat_string_convert_escaped_chars ("snowman: \\u2603");
+/* str == "snowman: ☃" */
+/* ... */
+free (str);
+----
+
+[NOTE]
+スクリプト API ではこの関数を利用できません。
+
 ==== weechat_string_mask_to_regex
 
 マスクから正規表現を作りこれを返す、マスク用の特殊文字は