WeeChat plugin API reference

int weechat_plugin_init (struct t_weechat_plugin *plugin,
                         int argc, char *argv[]);

int weechat_plugin_end (struct t_weechat_plugin *plugin);

# prototype
def register(name: str, author: str, version: str, license: str, description: str, shutdown_function: str, charset: str) -> int: ...

const char *weechat_plugin_get_name (struct t_weechat_plugin *plugin);

const char *name = weechat_plugin_get_name (plugin);

# prototype
def plugin_get_name(plugin: str) -> str: ...

# example
plugin = weechat.buffer_get_pointer(weechat.current_buffer(), "plugin")
name = weechat.plugin_get_name(plugin)

void weechat_charset_set (const char *charset);

weechat_charset_set ("iso-8859-1");

# prototype
def charset_set(charset: str) -> int: ...

# example
weechat.charset_set("iso-8859-1")

char *weechat_iconv_to_internal (const char *charset, const char *string);

char *str = weechat_iconv_to_internal ("iso-8859-1", "iso string: é à");
/* ... */
free (str);

# prototype
def iconv_to_internal(charset: str, string: str) -> str: ...

# example
str = weechat.iconv_to_internal("iso-8859-1", "iso string: é à")

char *weechat_iconv_from_internal (const char *charset, const char *string);

char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à");
/* ... */
free (str);

# prototype
def iconv_from_internal(charset: str, string: str) -> str: ...

# example
str = weechat.iconv_from_internal("iso-8859-1", "utf-8 string: é à")

const char *weechat_gettext (const char *string);

char *str = weechat_gettext ("hello");

# prototype
def gettext(string: str) -> str: ...

# example
str = weechat.gettext("hello")

const char *weechat_ngettext (const char *string, const char *plural,
                              int count);

char *str = weechat_ngettext ("file", "files", num_files);

# prototype
def ngettext(string: str, plural: str, count: int) -> str: ...

# example
num_files = 2
str = weechat.ngettext("file", "files", num_files)

char *weechat_strndup (const char *string, int bytes);

char *str = weechat_strndup ("abcdef", 3);  /* result: "abc" */
/* ... */
free (str);

char *weechat_string_cut (const char *string, int length, int count_suffix, int screen, const char *cut_suffix);

char *str = weechat_string_cut ("this is a test", 5, 1, 1, "…");  /* result: "this…" */
/* ... */
free (str);

char *weechat_string_tolower (const char *string);

char *str = weechat_string_tolower ("ABCD_É");  /* result: "abcd_é" */
/* ... */
free (str);

char *weechat_string_toupper (const char *string);

char *str = weechat_string_toupper ("abcd_é");  /* result: "ABCD_É" */
/* ... */
free (str);

int weechat_string_charcmp (const char *string1, const char *string2);

int diff = weechat_string_charcmp ("aaa", "ccc");  /* == -2 */

int weechat_string_charcasecmp (const char *string1, const char *string2);

int diff = weechat_string_charcasecmp ("aaa", "CCC");  /* == -2 */

int weechat_strcmp (const char *string1, const char *string2);

int diff = weechat_strcmp ("aaa", "ccc");  /* == -2 */

int weechat_strncmp (const char *string1, const char *string2, int max);

int diff = weechat_strncmp ("aabb", "aacc", 2);  /* == 0 */

int weechat_strcasecmp (const char *string1, const char *string2);

int diff;
diff = weechat_strcasecmp ("aaa", "CCC");    /* == -2 */
diff = weechat_strcasecmp ("noël", "NOËL");  /* == 0  */

int weechat_strcasecmp_range (const char *string1, const char *string2, int range);

int diff = weechat_strcasecmp_range ("nick{away}", "NICK[away]", 29);  /* == 0 */

int weechat_strncasecmp (const char *string1, const char *string2, int max);

int diff = weechat_strncasecmp ("aabb", "AACC", 2);  /* == 0 */

int weechat_strncasecmp_range (const char *string1, const char *string2, int max, int range);

