doc: add function string_replace_regex in plugin API reference

4 files changed, 231 insertions, 1 deletions

diff --git a/doc/en/weechat_plugin_api.en.txt b/doc/en/weechat_plugin_api.en.txt
index de66d72a3..0bbdf514d 100644
--- a/doc/en/weechat_plugin_api.en.txt
+++ b/doc/en/weechat_plugin_api.en.txt
@@ -1214,6 +1214,60 @@ highlight = weechat.string_has_highlight_regex(string, regex)
 highlight = weechat.string_has_highlight_regex("my test string", "test|word2") # 1
 ----
 
+==== weechat_string_replace_regex
+
+_WeeChat ≥ 0.4.4._
+
+Replace text in a string using a regular expression and replacement text.
+
+Prototype:
+
+[source,C]
+----
+char *weechat_string_replace_regex (const char *string, void *regex,
+                                    const char *replace, const char reference_char);
+----
+
+Arguments:
+
+* 'string': string
+* 'regex': pointer to a regular expression ('regex_t' structure) compiled with
+  WeeChat function <<_weechat_string_regcomp,weechat_string_regcomp>> or regcomp
+  (see `man regcomp`)
+* 'replace': replacement text, where following references are allowed:
+** `$0` to `$99`: match 0 to 99 in regular expression (0 is the whole match,
+   1 to 99 are groups captured between parentheses)
+** `$+`: the last match (with highest number)
+** `$.*N`: match `N` (can be `+` or `0` to `99`), with all chars replaced by `*`
+   (the `*` char can be any char between space (32) and `~` (126))
+* 'reference_char': the char used for reference to match (commonly '$')
+
+Return value:
+
+* string with text replaced, NULL if problem (must be freed by calling "free"
+  after use)
+
+C example:
+
+[source,C]
+----
+regex_t my_regex;
+char *string;
+if (weechat_string_regcomp (&my_regex, "([0-9]{4})-([0-9]{2})-([0-9]{2})",
+                            REG_EXTENDED) == 0)
+{
+    string = weechat_string_replace_regex ("date: 2014-02-14", &my_regex,
+                                           "$3/$2/$1", '$');
+    /* string == "date: 14/02/2014" */
+    if (string)
+        free (string);
+    regfree (&my_regex);
+}
+----
+
+[NOTE]
+This function is not available in scripting API.
+
 ==== weechat_string_split
 
 Split a string according to one or more delimiter(s).
@@ -1244,7 +1298,7 @@ Return value:
 * array of strings, NULL if problem (must be freed by calling
   <<_weechat_string_free_split,weechat_string_free_split>> after use)
 
-C examples:
+C example:
 
 [source,C]
 ----
diff --git a/doc/fr/weechat_plugin_api.fr.txt b/doc/fr/weechat_plugin_api.fr.txt
index d65ee1369..186cc0874 100644
--- a/doc/fr/weechat_plugin_api.fr.txt
+++ b/doc/fr/weechat_plugin_api.fr.txt
@@ -1230,6 +1230,65 @@ highlight = weechat.string_has_highlight_regex(string, regex)
 highlight = weechat.string_has_highlight_regex("my test string", "test|word2") # 1
 ----
 
