TeplUtils

TeplUtils — Utility functions

Functions

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

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:

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