summaryrefslogtreecommitdiff
path: root/doc/en/weechat_plugin_api.en.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/en/weechat_plugin_api.en.adoc')
-rw-r--r--doc/en/weechat_plugin_api.en.adoc61
1 files changed, 52 insertions, 9 deletions
diff --git a/doc/en/weechat_plugin_api.en.adoc b/doc/en/weechat_plugin_api.en.adoc
index edc10be7c..9301fb376 100644
--- a/doc/en/weechat_plugin_api.en.adoc
+++ b/doc/en/weechat_plugin_api.en.adoc
@@ -1483,6 +1483,8 @@ This function is not available in scripting API.
==== string_split
+_Updated in 2.5._
+
Split a string according to one or more delimiter(s).
Prototype:
@@ -1490,22 +1492,38 @@ Prototype:
[source,C]
----
char **weechat_string_split (const char *string, const char *separators,
- int keep_eol, int num_items_max,
- int *num_items);
+ int flags, int num_items_max, int *num_items);
----
Arguments:
* _string_: string to split
* _separators_: delimiters used for split
-* _keep_eol_:
-** 0: each string will contain one word
-** 1: each string will contain all string until end of line (see example below)
-** 2: same as 1, but do not remove separators at end of string before split
- _(WeeChat ≥ 0.3.6)_
+* _flags_: combination values to change the default behavior; if the value is 0,
+ the default behavior is used (no strip of separators at beginning/end of string,
+ multiple separators are kept as-is so empty strings can be returned);
+ the following flags are accepted:
+** WEECHAT_STRING_SPLIT_STRIP_LEFT: strip separators on the left
+ (beginning of string)
+** WEECHAT_STRING_SPLIT_STRIP_RIGHT: strip separators on the right
+ (end of string)
+** WEECHAT_STRING_SPLIT_COLLAPSE_SEPS: collapse multiple consecutive separators
+ into a single one
+** WEECHAT_STRING_SPLIT_KEEP_EOL: keep end of line for each value
* _num_items_max_: maximum number of items created (0 = no limit)
* _num_items_: pointer to int which will contain number of items created
+[NOTE]
+With WeeChat ≤ 2.4, the _flags_ argument was called _keep_eol_ and took other
+values, which must be converted like that:
+[width="100%",cols="1,10",options="header"]
+|===
+| keep_eol | flags
+| 0 | WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_STRIP_RIGHT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
+| 1 | WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_STRIP_RIGHT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS \| WEECHAT_STRING_SPLIT_KEEP_EOL
+| 2 | WEECHAT_STRING_SPLIT_STRIP_LEFT \| WEECHAT_STRING_SPLIT_COLLAPSE_SEPS \| WEECHAT_STRING_SPLIT_KEEP_EOL
+|===
+
Return value:
* array of strings, NULL if problem (must be freed by calling
@@ -1517,16 +1535,37 @@ C example:
----
char **argv;
int argc;
+
argv = weechat_string_split ("abc de fghi ", " ", 0, 0, &argc);
/* result: argv[0] == "abc"
argv[1] == "de"
+ argv[2] == ""
+ argv[3] == "fghi"
+ argv[4] = ""
+ argv[5] == NULL
+ argc == 5
+*/
+weechat_string_free_split (argv);
+
+argv = weechat_string_split ("abc de fghi ", " ",
+ WEECHAT_STRING_SPLIT_STRIP_LEFT
+ | WEECHAT_STRING_SPLIT_STRIP_RIGHT
+ | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS,
+ 0, &argc);
+/* result: argv[0] == "abc"
+ argv[1] == "de"
argv[2] == "fghi"
argv[3] == NULL
argc == 3
*/
weechat_string_free_split (argv);
-argv = weechat_string_split ("abc de fghi ", " ", 1, 0, &argc);
+argv = weechat_string_split ("abc de fghi ", " ",
+ WEECHAT_STRING_SPLIT_STRIP_LEFT
+ | WEECHAT_STRING_SPLIT_STRIP_RIGHT
+ | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
+ | WEECHAT_STRING_SPLIT_KEEP_EOL,
+ 0, &argc);
/* result: argv[0] == "abc de fghi"
argv[1] == "de fghi"
argv[2] == "fghi"
@@ -1535,7 +1574,11 @@ argv = weechat_string_split ("abc de fghi ", " ", 1, 0, &argc);
*/
weechat_string_free_split (argv);
-argv = weechat_string_split ("abc de fghi ", " ", 2, 0, &argc);
+argv = weechat_string_split ("abc de fghi ", " ",
+ WEECHAT_STRING_SPLIT_STRIP_LEFT
+ | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
+ | WEECHAT_STRING_SPLIT_KEEP_EOL,
+ 0, &argc);
/* result: argv[0] == "abc de fghi "
argv[1] == "de fghi "
argv[2] == "fghi "