int diff = weechat_strncasecmp_range ("nick{away}", "NICK[away]", 6, 29);  /* == 0 */

int weechat_strcmp_ignore_chars (const char *string1, const char *string2,
                                 const char *chars_ignored,
                                 int case_sensitive);

int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1);  /* == -3 */

const char *weechat_strcasestr (const char *string, const char *search);

const char *pos = weechat_strcasestr ("aBcDeF", "de");  /* result: pointer to "DeF" */

int weechat_strlen_screen (const char *string);

int length_on_screen = weechat_strlen_screen ("é");  /* == 1 */

# prototype
def strlen_screen(string: str) -> int: ...

# example
length = weechat.strlen_screen("é")  # 1

int weechat_string_match (const char *string, const char *mask,
                          int case_sensitive);

int match1 = weechat_string_match ("abcdef", "abc*", 0);   /* == 1 */
int match2 = weechat_string_match ("abcdef", "*dd*", 0);   /* == 0 */
int match3 = weechat_string_match ("abcdef", "*def", 0);   /* == 1 */
int match4 = weechat_string_match ("abcdef", "*de*", 0);   /* == 1 */
int match5 = weechat_string_match ("abcdef", "*b*d*", 0);  /* == 1 */

# prototype
def string_match(string: str, mask: str, case_sensitive: int) -> int: ...

# examples
match1 = weechat.string_match("abcdef", "abc*", 0)   # == 1
match2 = weechat.string_match("abcdef", "*dd*", 0)   # == 0
match3 = weechat.string_match("abcdef", "*def", 0)   # == 1
match4 = weechat.string_match("abcdef", "*de*", 0)   # == 1
match5 = weechat.string_match("abcdef", "*b*d*", 0)  # == 1

int weechat_string_match_list (const char *string, const char **masks,
                               int case_sensitive);

const char *masks[3] = { "*", "!abc*", NULL };
int match1 = weechat_string_match_list ("abc", masks, 0);     /* == 0 */
int match2 = weechat_string_match_list ("abcdef", masks, 0);  /* == 0 */
int match3 = weechat_string_match_list ("def", masks, 0);     /* == 1 */

# prototype
def string_match_list(string: str, masks: str, case_sensitive: int) -> int: ...

# examples
match1 = weechat.string_match("abc", "*,!abc*", 0)     # == 0
match2 = weechat.string_match("abcdef", "*,!abc*", 0)  # == 0
match3 = weechat.string_match("def", "*,!abc*", 0)     # == 1

char *weechat_string_expand_home (const char *path);

char *str = weechat_string_expand_home ("~/file.txt");
/* result: "/home/user/file.txt" */
/* ... */
free (str);

char *weechat_string_eval_path_home (const char *path,
                                     struct t_hashtable *pointers,
                                     struct t_hashtable *extra_vars,
                                     struct t_hashtable *options);

char *str = weechat_string_eval_path_home ("${weechat_config_dir}/test.conf", NULL, NULL, NULL);
/* result: "/home/user/.config/weechat/test.conf" */
/* ... */
free (str);

# prototype
def string_eval_path_home(path: str, pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str]) -> str: ...

# example
path = weechat.string_eval_path_home("${weechat_config_dir}/test.conf", {}, {}, {})
# path == "/home/user/.config/weechat/test.conf"

char *weechat_string_remove_quotes (const char *string, const char *quotes);

char *str = weechat_string_remove_quotes (string, " 'I can't' ", "'");
/* result: "I can't" */
/* ... */
free (str);

char *weechat_string_strip (const char *string, int left, int right,
                            const char *chars);

char *str = weechat_string_strip (".abc -", 0, 1, "- .");  /* result: ".abc" */
/* ... */
free (str);

char *weechat_string_convert_escaped_chars (const char *string);

char *str = weechat_string_convert_escaped_chars ("snowman: \\u2603");
/* str == "snowman: ☃" */
/* ... */
free (str);

char *weechat_string_mask_to_regex (const char *mask);

char *str_regex = weechat_string_mask_to_regex ("test*mask");
/* result: "test.*mask" */
/* ... */
free (str_regex);

