Plugin API
Strings 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.
weechat_charset_set Prototype: void weechat_charset_set (const char *charset) Set new plugin charset. Arguments: : new charset to use Example: weechat_charset_set (plugin, "iso-8859-1");
weechat_iconv_to_internal Prototype: void weechat_iconv_to_internal (const char *charset, const char *string) Convert string to WeeChat internal charset (UTF-8). Arguments: : charset to convert : 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: é à");
weechat_iconv_from_internal Prototype: void weechat_iconv_from_internal (const char *charset, const char *string) Convert string from internal WeeChat charset (UTF-8) to another. Arguments: : target charset : 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: é à");
weechat_gettext Prototype: char *weechat_gettext (const char *string) Return translated string (depends on local language). Arguments: : string to translate Return value: translated string. Example: char *str = weechat_gettext ("hello !");
weechat_ngettext Prototype: char *weechat_ngettext (const char *string, const char *plural, int count) Return translated string, using single or plural form, according to count. Arguments: : string to translate (single form) : string to translate (plural form) : used to choose between single and plural form Return value: translated string. Example: char *str = weechat_ngettext ("file", "files", num_files);
weechat_strndup Prototype: char *weechat_strndup (const char *string, int length) Return duplicated string, with max "length" chars. Arguments: : string to duplicate : 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" */
weechat_string_tolower Prototype: char *weechat_string_tolower (const char *string) Convert UTF-8 string to lower case. Arguments: : string to convert Return value: none. Example: weechat_string_tolower ("AbCdEé"); /* result: "abcdeé" */
weechat_string_toupper Prototype: char *weechat_string_toupper (const char *string) Convert UTF-8 string to upper case. Arguments: : string to convert Return value: none. Example: weechat_string_toupper ("AbCdEé"); /* result: "ABCDEé" */
weechat_strcasecmp Prototype: int weechat_strcasecmp (const char *string1, const char *string2) Locale and case independent string comparison. Arguments: : first string for comparison : 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 */
weechat_strncasecmp Prototype: int weechat_strncasecmp (const char *string1, const char *string2, int max) Locale and case independent string comparison, for "max" chars. Arguments: : first string for comparison : second string for comparison : 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 */
weechat_strcmp_ignore_chars 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: : first string for comparison : second string for comparison : string with chars to ignore : 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 */
weechat_strcasestr Prototype: int weechat_strcasestr (const char *string, const char *search) Locale and case independent string search. Arguments: : string : 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" */
weechat_string_match 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 : mask : 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 */
weechat_string_replace 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 to 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" */
weechat_string_remove_quotes 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 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" */
weechat_string_strip 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 : strip left chars if different from 0 : strip right chars if different from 0 : 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 */
weechat_string_has_highlight 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 : 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")) ...
weechat_string_explode 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 to explode : delimiters used for explosion : if different from 0, then each argument will contain all string until end of line (see example below) : maximum number of items created (0 = no limit) : 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);
weechat_string_free_exploded Prototype: void weechat_string_free_exploded (char **exploded_string) Free memory used by a string explosion. Arguments: : 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);
weechat_string_build_with_exploded Prototype: char **weechat_string_build_with_exploded (char **exploded_string, const char *separator) Build a string with exploded string. Arguments: : string exploded by "weechat_string_explode" function : 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" */
weechat_string_split_command 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 to split : 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", ';');
weechat_string_free_splitted_command Prototype: void weechat_string_free_splitted_command (char **splitted_command) Free memory used by a splitted command. Arguments: : 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);
UTF-8 Some UTF-8 string functions.
weechat_utf8_has_8bits Prototype: int weechat_utf8_has_8bits (const char *string) Check if a string has 8-bits chars. Arguments: : string Return value: 1 if string has 8-buts chars, 0 if only 7-bits chars. Example: if (weechat_utf8_has_8bits (string)) ...
weechat_utf8_is_valid Prototype: int weechat_utf8_is_valid (const char *string, char **error) Check if a string is UTF-8 valid. Arguments: : string : 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)) ...
weechat_utf8_normalize 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 : replacement char for non UTF-8 chars Return value: none. Example: weechat_utf8_normalize (string, '?');
weechat_utf8_prev_char Prototype: char *weechat_utf8_prev_char (const char *string_start, const char *string) Return previous UTF-8 char in a string. Arguments: : start of string (function will not return a char before this pointer) : 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);
weechat_utf8_next_char Prototype: char *weechat_utf8_next_char (const char *string) Return next UTF-8 char in a string. Arguments: : 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);
weechat_utf8_char_size Prototype: int weechat_utf8_char_size (const char *string) Return UTF-8 char size (in bytes). Arguments: : string Return value: UTF-8 char size (in bytes). Example: int char_size = weechat_utf8_char_size ("être"); /* == 2 */
weechat_utf8_strlen Prototype: int weechat_utf8_strlen (const char *string) Return UTF-8 string length (multi-byte char is considered as 1 char). Arguments: : string Return value: UTF-8 string length (number of real chars). Example: int length = weechat_utf8_strlen ("chêne"); /* == 5 */
weechat_utf8_strnlen 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 : max bytes in string Return value: UTF-8 string length (number of real chars). Example: int length = weechat_utf8_strnlen ("chêne", 4); /* == 3 */
weechat_utf8_strlen_screen Prototype: int weechat_utf8_strlen_screen (const char *string) Return number of chars needed on screen to display UTF-8 string. Arguments: : string Return value: number of chars needed on screen to display UTF-8 string. Example: int length_on_screen = weechat_utf8_strlen_screen ("东"); /* == 2 */
weechat_utf8_charcasecmp Prototype: int weechat_utf8_charcasecmp (const char *string1, const char *string2) Compare two UTF-8 chars (case is ignored). Arguments: : first string for comparison : 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) ...
weechat_utf8_char_size_screen Prototype: int weechat_utf8_char_size_screen (const char *string) Return number of chars needed on screen to display UTF-8 char. Arguments: : 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)
weechat_utf8_add_offset Prototype: char *weechat_utf8_add_offset (const char *string, int offset) Move forward N chars in an UTF-8 string. Arguments: : string : 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" */
weechat_utf8_real_pos Prototype: char *weechat_utf8_real_pos (const char *string, int pos) Get real position in UTF-8 string. Arguments: : string : 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 */
weechat_utf8_pos Prototype: char *weechat_utf8_pos (const char *string, int real_pos) Get position in UTF-8 string. Arguments: : string : 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 */
Directories Some functions related to directories.
weechat_mkdir_home Prototype: int weechat_mkdir_home (char *directory, int mode) Create a directory in WeeChat home. Arguments: : directory to create : mode for new directory Return value: 1 if directory was successfully created, 0 if an error occurred. Example: if (!weechat_mkdir_home ("temp")) ...
weechat_mkdir Prototype: int weechat_mkdir (char *directory, int mode) Create a directory. Arguments: : directory to create : mode for new directory Return value: 1 if directory was successfully created, 0 if an error occurred. Example: if (!weechat_mkdir ("/tmp/mydir")) ...
weechat_exec_on_files 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 for searching files : pointer given to callback when calling it found : 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);
Util Some useful functions.
weechat_timeval_cmp Prototype: int weechat_timeval_cmp (struct timeval *tv1, struct timeval *tv2) Compare 2 timeval structures. Arguments: : first timeval structure : 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) ...
weechat_timeval_diff Prototype: long weechat_timeval_diff (struct timeval *tv1, struct timeval *tv2) Return difference (in milliseconds) between 2 timeval structures. Arguments: : first timeval structure : second timeval structure Return value: difference in milliseconds. Example: long diff = weechat_timeval_diff (&tv1, &tv2);
weechat_timeval_add Prototype: void weechat_timeval_add (struct timeval *tv, long interval) Add interval (in milliseconds) to a timeval structure. Arguments: : timeval structure : interval (in milliseconds) Return value: none. Example: weechat_timeval_add (&tv, 2000); /* add 2 seconds */
To be continued...