Many string functions below are already available thru standard C functions, but it's recommended to use functions in this API because they are ok with UTF-8 and locale.

Prototype: void weechat_charset_set (const char *charset) Set new plugin charset. Arguments: charset: new charset to use Example: weechat_charset_set (plugin, "iso-8859-1");

Prototype: void weechat_iconv_to_internal (const char *charset, const char *string) Convert string to WeeChat internal charset (UTF-8). Arguments: charset: charset to convert string: string to convert Return value: converted string. Note: result has to be free by a call to "free" after use. Example: char *str = weechat_iconv_to_internal (plugin, "iso-8859-1", "iso string: é à");

Prototype: void weechat_iconv_from_internal (const char *charset, const char *string) Convert string from internal WeeChat charset (UTF-8) to another. Arguments: charset: target charset string: string to convert Return value: converted string. Note: result has to be free by a call to "free" after use. Example: char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à");

Prototype: char *weechat_gettext (const char *string) Return translated string (depends on local language). Arguments: string: string to translate Return value: translated string. Example: char *str = weechat_gettext ("hello !");

Prototype: char *weechat_ngettext (const char *string, const char *plural, int count) Return translated string, using single or plural form, according to count. Arguments: single: string to translate (single form) plural: string to translate (plural form) count: used to choose between single and plural form Return value: translated string. Example: char *str = weechat_ngettext ("file", "files", num_files);

Prototype: char *weechat_strndup (const char *string, int length) Return duplicated string, with max "length" chars. Arguments: string: string to duplicate length: max chars to duplicate Return value: duplicated string. Note: result has to be free by a call to "free" after use. Example: char *str = weechat_strndup ("abcdef", 3); /* result: "abc" */

Prototype: char *weechat_string_tolower (const char *string) Convert UTF-8 string to lower case. Arguments: string: string to convert Return value: none. Example: weechat_string_tolower ("AbCdEé"); /* result: "abcdeé" */

Prototype: char *weechat_string_toupper (const char *string) Convert UTF-8 string to upper case. Arguments: string: string to convert Return value: none. Example: weechat_string_toupper ("AbCdEé"); /* result: "ABCDEé" */

Prototype: int weechat_strcasecmp (const char *string1, const char *string2) Locale and case independent string comparison. Arguments: string1: first string for comparison string2: second string for comparison Return value: difference between two strings: negative if string1 < string2, zero if string1 == string2, positive if string1 > string2 Example: int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */

Prototype: int weechat_strncasecmp (const char *string1, const char *string2, int max) Locale and case independent string comparison, for "max" chars. Arguments: string1: first string for comparison string2: second string for comparison max: max number of chars for comparison Return value: difference between two strings: negative if string1 < string2, zero if string1 == string2, positive if string1 > string2 Example: int diff = weechat_strncasecmp ("aaa", "CCC", 2); /* == -2 */

Prototype: int weechat_strcmp_ignore_chars (const char *string1, const char *string2, const char *chars_ignored, int case_sensitive) Locale (and optionally case independent) string comparison, ignoring some chars. Arguments: string1: first string for comparison string2: second string for comparison chars_ignored: string with chars to ignore case_sensitive: 1 for case sensitive comparison, 0 otherwise Return value: difference between two strings: negative if string1 < string2, zero if string1 == string2, positive if string1 > string2 Example: int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1); /* == -3 */

Prototype: int weechat_strcasestr (const char *string, const char *search) Locale and case independent string search. Arguments: string: string search: string to search in "string" Return value: pointer to string found, or NULL if not found Example: char *pos = weechat_strcasestr ("aBcDeF", "de"); /* result: pointer to "DeF" */

Prototype: int weechat_string_match (const char *string, const char *mask, int case_sensitive) Check if a string matches a mask. Mask may begin or end with "*" (no other "*" are allowed inside mask). Arguments: string: string mask: mask case_sensitive: 1 for case sensitive search, otherwise 0 Return value: 1 if string matches mask, otherwise 0. Examples: 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 */

Prototype: char *weechat_string_replace (const char *string, const char *search, const char *replace) Replace "search" string by new one in a string. Arguments: string: string search: string to replace replace: replacement for "search" string Return value: string with "search" replaced by "replace". Note: result has to be free by a call to "free" after use. Example: char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */

Prototype: char *weechat_string_remove_quotes (const char *string, const char *quotes) Remove quotes at beginning/end of string (ignore spaces if there are before first quote or after last quote). Arguments: string: string quotes: string with list of quotes Return value: string without quotes at beginning/end. Note: result has to be free by a call to "free" after use. Example: char *str = weechat_string_remove_quotes (string, " 'abc' ", "'"); /* result: "abc" */