# prototype
def string_mask_to_regex(mask: str) -> str: ...

# example
regex = weechat.string_mask_to_regex("test*mask")  # "test.*mask"

const char *weechat_string_regex_flags (const char *regex, int default_flags, int *flags)

const char *regex = "(?i)test";
int flags;
const char *ptr_regex = weechat_string_regex_flags (regex, REG_EXTENDED, &flags);
/* ptr_regex == "test", flags == REG_EXTENDED | REG_ICASE */

int weechat_string_regcomp (void *preg, const char *regex, int default_flags)

regex_t my_regex;
if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) == 0)
{
    /* OK */
    /* ... */
    regfree (&my_regex);
}
else
{
    /* error */
    /* ... */
}

int weechat_string_has_highlight (const char *string,
                                  const char highlight_words);

int hl = weechat_string_has_highlight ("my test string", "test,word2");  /* == 1 */

# prototype
def string_has_highlight(string: str, highlight_words: str) -> int: ...

# example
highlight = weechat.string_has_highlight("my test string", "test,word2")  # 1

int weechat_string_has_highlight_regex (const char *string, const char *regex);

int hl = weechat_string_has_highlight_regex ("my test string", "test|word2");  /* == 1 */

# prototype
def string_has_highlight_regex(string: str, regex: str) -> int: ...

# example
highlight = weechat.string_has_highlight_regex("my test string", "test|word2")  # 1

char *weechat_string_replace (const char *string, const char *search,
                              const char *replace);

char *str = weechat_string_replace ("test", "s", "x");  /* result: "text" */
/* ... */
free (str);

char *weechat_string_replace_regex (const char *string, void *regex,
                                    const char *replace, const char reference_char,
                                    char *(*callback)(void *data, const char *text),
                                    void *callback_data);

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", '$', NULL, NULL);
    /* string == "date: 14/02/2014" */
    if (string)
        free (string);
    regfree (&my_regex);
}

char *string_translate_chars (const char *string, const char *chars1, const char *chars2);

/* "test" => "tEst" */
char *str = weechat_string_translate_chars ("test", "abcdef", "ABCDEF");

/* "clean the boat" => "CleAn the BoAt" */
char *str = weechat_string_translate_chars ("clean the boat", "abc", "ABC");

char **weechat_string_split (const char *string, const char *separators,
                             const char *strip_items, int flags,
                             int num_items_max, int *num_items);

char **argv;
int argc;

