# 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:

- `charset`: 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`: 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: é à");

### 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:

- `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: é à");

### weechat_gettext

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 !");

### 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:

- `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);

### weechat_strndup

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" */

### weechat_string_tolower

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é" */

### weechat_string_toupper

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é" */

### weechat_strcasecmp

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 */

### weechat_strncasecmp

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 */

### 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:

- `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 */

### weechat_strcasestr

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" */

### 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`: 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 */

### 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

- `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" */

### 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

- `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" */

### 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`: 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 */

### 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`: 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")) ...

### 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`: 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);

### weechat_string_free_exploded

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);

### 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:

- `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" */

### 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`: 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", ';');

### weechat_string_free_splitted_command

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);

## 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`: 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`: 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)) ...

### 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`: string

- `replacement`: 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:

- `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);

### weechat_utf8_next_char

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);

### weechat_utf8_char_size

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 */

### 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`: 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`: 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 */

### 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`: 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:

- `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) ...

### 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`: 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`: 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" */

### weechat_utf8_real_pos

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 */

### weechat_utf8_pos

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 */

## 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`: 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")) ...

### weechat_mkdir

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")) ...

### 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`: 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);

## Util

Some useful functions.

### weechat_timeval_cmp

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) ...

### weechat_timeval_diff

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);

### weechat_timeval_add

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...