TeplUtils: Tepl 5 Reference Manual

## TeplUtils TeplUtils — Utility functions |

## Functions

gchar * | tepl_utils_str_middle_truncate ()
gchar * | tepl_utils_str_end_truncate ()
gchar * | tepl_utils_str_replace ()
gchar * | tepl_utils_markup_escape_text ()
gchar * | tepl_utils_get_file_extension ()
gchar * | tepl_utils_get_file_shortname ()
gchar * | tepl_utils_replace_home_dir_with_tilde ()
gboolean | tepl_utils_decode_uri ()
gboolean | tepl_utils_create_parent_directories ()
void | tepl_utils_file_query_exists_async ()
gboolean | tepl_utils_file_query_exists_finish ()
GtkWidget * | tepl_utils_create_close_button ()
void | tepl_utils_show_warning_dialog ()
gboolean | tepl_utils_binding_transform_func_smart_bool ()

## Includes

    #include <tepl/tepl.h>

## Description

Utility functions.

## Functions

### tepl_utils_str_middle_truncate ()

    gchar *
    tepl_utils_str_middle_truncate (const gchar *str,
                                    guint truncate_length);

If `str` is longer than `truncate_length` , then this function returns `str` truncated in the middle with a “…” character. Otherwise it just returns a copy of `str` .

#### Parameters

str | a UTF-8 string. |
truncate_length | truncate the string at that length, in UTF-8 characters (not bytes). |

#### Returns

the truncated string. Free with `g_free()`.

Since: 4.4

### tepl_utils_str_end_truncate ()

    gchar *
    tepl_utils_str_end_truncate (const gchar *str,
                                 guint truncate_length);

Like `tepl_utils_str_middle_truncate()` but the “…” character is at the end.

#### Parameters

str | a UTF-8 string. |
truncate_length | truncate the string at that length, in UTF-8 characters (not bytes). |

#### Returns

the truncated string. Free with `g_free()`.

Since: 4.4

### tepl_utils_str_replace ()

    gchar *
    tepl_utils_str_replace (const gchar *string,
                            const gchar *search,
                            const gchar *replacement);

Replaces all occurences of `search` by `replacement` .

The function does only one pass, for example:

    1
    tepl_utils_str_replace ("aaaa", "aa", "a");

returns "aa", not "a".

#### Parameters

string | a string |
search | the search string |
replacement | the replacement string |

#### Returns

A newly allocated string with the replacements. Free with `g_free()`.

Since: 4.4

### tepl_utils_markup_escape_text ()

    gchar *
    tepl_utils_markup_escape_text (const gchar *src);

The same as `g_markup_escape_text()`, but with an implementation that fully supports round-trip integrity. I.e. when GMarkupParser or any other XML parser will decode/unescape the string, the exact same string as `src` will be brought back. As long as `src` is a valid UTF-8 string.

The other difference with `g_markup_escape_text()` is that the `length` parameter is not present for `tepl_utils_markup_escape_text()`.

### g_markup_escape_text() doesn't fully support round-trip integrity

In fact, `g_markup_escape_text()` doesn't escape the tabstop, newline and carriage return characters. And the GMarkupParser correctly processes whitespace and line endings according to the XML rules for normalization of line endings and attribute values.

For example `"\t"` (a tab) after a round-trip through `g_markup_escape_text()` and GMarkupParser becomes a simple space.

#### Parameters

src | a nul-terminated UTF-8 string. |

#### Returns

a newly allocated string with the escaped text, or `NULL` if `src` is not a valid UTF-8 string. Free with `g_free()` when no longer needed.

[transfer full][nullable]

Since: 5.0

### tepl_utils_get_file_extension ()

    gchar *
    tepl_utils_get_file_extension (const gchar *filename);

Examples:

- "file.pdf" returns ".pdf".

- "file.PDF" returns ".pdf".

- "file.tar.gz" returns ".gz".

- "path/to/file.pdf" returns ".pdf".

- "file" (without an extension) returns "" (the empty string).

#### Parameters

filename | a filename. |

#### Returns

the `filename` 's extension with the dot, in lowercase. Free with `g_free()`.

Since: 4.4

### tepl_utils_get_file_shortname ()

    gchar *
    tepl_utils_get_file_shortname (const gchar *filename);

Returns `filename` without its extension. With the “extension” having the same definition as in `tepl_utils_get_file_extension()`; in other words it returns the other part of `filename` .

#### Parameters

filename | a filename. |

#### Returns

the `filename` without its extension. Free with `g_free()`.

Since: 4.4