argv = weechat_string_split ("abc de  fghi ", " ", NULL, 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 ", " ", NULL,
                             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 ", " ", NULL,
                             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"
           argv[3] == NULL
           argc == 3
*/
weechat_string_free_split (argv);

argv = weechat_string_split ("abc de  fghi ", " ", NULL,
                             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 "
           argv[3] == NULL
           argc == 3
*/
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);

char **weechat_string_split_shell (const char *string, int *num_items);

char **argv;
int argc;
argv = weechat_string_split_shell ("test 'first arg'  \"second arg\"", &argc);
/* result: argv[0] == "test"
           argv[1] == "first arg"
           argv[2] == "second arg"
           argv[3] == NULL
           argc == 3
*/
weechat_string_free_split (argv);

void weechat_string_free_split (char **split_string);

char *argv;
int argc;
argv = weechat_string_split (string, " ", 0, 0, &argc);
/* ... */
weechat_string_free_split (argv);

char *weechat_string_rebuild_split_string (char **split_string,
                                           const char *separator,
                                           int index_start, int index_end);

char **argv;
int argc;
argv = weechat_string_split ("abc def ghi", " ", 0, 0, &argc);
char *str = weechat_string_rebuild_split_string (argv, ";", 0, -1);
/* str == "abc;def;ghi" */
/* ... */
free (str);

char **weechat_string_split_command (const char *command, char separator);

char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* result: argv[0] == "/command1 arg"
           argv[1] == "/command2"
           argv[2] == NULL
*/
weechat_free_split_command (argv);

void weechat_string_free_split_command (char **split_command);

char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* ... */
weechat_free_split_command (argv);

char *weechat_string_format_size (unsigned long long size);

/* examples with English locale */

char *str = weechat_string_format_size (0);  /* str == "0 bytes" */
/* ... */
free (str);

char *str = weechat_string_format_size (1);  /* str == "1 byte" */
/* ... */
free (str);

char *str = weechat_string_format_size (200);  /* str == "200 bytes" */
/* ... */
free (str);

char *str = weechat_string_format_size (15200);  /* str == "15.2 KB" */
/* ... */
free (str);

char *str = weechat_string_format_size (2097152);  /* str == "2.10 MB" */
/* ... */
free (str);

# prototype
def string_format_size(size: int) -> str: ...

# example
str = weechat.string_format_size(15200)  # == "15.2 KB"

unsigned long long weechat_string_parse_size (const char *size);

unsigned long long size = weechat_parse_size ("1.34m");  /* size == 1340000 */

# prototype
def string_parse_size(size: str) -> int: ...

# example
size = weechat.string_parse_size("1.34m")  # 1340000

int weechat_string_color_code_size (const char *string);

int size;

size = weechat_string_color_code_size ("test");  /* size == 0 */
size = weechat_string_color_code_size (weechat_color ("bold"));  /* size == 2 */
size = weechat_string_color_code_size (weechat_color ("yellow,red"));  /* size == 7 */

# prototype
def string_color_code_size(string: str) -> int: ...

# examples
size = weechat.string_color_code_size("test")  # size == 0
size = weechat.string_color_code_size(weechat.color("bold"))  # size == 2
size = weechat.string_color_code_size(weechat.color("yellow,red"))  # size == 7

char *weechat_string_remove_color (const char *string,
                                   const char *replacement);

/* remove color codes */
char *str = weechat_string_remove_color (my_string1, NULL);
/* ... */
free (str);

/* replace color codes by "?" */
char *str = weechat_string_remove_color (my_string2, "?");
/* ... */
free (str);

# prototype
def string_remove_color(string: str, replacement: str) -> str: ...

# example
str = weechat.string_remove_color(my_string, "?")

int weechat_string_base_encode (int base, const char *from, int length, char *to);

char *string = "abcdefgh", result[128];
int length;
length = weechat_string_base_encode (16, string, strlen (string), result);
/* length == 16, result == "6162636465666768" */
length = weechat_string_base_encode (32, string, strlen (string), result);
/* length == 16, result == "MFRGGZDFMZTWQ===" */
length = weechat_string_base_encode (64, string, strlen (string), result);
/* length == 12, result == "YWJjZGVmZ2g=" */

int weechat_string_base_decode (int base, const char *from, char *to);

char result[128];
int length;
length = weechat_string_base_decode (16, "6162636465666768", result);
/* length == 8, result == "abcdefgh" */
length = weechat_string_base_decode (32, "MFRGGZDFMZTWQ===", result);
/* length == 8, result == "abcdefgh" */
length = weechat_string_base_decode (64, "YWJjZGVmZ2g=", result);
/* length == 8, result == "abcdefgh" */

char *string_hex_dump (const char *data, int data_size, int bytes_per_line,
                       const char *prefix, const char *suffix);

char *string = "abc def-ghi";
char *dump = weechat_string_hex_dump (string, strlen (string), 8, " >> ", NULL);
/* dump == " >> 61 62 63 20 64 65 66 2D   a b c   d e f - \n"
           " >> 67 68 69                  g h i           "  */

int weechat_string_is_command_char (const char *string);

int command_char1 = weechat_string_is_command_char ("/test");  /* == 1 */
int command_char2 = weechat_string_is_command_char ("test");   /* == 0 */

# prototype
def string_is_command_char(string: str) -> int: ...

# examples
command_char1 = weechat.string_is_command_char("/test")  # == 1
command_char2 = weechat.string_is_command_char("test")   # == 0

const char *weechat_string_input_for_buffer (const char *string);

const char *str1 = weechat_string_input_for_buffer ("test");    /* "test"  */
const char *str2 = weechat_string_input_for_buffer ("/test");   /* NULL    */
const char *str3 = weechat_string_input_for_buffer ("//test");  /* "/test" */

# prototype
def string_input_for_buffer(string: str) -> str: ...

# examples
str1 = weechat.string_input_for_buffer("test")    # "test"
str2 = weechat.string_input_for_buffer("/test")   # ""
str3 = weechat.string_input_for_buffer("//test")  # "/test"

char *weechat_string_eval_expression (const char *expr,
                                      struct t_hashtable *pointers,
                                      struct t_hashtable *extra_vars,
                                      struct t_hashtable *options);

/* conditions */
struct t_hashtable *options1 = weechat_hashtable_new (8,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      NULL,
                                                      NULL);
weechat_hashtable_set (options1, "type", "condition");
char *str1 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options1);  /* "1" */
char *str2 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options1);                 /* "0" */

