## gimputils

gimputils — Utilities of general interest

## Synopsis

    gchar*      gimp_any_to_utf8                (const gchar *str,
                                                 gssize len,
                                                 const gchar *warning_format,
                                                 ...);
    const gchar* gimp_filename_to_utf8          (const gchar *filename);
    gchar*      gimp_utf8_strtrim               (const gchar *str,
                                                 gint max_chars);
    gchar*      gimp_memsize_to_string          (guint64 memsize);
    gchar*      gimp_strip_uline                (const gchar *str);

## Description

## Details

### gimp_any_to_utf8 ()

    gchar*      gimp_any_to_utf8                (const gchar *str,
                                                 gssize len,
                                                 const gchar *warning_format,
                                                 ...);

This function takes any string (UTF-8 or not) and always returns a valid UTF-8 string.

If `str` is valid UTF-8, a copy of the string is returned.

If UTF-8 validation fails, `g_locale_to_utf8()` is tried and if it succeeds the resulting string is returned.

Otherwise, the portion of `str` that is UTF-8, concatenated with "(invalid UTF-8 string)" is returned. If not even the start of `str` is valid UTF-8, only "(invalid UTF-8 string)" is returned.

`str` : | The string to be converted to UTF-8.
`len` : | The length of the string, or -1 if the string is nul-terminated.
`warning_format` : | The message format for the warning message if conversion to UTF-8 fails. See the ``printf()`` documentation.
`...` : | The parameters to insert into the format string.
Returns : | The UTF-8 string as described above.

### gimp_filename_to_utf8 ()

    const gchar* gimp_filename_to_utf8          (const gchar *filename);

Convert a filename in the filesystem's encoding to UTF-8 temporarily. The return value is a pointer to a string that is guaranteed to be valid only during the current iteration of the main loop or until the next call to `gimp_filename_to_utf8()`.

The only purpose of this function is to provide an easy way to pass a filename in the filesystem encoding to a function that expects an UTF-8 encoded filename.

`filename` : | The filename to be converted to UTF-8.
Returns : | A temporarily valid UTF-8 representation of `filename`. This string must not be changed or freed.

### gimp_utf8_strtrim ()

    gchar*      gimp_utf8_strtrim               (const gchar *str,
                                                 gint max_chars);

Creates a (possibly trimmed) copy of `str`. The string is cut if it exceeds `max_chars` characters or on the first newline. The fact that the string was trimmed is indicated by appending an ellipsis.

`str` : | an UTF-8 encoded string (or `NULL`)
`max_chars` : | the maximum number of characters before the string get trimmed
Returns : | A (possibly trimmed) copy of `str` which should be freed using `g_free()` when it is not needed any longer.

### gimp_memsize_to_string ()

    gchar*      gimp_memsize_to_string          (guint64 memsize);

This function returns a human readable, translated representation of the passed `memsize`. Large values are displayed using a reasonable memsize unit, e.g.: "345" becomes "345 Bytes", "4500" becomes "4.4 KB" and so on.

`memsize` : | A memory size in bytes.
Returns : | A newly allocated human-readable, translated string.

### gimp_strip_uline ()

    gchar*      gimp_strip_uline                (const gchar *str);

This function returns a copy of `str` stripped of underline characters. This comes in handy when needing to strip mnemonics from menu paths etc.

`str` : | Underline infested string (or `NULL`)
Returns : | A (possibly stripped) copy of `str` which should be freed using `g_free()` when it is not needed any longer.