Prototype: char *weechat_string_strip (const char *string, int left, int right, const char *chars) Strip chars at beginning and/or end of string. Arguments: string: string left: strip left chars if different from 0 right: strip right chars if different from 0 chars: string with chars to strip Return value: stripped string. Note: result has to be free by a call to "free" after use. Example: char *str = weechat_strip (string, " ", 0, 1); /* remove spaces at end of string */

Prototype: char *weechat_string_has_highlight (const char *string, const char highlight_words) Check if a string has highlights, using list of highlight words. Arguments: string: string highlight_words: list of highlight words, separated by comma Return value: 1 if string has one or more highlights, 0 otherwise. Example: if (weechat_string_has_highlight (string, "word1,word2")) ...

Prototype: char **weechat_string_explode (const char *string, const char *separators, int keep_eol, int num_items_max, int *num_items) Explode a string according to one or more delimiter(s). Arguments: string: string to explode separators: delimiters used for explosion keep_eol: if different from 0, then each argument will contain all string until end of line (see example below) num_items_max: maximum number of items created (0 = no limit) num_items: pointer to int which will contain number of items created Return value: array of strings, NULL if problem. Note: result has to be free by a call to "weechat_string_free_exploded" after use. Examples: char **argv; int argc; argv = weechat_string_explode ("abc de fghi", " ", 0, 0, &argc); /* result: argv[0] == "abc" argv[1] == "de" argv[2] == "fghi" argv[3] == NULL argc == 3 */ weechat_string_free_exploded (argv); argv = weechat_string_explode ("abc de fghi", " ", 1, 0, &argc); /* result: argv[0] == "abc de fghi" argv[1] == "de fghi" argv[2] == "fghi" argv[3] == NULL argc == 3 */ weechat_string_free_exploded (argv);

Prototype: void weechat_string_free_exploded (char **exploded_string) Free memory used by a string explosion. Arguments: exploded_string: string exploded by "weechat_string_explode" function Return value: none. Example: char *argv; int argc; argv = weechat_string_explode (string, " ", 0, 0, &argc); ... weechat_string_free_exploded (, argv);

Prototype: char **weechat_string_build_with_exploded (char **exploded_string, const char *separator) Build a string with exploded string. Arguments: exploded_string: string exploded by "weechat_string_explode" function separator: string used to separate strings Return value: string built with exploded string. Note: result has to be free by a call to "free" after use. Example: char **argv; int argc; argv = weechat_string_explode ("abc def ghi", " ", 0, 0, &argc); char *string = weechat_string_build_with_exploded (argv, ";"); /* string == "abc;def;ghi" */

Prototype: char **weechat_string_split_command (const char *command, char separator) Split a list of commands separated by 'separator' (which can be escaped by '\' in string). Arguments: command: command to split separator: separator Return value: array of strings, NULL if problem. Note: result has to be free by a call to "weechat_string_free_splitted_command" after use. Example: char **argv = weechat_string_split_command ("/command1;/command2", ';');

Prototype: void weechat_string_free_splitted_command (char **splitted_command) Free memory used by a splitted command. Arguments: splitted_command: command splitted by "weechat_string_split_commaand" function Return value: none. Example: char **argv = weechat_string_split_command ("/command1;/command2", ';'); ... weechat_string_free_splitted_command (argv);

Some UTF-8 string functions.

Prototype: int weechat_utf8_has_8bits (const char *string) Check if a string has 8-bits chars. Arguments: string: string Return value: 1 if string has 8-buts chars, 0 if only 7-bits chars. Example: if (weechat_utf8_has_8bits (string)) ...

Prototype: int weechat_utf8_is_valid (const char *string, char **error) Check if a string is UTF-8 valid. Arguments: string: string error: if not NULL, it is set with first non valid UTF-8 char in string, if any Return value: 1 if UTF-8 string is valid, 0 otherwise. Example: char *error; if (weechat_utf8_is_valid (string, &error)) ...

Prototype: void weechat_utf8_normalize (const char *string, char replacement) Normalize UTF-8 string: remove non UTF-8 chars and replace them by a char Arguments: string: string replacement: replacement char for non UTF-8 chars Return value: none. Example: weechat_utf8_normalize (string, '?');

Prototype: char *weechat_utf8_prev_char (const char *string_start, const char *string) Return previous UTF-8 char in a string. Arguments: string_start: start of string (function will not return a char before this pointer) string: pointer to string (must be >= string_start) Return value: pointer to previous UTF-8 char, NULL if not found (start of string reached) Example: char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);

Prototype: char *weechat_utf8_next_char (const char *string) Return next UTF-8 char in a string. Arguments: string: string Return value: pointer to next UTF-8 char, NULL if not found (end of string reached) Example: char *next_char = weechat_utf8_next_char (string);