/* simple expression */
char *str3 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);  /* "core.weechat" */

/* replace with regex */
struct t_hashtable *options2 = weechat_hashtable_new (8,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      NULL,
                                                      NULL);
/* add brackets around URLs */
weechat_hashtable_set (options2, "regex", "[a-zA-Z0-9_]+://[^ ]+");
weechat_hashtable_set (options2, "regex_replace", "[ ${re:0} ]");
char *str4 = weechat_string_eval_expression ("test: https://weechat.org", NULL, NULL, NULL);  /* "test: [ https://weechat.org ]" */

/* hide passwords */
weechat_hashtable_set (options2, "regex", "(password=)([^ ]+)");
weechat_hashtable_set (options2, "regex_replace", "${re:1}${hide:*,${re:2}}");
char *str5 = weechat_string_eval_expression ("password=abc password=def", NULL, NULL, NULL);  /* "password=*** password=***" */

# prototype
def string_eval_expression(expr: str, pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str]) -> str: ...

# examples

# conditions
str1 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
str2 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"

# simple expression
str3 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {}) # "core.weechat"

# replace with regex: add brackets around URLs
options = {
    "regex": "[a-zA-Z0-9_]+://[^ ]+",
    "regex_replace": "[ ${re:0} ]",
}
str4 = weechat.string_eval_expression("test: https://weechat.org", {}, {}, options)  # "test: [ https://weechat.org ]"

# replace with regex: hide passwords
options = {
    "regex": "(password=)([^ ]+)",
    "regex_replace": "${re:1}${hide:*,${re:2}}",
}
str5 = weechat.string_eval_expression("password=abc password=def", {}, {}, options)  # "password=*** password=***"

char **weechat_string_dyn_alloc (int size_alloc);

char **string = weechat_string_dyn_alloc (256);

int weechat_string_dyn_copy (char **string, const char *new_string);

char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_copy (string, "test"))
{
    /* OK */
}
else
{
    /* error */
}

int weechat_string_dyn_concat (char **string, const char *add, int bytes);

char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_copy (string, "test"))
{
    if (weechat_string_dyn_concat (string, "abc", -1))
    {
        /* ... */
    }
}

char *weechat_string_dyn_free (char **string, int free_string);

char **string = weechat_string_dyn_alloc (256);
if (weechat_string_dyn_concat (string, "test"))
{
    /* OK */
}
else
{
    /* error */
}
/* ... */
weechat_string_dyn_free (string, 1);

const char *weechat_string_concat (const char *separator, ...);

const char *result = weechat_string_concat (" / ", "abc", "def", "ghi", NULL);  /* result == "abc / def / ghi" */

/* with macro */
const char *result = WEECHAT_STR_CONCAT(" / ", "abc", "def", "ghi");  /* result == "abc / def / ghi" */

int weechat_utf8_has_8bits (const char *string);

if (weechat_utf8_has_8bits (string))
{
    /* ... */
}

int weechat_utf8_is_valid (const char *string, int length, char **error);

char *error;
if (weechat_utf8_is_valid (string, -1, &error))
{
    /* ... */
}
else
{
    /* "error" points to first invalid char */
}