+==== weechat_string_replace_regex
+
+_WeeChat ≥ 0.4.4._
+
+Remplacer du texte dans une chaîne en utilisant une expression régulière et du
+texte de remplacement.
+
+Prototype :
+
+[source,C]
+----
+char *weechat_string_replace_regex (const char *string, void *regex,
+                                    const char *replace, const char reference_char);
+----
+
+Paramètres :
+
+* 'string' : chaîne
+* 'regex' : pointeur vers une expression régulière (structure 'regex_t')
+  compilée avec la fonction WeeChat
+  <<_weechat_string_regcomp,weechat_string_regcomp>> ou regcomp (voir
+  `man regcomp`)
+* 'replace' : texte de remplacement, où les références suivantes sont
+  autorisées :
+** `$0` à `$99` : correspondance 0 à 99 dans l'expression régulière (0 est la
+   correspondance entière, 1 à 99 sont les groupes capturés entre parenthèses)
+** `$+` : la dernière correspondance (avec le numéro le plus élevé)
+** `$.*N` : correspondance `N` (peut être `+` ou de `0` à `99`), avec tous les
+   caractères remplacés par `*` (le caractère `*` peut être n'importe quel
+   caractère entre l'espace (32) et `~` (126))
+* 'reference_char' : le caractère utilisé pour les références aux
+  correspondances (en général '$')
+
+Valeur de retour :
+
+* chaîne avec le texte remplacé, NULL en cas de problème (doit être supprimée
+  par un appel à "free" après utilisation)
+
+Exemple en C :
+
+[source,C]
+----
+regex_t my_regex;
+char *string;
+if (weechat_string_regcomp (&my_regex, "([0-9]{4})-([0-9]{2})-([0-9]{2})",
+                            REG_EXTENDED) == 0)
+{
+    string = weechat_string_replace_regex ("date: 2014-02-14", &my_regex,
+                                           "$3/$2/$1", '$');
+    /* string == "date: 14/02/2014" */
+    if (string)
+        free (string);
+    regfree (&my_regex);
+}
+----
+
+[NOTE]
+Cette fonction n'est pas disponible dans l'API script.
+
 ==== weechat_string_split
 
 Découper une chaîne à l'aide de délimiteur(s).
diff --git a/doc/it/weechat_plugin_api.it.txt b/doc/it/weechat_plugin_api.it.txt
index 40e6e31cd..08f18b799 100644
--- a/doc/it/weechat_plugin_api.it.txt
+++ b/doc/it/weechat_plugin_api.it.txt
@@ -1245,6 +1245,63 @@ highlight = weechat.string_has_highlight_regex(string, regex)
 highlight = weechat.string_has_highlight_regex("my test string", "test|word2") # 1
 ----
 
+==== weechat_string_replace_regex
+
+_WeeChat ≥ 0.4.4._
+
+// TRANSLATION MISSING
+Replace text in a string using a regular expression and replacement text.
+
+Prototipo:
+
+[source,C]
+----
+char *weechat_string_replace_regex (const char *string, void *regex,
+                                    const char *replace, const char reference_char);
+----
+
+Argomenti:
+
+// TRANSLATION MISSING
+* 'string': string
+* 'regex': pointer to a regular expression ('regex_t' structure) compiled with
+  WeeChat function <<_weechat_string_regcomp,weechat_string_regcomp>> or regcomp
+  (see `man regcomp`)
+* 'replace': replacement text, where following references are allowed:
+** `$0` to `$99`: match 0 to 99 in regular expression (0 is the whole match,
+   1 to 99 are groups captured between parentheses)
+** `$+`: the last match (with highest number)
+** `$.*N`: match `N` (can be `+` or `0` to `99`), with all chars replaced by `*`
+   (the `*` char can be any char between space (32) and `~` (126))
+* 'reference_char': the char used for reference to match (commonly '$')
+
+Valore restituito:
+
+// TRANSLATION MISSING
+* string with text replaced, NULL if problem (must be freed by calling "free"
+  after use)
+
+Esempio in C:
+
+[source,C]
+----
+regex_t my_regex;
+char *string;
+if (weechat_string_regcomp (&my_regex, "([0-9]{4})-([0-9]{2})-([0-9]{2})",
+                            REG_EXTENDED) == 0)
+{
+    string = weechat_string_replace_regex ("date: 2014-02-14", &my_regex,
+                                           "$3/$2/$1", '$');
+    /* string == "date: 14/02/2014" */
+    if (string)
+        free (string);
+    regfree (&my_regex);
+}
+----
+
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
 ==== weechat_string_split
 
 Divide una stringa in base a uno o più delimitatori.
@@ -1301,6 +1358,9 @@ argv = weechat_string_split ("abc de  fghi", " ", 1, 0, &argc);
 weechat_string_free_split (argv);
 ----
 
+[NOTE]
+Questa funzione non è disponibile nelle API per lo scripting.
+
 ==== weechat_string_free_split
 
 Libera la memoria usata per la divisione di una stringa.
diff --git a/doc/ja/weechat_plugin_api.ja.txt b/doc/ja/weechat_plugin_api.ja.txt
index d019d55a3..b35c5ccc6 100644
--- a/doc/ja/weechat_plugin_api.ja.txt
+++ b/doc/ja/weechat_plugin_api.ja.txt
@@ -1212,6 +1212,63 @@ highlight = weechat.string_has_highlight_regex(string, regex)
 highlight = weechat.string_has_highlight_regex("my test string", "test|word2") # 1
 ----
 
+==== weechat_string_replace_regex
+
+_WeeChat バージョン 0.4.4 以上で利用可。_
+
+// TRANSLATION MISSING
+Replace text in a string using a regular expression and replacement text.
+
+プロトタイプ:
+
+[source,C]
+----
+char *weechat_string_replace_regex (const char *string, void *regex,
+                                    const char *replace, const char reference_char);
+----
+
+引数:
+
+// TRANSLATION MISSING
+* 'string': string
+* 'regex': pointer to a regular expression ('regex_t' structure) compiled with
+  WeeChat function <<_weechat_string_regcomp,weechat_string_regcomp>> or regcomp
+  (see `man regcomp`)
+* 'replace': replacement text, where following references are allowed:
+** `$0` to `$99`: match 0 to 99 in regular expression (0 is the whole match,
+   1 to 99 are groups captured between parentheses)
+** `$+`: the last match (with highest number)
+** `$.*N`: match `N` (can be `+` or `0` to `99`), with all chars replaced by `*`
+   (the `*` char can be any char between space (32) and `~` (126))
+* 'reference_char': the char used for reference to match (commonly '$')
+
+戻り値:
+
+// TRANSLATION MISSING
+* string with text replaced, NULL if problem (must be freed by calling "free"
+  after use)
+
+C 言語での使用例:
+
+[source,C]
+----
+regex_t my_regex;
+char *string;
+if (weechat_string_regcomp (&my_regex, "([0-9]{4})-([0-9]{2})-([0-9]{2})",
+                            REG_EXTENDED) == 0)
+{
+    string = weechat_string_replace_regex ("date: 2014-02-14", &my_regex,
+                                           "$3/$2/$1", '$');
+    /* string == "date: 14/02/2014" */
+    if (string)
+        free (string);
+    regfree (&my_regex);
+}
+----
+
+[NOTE]
+スクリプト API ではこの関数を利用できません。
+
 ==== weechat_string_split
 
 1 つ以上の区切り文字に従って文字列を分割。