Prototype: int weechat_utf8_char_size (const char *string) Return UTF-8 char size (in bytes). Arguments: string: string Return value: UTF-8 char size (in bytes). Example: int char_size = weechat_utf8_char_size ("être"); /* == 2 */

Prototype: int weechat_utf8_strlen (const char *string) Return UTF-8 string length (multi-byte char is considered as 1 char). Arguments: string: string Return value: UTF-8 string length (number of real chars). Example: int length = weechat_utf8_strlen ("chêne"); /* == 5 */

Prototype: int weechat_utf8_strnlen (const char *string, int bytes) Return UTF-8 string length (multi-byte char is considered as 1 char), for max bytes in string Arguments: string: string bytes: max bytes in string Return value: UTF-8 string length (number of real chars). Example: int length = weechat_utf8_strnlen ("chêne", 4); /* == 3 */

Prototype: int weechat_utf8_strlen_screen (const char *string) Return number of chars needed on screen to display UTF-8 string. Arguments: string: string Return value: number of chars needed on screen to display UTF-8 string. Example: int length_on_screen = weechat_utf8_strlen_screen ("东"); /* == 2 */

Prototype: int weechat_utf8_charcasecmp (const char *string1, const char *string2) Compare two UTF-8 chars (case is ignored). Arguments: string1: first string for comparison string2: second string for comparison Return value: difference between first char of each string: negative if char1 < char2, zero if char1 == char2, positive if char1 > char2 Example: if (weechat_utf8_charcasecmp (string1, string2) != 0) ...

Prototype: int weechat_utf8_char_size_screen (const char *string) Return number of chars needed on screen to display UTF-8 char. Arguments: string: string Return value: number of chars needed on screen to display UTF-8 char. Example: int length_on_screen = weechat_utf8_char_size_screen (string)

Prototype: char *weechat_utf8_add_offset (const char *string, int offset) Move forward N chars in an UTF-8 string. Arguments: string: string offset: number of chars Return value: pointer to string, N chars after (NULL if it's not reachable). Example: char *ptr = weechat_utf8_add_offset ("chêne", 3); /* points to "ne" */

Prototype: char *weechat_utf8_real_pos (const char *string, int pos) Get real position in UTF-8 string. Arguments: string: string pos: position in chars Return value: real position (in bytes) for "pos" chars in string. Example: int pos = weechat_utf8_real_pos ("chêne", 3); /* == 4 */

Prototype: char *weechat_utf8_pos (const char *string, int real_pos) Get position in UTF-8 string. Arguments: string: string real_pos: position in bytes Return value: position (in chars) for "real_pos" bytes in string. Example: int pos = weechat_utf8_real_pos ("chêne", 4); /* == 3 */

Some functions related to directories.

Prototype: int weechat_mkdir_home (char *directory, int mode) Create a directory in WeeChat home. Arguments: directory: directory to create mode: mode for new directory Return value: 1 if directory was successfully created, 0 if an error occurred. Example: if (!weechat_mkdir_home ("temp")) ...

Prototype: int weechat_mkdir (char *directory, int mode) Create a directory. Arguments: directory: directory to create mode: mode for new directory Return value: 1 if directory was successfully created, 0 if an error occurred. Example: if (!weechat_mkdir ("/tmp/mydir")) ...

Prototype: void weechat_exec_on_files (const char *directory, void *data, int (*callback)(void *data, const char *filename)) Find files in a directory and execute a callback on each file. Arguments: directory: directory for searching files data: pointer given to callback when calling it found callback: function called for each file found Return value: none. Example: int callback (void *data, const char *filename) { /* ... */ return 1; } ... plugin->exec_on_files (plugin, "/tmp", &callback);

Some useful functions.

Prototype: int weechat_timeval_cmp (struct timeval *tv1, struct timeval *tv2) Compare 2 timeval structures. Arguments: tv1: first timeval structure tv2: second timeval structure Return value: -1 if tv1 < char2, zero if tv1 == tv2, +1 if tv1 > tv2 Example: if (weechat_timeval_cmp (&tv1, &tv2) > 0) ...

Prototype: long weechat_timeval_diff (struct timeval *tv1, struct timeval *tv2) Return difference (in milliseconds) between 2 timeval structures. Arguments: tv1: first timeval structure tv2: second timeval structure Return value: difference in milliseconds. Example: long diff = weechat_timeval_diff (&tv1, &tv2);

Prototype: void weechat_timeval_add (struct timeval *tv, long interval) Add interval (in milliseconds) to a timeval structure. Arguments: tv: timeval structure interval: interval (in milliseconds) Return value: none. Example: weechat_timeval_add (&tv, 2000); /* add 2 seconds */

To be continued...