void weechat_utf8_normalize (char *string, char replacement);

weechat_utf8_normalize (string, '?');

const char *weechat_utf8_prev_char (const char *string_start,
                                    const char *string);

const char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);

const char *weechat_utf8_next_char (const char *string);

const char *next_char = weechat_utf8_next_char (string);

int weechat_utf8_char_int (const char *string);

int char_int = weechat_utf8_char_int ("être");  /* "ê" as integer */

int weechat_utf8_char_size (const char *string);

int char_size = weechat_utf8_char_size ("être");  /* == 2 */

int weechat_utf8_strlen (const char *string);

int length = weechat_utf8_strlen ("chêne");  /* == 5 */

int weechat_utf8_strnlen (const char *string, int bytes);

int length = weechat_utf8_strnlen ("chêne", 4);  /* == 3 */

int weechat_utf8_strlen_screen (const char *string);

int length_on_screen = weechat_utf8_strlen_screen ("é");  /* == 1 */

int weechat_utf8_char_size_screen (const char *string);

int length_on_screen = weechat_utf8_char_size_screen ("é");  /* == 1 */

const char *weechat_utf8_add_offset (const char *string, int offset);

const char *str = "chêne";
const char *str2 = weechat_utf8_add_offset (str, 3);  /* points to "ne" */

int weechat_utf8_real_pos (const char *string, int pos);

int pos = weechat_utf8_real_pos ("chêne", 3);  /* == 4 */

int weechat_utf8_pos (const char *string, int real_pos);

int pos = weechat_utf8_pos ("chêne", 4);  /* == 3 */

char *weechat_utf8_strndup (const char *string, int length);

char *string = weechat_utf8_strndup ("chêne", 3);  /* returns "chê" */
/* ... */
free (string);

void weechat_utf8_strncpy (char *dest, const char *string, int length);

char dest[256];

weechat_utf8_strncpy (dest, "chêne", 3);  /* copies "chê" to dest */

int weechat_crypto_hash (const void *data, int data_size, const char *hash_algo,
                         void *hash, int *hash_size);

const char *data = "abcdefghijklmnopqrstuvwxyz";
char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hash (data, strlen (data), "sha256", hash, &hash_size);
/* rc == 1, hash_size == 32 and hash is a buffer with:
   71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 */

int weechat_crypto_hash_file (const char *filename, const char *hash_algo,
                              void *hash, int *hash_size);

char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hash_file ("/path/to/file", "sha256", hash, &hash_size);
/* rc == 1, hash_size == 32 and hash is a buffer with:
   71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 */

int weechat_crypto_hash_pbkdf2 (const void *data, int data_size,
                                const char *hash_algo,
                                const void *salt, int salt_size,
                                int iterations,
                                void *hash, int *hash_size);

const char *data = "abcdefghijklmnopqrstuvwxyz";
const char *salt = "12345678901234567890123456789012";  /* 32 bytes */
char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hash_pbkdf2 (data, strlen (data), "sha256", salt, strlen (salt), 100000,
                                 hash, &hash_size);
/* rc == 1, hash_size == 32 and hash is a buffer with:
   99 b3 5e 42 53 d1 a7 a8 49 c1 dc 2c e2 53 c2 b6 6d a1 8b dc 6e 78 a7 06 e0 ef 34 db 0a 7a a2 bb */

int weechat_crypto_hmac (const void *key, int key_size, const void *message, int message_size,
                         int hash_algo, void *hash, int *hash_size);

const char *key = "the key";
const char *message = "the message";
char hash[256 / 8];
int rc, hash_size;
rc = weechat_crypto_hmac (key, strlen (key), message, strlen (message), "sha256", hash, &hash_size);
/* rc == 1, hash_size == 32 and hash is a buffer with:
   47 36 67 02 fc bc b1 97 a4 25 e6 7a b9 52 92 bd 15 9a 66 91 9c fb 94 b0 b4 9a 39 cb c0 24 2d 7b */

int weechat_mkdir_home (char *directory, int mode);

