## translate-util

translate-util — miscellaneous utility functions

## Synopsis

    gboolean    translate_ascii_strcase_equal   (gconstpointer s1,
                                                 gconstpointer s2);
    unsigned int translate_ascii_strcase_hash   (gconstpointer key);
    char*       translate_ascii_strcasestr      (const char *big,
                                                 const char *little);
    char*       translate_ascii_strcasestr_len  (const char *big,
                                                 unsigned int big_len,
                                                 const char *little);
    int         translate_ascii_strcasecoll     (const char *s1,
                                                 const char *s2);
    int         translate_utf8_strcasecoll      (const char *s1,
                                                 const char *s2);
    int         translate_utf8_strcmp           (const char *s1,
                                                 const char *s2);
    int         translate_utf8_strcasecmp       (const char *s1,
                                                 const char *s2);
    char*       translate_utf8_strpbrk          (const char *p,
                                                 gssize len,
                                                 const char *charset);
    char*       translate_utf8_strrpbrk         (const char *p,
                                                 gssize len,
                                                 const char *charset);
    time_t      translate_time                  (void);
    char*       translate_sgml_ref_expand       (const char *str);

## Description

The following functions may come in handy to manipulate ASCII or UTF-8 strings, get the current time, or expand SGML character references and XHTML character entities.

## Details

### translate_ascii_strcase_equal ()

    gboolean    translate_ascii_strcase_equal   (gconstpointer s1,
                                                 gconstpointer s2);

Compares two strings, ignoring the case of ASCII characters of both strings, and returns `TRUE` if they are equal. It can be passed to `g_hash_table_new()` as the `key_equal_func` parameter, when using strings as case-insensitive keys in a GHashTable.

`s1` : | a nul-terminated string.
`s2` : | a nul-terminated string.
Returns : | `TRUE` if the two strings match.

### translate_ascii_strcase_hash ()

    unsigned int translate_ascii_strcase_hash   (gconstpointer key);

Converts a string to a hash value, ignoring the case of ASCII characters of the string. It can be passed to `g_hash_table_new()` as the `hash_func` parameter, when using strings as case-insensitive keys in a GHashTable.

`key` : | a string key.
Returns : | a hash value corresponding to the key.

### translate_ascii_strcasestr ()

    char*       translate_ascii_strcasestr      (const char *big,
                                                 const char *little);

Locates the first occurrence of `little` in `big`, ignoring the case of ASCII characters of both strings.

`big` : | a nul-terminated string, which may not be encoded in UTF-8.
`little` : | the nul-terminated string to search for, which may not be encoded in UTF-8.
Returns : | if `little` is an empty string, `big` is returned; if `little` occurs nowhere in `big`, `NULL` is returned; otherwise a pointer to the first character of the first occurrence of `little` in `big` is returned.

### translate_ascii_strcasestr_len ()

    char*       translate_ascii_strcasestr_len  (const char *big,
                                                 unsigned int big_len,
                                                 const char *little);

Locates the first occurrence of `little` in `big`, ignoring the case of ASCII characters of both strings, and limiting the length of the search to `big_len`.

`big` : | a nul-terminated string, which may not be encoded in UTF-8.
`big_len` : | length of `big` in bytes, or -1 if `big` is nul-terminated.
`little` : | the nul-terminated string to search for, which may not be encoded in UTF-8.
Returns : | if `little` is an empty string, `big` is returned; if `little` occurs nowhere in `big`, `NULL` is returned; otherwise a pointer to the first character of the first occurrence of `little` in `big` is returned.

### translate_ascii_strcasecoll ()

    int         translate_ascii_strcasecoll     (const char *s1,
                                                 const char *s2);

Compares two strings for ordering using the linguistically correct rules for the current locale, ignoring the case of ASCII characters of both strings.

`s1` : | a nul-terminated string, which may not be encoded in UTF-8.
`s2` : | a nul-terminated string, which may not be encoded in UTF-8.
Returns : | an integer greater than, equal to, or less than 0, according as `s1` is greater than, equal to, or less than `s2`.

### translate_utf8_strcasecoll ()

    int         translate_utf8_strcasecoll      (const char *s1,
                                                 const char *s2);

Compares two UTF-8 strings for ordering using the linguistically correct rules for the current locale, ignoring the case of both strings.

`s1` : | a nul-terminated string.
`s2` : | a nul-terminated string.
Returns : | an integer greater than, equal to, or less than 0, according as `s1` is greater than, equal to, or less than `s2`.

### translate_utf8_strcmp ()

    int         translate_utf8_strcmp           (const char *s1,
                                                 const char *s2);

Compares two UTF-8 strings for ordering.

`s1` : | a nul-terminated string.
`s2` : | a nul-terminated string.
Returns : | an integer greater than, equal to, or less than 0, according as `s1` is greater than, equal to, or less than `s2`.

### translate_utf8_strcasecmp ()

    int         translate_utf8_strcasecmp       (const char *s1,
                                                 const char *s2);

Compares two UTF-8 strings for ordering, ignoring the case of both strings.

`s1` : | a nul-terminated string.
`s2` : | a nul-terminated string.
Returns : | an integer greater than, equal to, or less than 0, according as `s1` is greater than, equal to, or less than `s2`.

### translate_utf8_strpbrk ()

    char*       translate_utf8_strpbrk          (const char *p,
                                                 gssize len,
                                                 const char *charset);

Locates in `p` the first occurrence of any character in the string `charset`.

`p` : | a nul-terminated string.
`len` : | length of `p` in bytes, or -1 if `p` is nul-terminated.
`charset` : | the set of characters to search for.
Returns : | the first occurrence of any character of `charset` in `p`, or `NULL` if no characters from `charset` occur anywhere in `p`.

### translate_utf8_strrpbrk ()

    char*       translate_utf8_strrpbrk         (const char *p,
                                                 gssize len,
                                                 const char *charset);

Locates in `p` the last occurrence of any character in the string `charset`.

`p` : | a nul-terminated string.
`len` : | length of `p` in bytes, or -1 if `p` is nul-terminated.
`charset` : | the set of characters to search for.
Returns : | the last occurrence of any character of `charset` in `p`, or `NULL` if no characters from `charset` occur anywhere in `p`.

### translate_time ()

    time_t      translate_time                  (void);

Returns the current time, issuing a warning if an error occurs.

Returns : | the number of seconds since 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time, or 0 if an error has occurred.

### translate_sgml_ref_expand ()

    char*       translate_sgml_ref_expand       (const char *str);

Parses `str`, expanding its SGML character references and XHTML character entities into their Unicode character value.

Numerical SGML character references as well as XHTML entities are supported. Unsupported entities will be inserted verbatim into the result.

`str` : | a nul-terminated string.
Returns : | the expansion of str. The returned string should be freed when no longer needed.