diff options
Diffstat (limited to 'doc/en/weechat_plugin_api.en.adoc')
| -rw-r--r-- | doc/en/weechat_plugin_api.en.adoc | 61 |
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 " |