if (!weechat_mkdir_home ("${weechat_cache_dir}/temp", 0755))
{
    /* error */
}

# prototype
def mkdir_home(directory: str, mode: int) -> int: ...

# example
weechat.mkdir_home("${weechat_cache_dir}/temp", 0755)

int weechat_mkdir (char *directory, int mode);

if (!weechat_mkdir ("/tmp/mydir", 0755))
{
    /* error */
}

# prototype
def mkdir(directory: str, mode: int) -> int: ...

# example
weechat.mkdir("/tmp/mydir", 0755)

int weechat_mkdir_parents (char *directory, int mode);

if (!weechat_mkdir_parents ("/tmp/my/dir", 0755))
{
    /* error */
}

# prototype
def mkdir_parents(directory: str, mode: int) -> int: ...

# example
weechat.mkdir_parents("/tmp/my/dir", 0755)

void weechat_exec_on_files (const char *directory,
                            int recurse_subdirs,
                            int hidden_files,
                            void (*callback)(void *data,
                                             const char *filename),
                            void *callback_data);

void callback (void *data, const char *filename)
{
    /* ... */
}
...
weechat_exec_on_files ("/tmp", 0, 0, &callback, NULL);

char *weechat_file_get_content (const char *filename);

char *content;

content = weechat_file_get_content ("/tmp/test.txt");
/* ... */
free (content);

int weechat_file_copy (const char *from, const char *to);

if (weechat_file_copy ("/tmp/test.txt", "/path/to/test2.txt"))
{
    /* OK */
}

int weechat_file_compress (const char *from, const char *to,
                           const char *compressor, int compression_level);

if (weechat_file_compress ("/tmp/test.txt", "/tmp/test.txt.zst", "zstd", 50))
{
    /* OK */
}

int weechat_util_timeval_cmp (struct timeval *tv1, struct timeval *tv2);

if (weechat_util_timeval_cmp (&tv1, &tv2) > 0)
{
    /* tv1 > tv2 */
}

long long weechat_util_timeval_diff (struct timeval *tv1, struct timeval *tv2);

long long diff = weechat_util_timeval_diff (&tv1, &tv2);

void weechat_util_timeval_add (struct timeval *tv, long long interval);

weechat_util_timeval_add (&tv, 2000000);  /* add 2 seconds */

const char *weechat_util_get_time_string (const time_t *date);

time_t date = time (NULL);
weechat_printf (NULL, "date: %s",
                weechat_util_get_time_string (&date));

int weechat_util_strftimeval (char *string, int max, const char *format, struct timeval *tv);

char time[256];
struct timeval tv;
gettimeofday (&tv, NULL);
weechat_util_strftimeval (time, sizeof (time), "%FT%T.%f", &tv);
/* result: 2023-12-26T18:10:04.460509 */

int util_parse_time (const char *datetime, struct timeval *tv);

struct timeval tv;
weechat_util_parse_time ("2023-12-25T10:29:09.456789Z", &tv);  /* == 1 */
/* result: tv.tv_sec == 1703500149, tv.tv_usec = 456789 */

int weechat_util_version_number (const char *version);

version_number = weechat_util_version_number ("0.3.8");      /* == 0x00030800 */
version_number = weechat_util_version_number ("0.3.9-dev");  /* == 0x00030900 */
version_number = weechat_util_version_number ("0.3.9-rc1");  /* == 0x00030900 */
version_number = weechat_util_version_number ("0.3.9");      /* == 0x00030900 */
version_number = weechat_util_version_number ("1.0");        /* == 0x01000000 */
version_number = weechat_util_version_number ("4.0.0");      /* == 0x04000000 */

struct t_weelist *weechat_list_new ();

struct t_weelist *list = weechat_list_new ();

# prototype
def list_new() -> str: ...

# example
list = weechat.list_new()

struct t_weelist_item *weechat_list_add (struct t_weelist *weelist,
                                         const char *data,
                                         const char *where,
                                         void *user_data);

struct t_weelist_item *my_item =
    weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT, NULL);