### tepl_utils_replace_home_dir_with_tilde ()

    gchar *
    tepl_utils_replace_home_dir_with_tilde
                                   (const gchar *filename);

Replaces the home directory with a tilde, if the home directory is present in the `filename` .

#### Parameters

filename | the filename. |

#### Returns

the new filename. Free with `g_free()`.

Since: 4.4

### tepl_utils_decode_uri ()

    gboolean
    tepl_utils_decode_uri (const gchar *uri,
                           gchar **scheme,
                           gchar **user,
                           gchar **host,
                           gchar **port,
                           gchar **path);

Parse and break an uri apart in its individual components like the uri scheme, user info, host, port and path. The return value pointer can be `NULL` to ignore certain parts of the uri. If the function returns `TRUE`, then all return value pointers should be freed using `g_free()`.

#### Parameters

uri | the uri to decode |
scheme | return value pointer for the uri's scheme (e.g. http, sftp, ...), or `NULL`. | [out][optional]
user | return value pointer for the uri user info, or `NULL`. | [out][optional]
host | return value pointer for the uri host, or `NULL`. | [out][optional]
port | return value pointer for the uri port, or `NULL`. | [out][optional]
path | return value pointer for the uri path, or `NULL`. | [out][optional]

#### Returns

`TRUE` if the uri could be properly decoded, `FALSE` otherwise.

Since: 5.0

### tepl_utils_create_parent_directories ()

    gboolean
    tepl_utils_create_parent_directories (GFile *file,
                                          GCancellable *cancellable,
                                          GError **error);

Synchronously creates parent directories of `file` , so that `file` can be saved.

#### Parameters

file | a file |
cancellable | optional GCancellable object, `NULL` to ignore. | [nullable]
error | a location to a `NULL` GError, or `NULL`. | [out][optional]

#### Returns

whether the directories are correctly created. `FALSE` is returned on error.

Since: 5.0

### tepl_utils_file_query_exists_async ()

    void
    tepl_utils_file_query_exists_async (GFile *file,
                                        GCancellable *cancellable,
                                        GAsyncReadyCallback callback,
                                        gpointer user_data);

The asynchronous version of `g_file_query_exists()`. When the operation is finished, `callback` will be called. You can then call `tepl_utils_file_query_exists_finish()` to get the result of the operation.

#### Parameters

file | a GFile. |
cancellable | a GCancellable. |
callback | the callback to call when the operation is finished. |
user_data | the data to pass to the callback function. |

Since: 5.0

### tepl_utils_file_query_exists_finish ()

    gboolean
    tepl_utils_file_query_exists_finish (GFile *file,
                                         GAsyncResult *result);

Finishes the operation started with `tepl_utils_file_query_exists_async()`. There is no output GError parameter, so you should check if the operation has been cancelled (in which case `FALSE` will be returned).

#### Parameters

file | a GFile. |
result | a GAsyncResult. |

#### Returns

`TRUE` if the file exists and the operation hasn't been cancelled, `FALSE` otherwise.

Since: 5.0

### tepl_utils_create_close_button ()

    GtkWidget *
    tepl_utils_create_close_button (void);

#### Returns

a new close button (a GtkButton).

[transfer floating]

Since: 5.0

### tepl_utils_show_warning_dialog ()

    void
    tepl_utils_show_warning_dialog (GtkWindow *parent,
                                    const gchar *format,
                                    ...);

Shows a GtkDialog with the provided warning message.

#### Parameters

parent | the GtkWindow issuing the warning. | [nullable]
format | format string, as with `printf()`. |
... | parameters to insert into the format string. |

Since: 5.0

### tepl_utils_binding_transform_func_smart_bool ()

    gboolean
    tepl_utils_binding_transform_func_smart_bool
                                   (GBinding *binding,
                                    const GValue *from_value,
                                    GValue *to_value,
                                    gpointer user_data);

A GBindingTransformFunc to transform between these two GValue types:

- A GValue of type gboolean.

- A GValue of type GVariant, with the GVariant of type boolean.

For convenience, this function works in both directions (hence the “smart”), it introspects the types of `from_value` and `to_value` .

Note that if `from_value` and `to_value` are of the same GValue type, this function won't work and you shouldn't use a custom GBindingTransformFunc in the first place.

#### Parameters

binding | a GBinding. |
from_value | the GValue containing the value to transform. |
to_value | the GValue in which to store the transformed value. |
user_data | data passed to the transform function. |

#### Returns

`TRUE` if the transformation was successful, and `FALSE` otherwise.

Since: 5.0