# prototype
def list_add(list: str, data: str, where: str, user_data: str) -> str: ...

# example
item = weechat.list_add(list, "my data", weechat.WEECHAT_LIST_POS_SORT, "")

struct t_weelist_item *weechat_list_search (struct t_weelist *weelist,
                                            const char *data);

struct t_weelist_item *item = weechat_list_search (list, "my data");

# prototype
def list_search(list: str, data: str) -> str: ...

# example
item = weechat.list_search(list, "my data")

int weechat_list_search_pos (struct t_weelist *weelist,
                             const char *data);

int pos_item = weechat_list_search_pos (list, "my data");

# prototype
def list_search_pos(list: str, data: str) -> int: ...

# example
pos_item = weechat.list_search_pos(list, "my data")

struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist,
                                                const char *data);

struct t_weelist_item *item = weechat_list_casesearch (list, "my data");

# prototype
def list_casesearch(list: str, data: str) -> str: ...

# example
item = weechat.list_casesearch(list, "my data")

int weechat_list_casesearch_pos (struct t_weelist *weelist,
                                 const char *data);

int pos_item = weechat_list_casesearch_pos (list, "my data");

# prototype
def list_casesearch_pos(list: str, data: str) -> int: ...

# example
pos_item = weechat.list_casesearch_pos(list, "my data")

struct t_weelist_item *weechat_list_get (struct t_weelist *weelist,
                                         int position);

struct t_weelist_item *item = weechat_list_get (list, 0);  /* first item */

# prototype
def list_get(list: str, position: int) -> str: ...

# example
item = weechat.list_get(list, 0)

void weechat_list_set (struct t_weelist_item *item, const char *value);

weechat_list_set (item, "new data");

# prototype
def list_set(item: str, value: str) -> int: ...

# example
weechat.list_set(item, "new data")

struct t_weelist_item *weechat_list_next (struct t_weelist_item *item);

struct t_weelist_item *next_item = weechat_list_next (item);

# prototype
def list_next(item: str) -> str: ...

# example
item = weechat.list_next(item)

struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item);

struct t_weelist_item *prev_item = weechat_list_prev (item);

# prototype
def list_prev(item: str) -> str: ...

# example
item = weechat.list_prev(item)

const char *weechat_list_string (struct t_weelist_item *item);

weechat_printf (NULL, "value of item: %s", weechat_list_string (item));

# prototype
def list_string(item: str) -> str: ...

# example
weechat.prnt("", "value of item: %s" % weechat.list_string(item))

void *weechat_list_user_data (struct t_weelist_item *item);

weechat_printf (NULL, "user data of item: 0x%lx", weechat_list_user_data (item));

char *weechat_list_size (struct t_weelist *weelist);

weechat_printf (NULL, "size of list: %d", weechat_list_size (list));

# prototype
def list_size(list: str) -> int: ...

# example
weechat.prnt("", "size of list: %d" % weechat.list_size(list))

void weechat_list_remove (struct t_weelist *weelist,
                          struct t_weelist_item *item);

weechat_list_remove (list, item);

# prototype
def list_remove(list: str, item: str) -> int: ...

# example
weechat.list_remove(list, item)

void weechat_list_remove_all (struct t_weelist *weelist);

weechat_list_remove_all (list);

# prototype
def list_remove_all(list: str) -> int: ...

# example
weechat.list_remove_all(list)

void weechat_list_free (struct t_weelist *weelist);

weechat_list_free (list);

# prototype
def list_free(list: str) -> int: ...

# example
weechat.list_free(list)

struct t_arraylist *weechat_arraylist_new (int initial_size,
                                           int sorted,
                                           int allow_duplicates,
                                           int (*callback_cmp)(void *data,
                                                               struct t_arraylist *arraylist,
                                                               void *pointer1,
                                                               void *pointer2),
                                           void *callback_cmp_data,
                                           void (*callback_free)(void *data,
                                                                 struct t_arraylist *arraylist,
                                                                 void *pointer),
                                           void *callback_free_data);