e-util

## e-util e-util |

## Synopsis

    struct              tm;
    const gchar *       e_get_user_cache_dir                (void);
    const gchar *       e_get_user_config_dir               (void);
    const gchar *       e_get_user_data_dir                 (void);
    gchar *             e_util_strstrcase                   (const gchar *haystack,
                                                             const gchar *needle);
    gchar *             e_util_unicode_get_utf8             (const gchar *text,
                                                             gunichar *out);
    const gchar *       e_util_utf8_strstrcase              (const gchar *haystack,
                                                             const gchar *needle);
    const gchar *       e_util_utf8_strstrcasedecomp        (const gchar *haystack,
                                                             const gchar *needle);
    gint                e_util_utf8_strcasecmp              (const gchar *s1,
                                                             const gchar *s2);
    gchar *             e_util_utf8_remove_accents          (const gchar *str);
    gchar *             e_util_utf8_make_valid              (const gchar *str);
    const gchar *       e_util_ensure_gdbus_string          (const gchar *str,
                                                             gchar **gdbus_str);
    guint64             e_util_gthread_id                   (GThread *thread);
    void                e_filename_make_safe                (gchar *string);
    gchar *             e_filename_mkdir_encoded            (const gchar *basepath,
                                                             const gchar *fileprefix,
                                                             const gchar *filename,
                                                             gint fileindex);
    gsize               e_utf8_strftime                     (gchar *string,
                                                             gsize max,
                                                             const gchar *fmt,
                                                             const struct tm *tm);
    gsize               e_strftime                          (gchar *string,
                                                             gsize max,
                                                             const gchar *fmt,
                                                             const struct tm *tm);
    gchar **            e_util_slist_to_strv                (const GSList *strings);
    GSList *            e_util_strv_to_slist                (const gchar * const *strv);
    GSList *            e_util_copy_string_slist            (GSList *copy_to,
                                                             const GSList *strings);
    GSList *            e_util_copy_object_slist            (GSList *copy_to,
                                                             const GSList *objects);
    void                e_util_free_string_slist            (GSList *strings);
    void                e_util_free_object_slist            (GSList *objects);
    gboolean            e_binding_transform_enum_value_to_nick
                                                            (GBinding *binding,
                                                             const GValue *source_value,
                                                             GValue *target_value,
                                                             gpointer not_used);
    gboolean            e_binding_transform_enum_nick_to_value
                                                            (GBinding *binding,
                                                             const GValue *source_value,
                                                             GValue *target_value,
                                                             gpointer not_used);
    const gchar *       e_util_get_prefix                   (void);
    const gchar *       e_util_get_cp_prefix                (void);
    const gchar *       e_util_get_localedir                (void);
    gchar *             e_util_replace_prefix               (const gchar *configure_time_prefix,
                                                             const gchar *runtime_prefix,
                                                             const gchar *configure_time_path);
    gint                e_data_server_util_get_dbus_call_timeout
                                                            (void);
    void                e_data_server_util_set_dbus_call_timeout
                                                            (gint timeout_msec);
    #define             e_pointer_tracker_track             (ptr)
    void                e_pointer_tracker_track_with_info   (gpointer ptr,
                                                             const gchar *info);
    void                e_pointer_tracker_untrack           (gpointer ptr);
    void                e_pointer_tracker_dump              (void);

## Description

## Details

### struct tm

    struct tm;

### e_get_user_cache_dir ()

    const gchar *       e_get_user_cache_dir                (void);

Returns a base directory in which to store user-specific, non-essential cached data for Evolution or Evolution-Data-Server.

The returned string is owned by libedataserver and must not be modified or freed.

Returns : | base directory for user-specific, non-essential data

Since 2.32

### e_get_user_config_dir ()

    const gchar *       e_get_user_config_dir               (void);

Returns a base directory in which to store user-specific configuration information for Evolution or Evolution-Data-Server.

The returned string is owned by libedataserver and must not be modified or freed.

Returns : | base directory for user-specific configuration information

Since 2.32

### e_get_user_data_dir ()

    const gchar *       e_get_user_data_dir                 (void);

Returns a base directory in which to store user-specific data for Evolution or Evolution-Data-Server.

The returned string is owned by libedataserver and must not be modified or freed.

Returns : | base directory for user-specific data

Since 2.32

### e_util_strstrcase ()

    gchar *             e_util_strstrcase                   (const gchar *haystack,
                                                             const gchar *needle);

Find the first instance of `needle` in `haystack`, ignoring case for bytes that are ASCII characters.

`haystack` : | The string to search in.
`needle` : | The string to search for.
Returns : | A pointer to the start of `needle` in `haystack`, or NULL if `needle` is not found.

### e_util_unicode_get_utf8 ()

    gchar *             e_util_unicode_get_utf8             (const gchar *text,
                                                             gunichar *out);

Get a UTF-8 character from the beginning of `text`.

`text` : | The string to take the UTF-8 character from.
`out` : | The location to store the UTF-8 character in.
Returns : | A pointer to the next character in `text` after `out`.

### e_util_utf8_strstrcase ()

    const gchar *       e_util_utf8_strstrcase              (const gchar *haystack,
                                                             const gchar *needle);

Find the first instance of `needle` in `haystack`, ignoring case. (No proper case folding or decomposing is done.) Both `needle` and `haystack` are UTF-8 strings.

`haystack` : | The string to search in.
`needle` : | The string to search for.
Returns : | A pointer to the first instance of `needle` in `haystack`, or `NULL` if no match is found, or if either of the strings are not legal UTF-8 strings.

### e_util_utf8_strstrcasedecomp ()

    const gchar *       e_util_utf8_strstrcasedecomp        (const gchar *haystack,
                                                             const gchar *needle);

Find the first instance of `needle` in `haystack`, where both `needle` and `haystack` are UTF-8 strings. Both strings are stripped and decomposed for comparison, and case is ignored.

`haystack` : | The string to search in.
`needle` : | The string to search for.
Returns : | A pointer to the first instance of `needle` in `haystack`, or `NULL` if either of the strings are not legal UTF-8 strings.

### e_util_utf8_strcasecmp ()

    gint                e_util_utf8_strcasecmp              (const gchar *s1,
                                                             const gchar *s2);

Compares two UTF-8 strings using approximate case-insensitive ordering.

`s1` : | a UTF-8 string
`s2` : | another UTF-8 string
Returns : | < 0 if `s1` compares before `s2`, 0 if they compare equal, > 0 if `s1` compares after `s2`

### e_util_utf8_remove_accents ()

    gchar *             e_util_utf8_remove_accents          (const gchar *str);

Returns a newly-allocated copy of `str` with accents removed.

`str` : | a UTF-8 string, or `NULL`
Returns : | a newly-allocated string

Since 2.28

### e_util_utf8_make_valid ()

    gchar *             e_util_utf8_make_valid              (const gchar *str);

Returns a newly-allocated copy of `str`, with invalid characters replaced by Unicode replacement characters (U+FFFD).

`str` : | a UTF-8 string
Returns : | a newly-allocated string

Since 3.0

### e_util_ensure_gdbus_string ()

    const gchar *       e_util_ensure_gdbus_string          (const gchar *str,
                                                             gchar **gdbus_str);

If `str` is a valid UTF-8 string, the function returns `str` and does not set `gdbus_str`.

If `str` is an invalid UTF-8 string, the function calls `e_util_utf8_make_valid()` and points `gdbus_str` to the newly-allocated, valid UTF-8 string, and also returns it. The caller should free the string pointed to by `gdbus_str` with `g_free()`.

If `str` is `NULL`, the function returns an empty string and does not set `gdbus_str`.

Admittedly, the function semantics are a little awkward. The example below illustrates the easiest way to cope with the `gdbus_str` argument:

<informalexample> <programlisting> const gchar *trusted_utf8; gchar *allocated = NULL;

trusted_utf8 = e_util_ensure_gdbus_string (untrusted_utf8, &allocated);

Do stuff with trusted_utf8, then clear it.

trusted_utf8 = NULL;

g_free (allocated); allocated = NULL; </programlisting> </informalexample>

`str` : | a possibly invalid UTF-8 string, or `NULL`
`gdbus_str` : | return location for the corrected string
Returns : | a valid UTF-8 string

Since 3.0

### e_util_gthread_id ()

    guint64             e_util_gthread_id                   (GThread *thread);

Returns a 64-bit integer hopefully uniquely identifying the thread. To be used in debugging output and logging only. The returned value is just a cast of a pointer to the 64-bit integer.

There is no guarantee that calling `e_util_gthread_id()` on one thread first and later after that thread has dies on another won't return the same integer.

On Linux and Win32, known to really return a unique id for each thread existing at a certain time. No guarantee that ids won't be reused after a thread has terminated, though.

`thread` : | A GThread pointer
Returns : | A 64-bit integer.

Since 2.32

### e_filename_make_safe ()

    void                e_filename_make_safe                (gchar *string);

### e_filename_mkdir_encoded ()

    gchar *             e_filename_mkdir_encoded            (const gchar *basepath,
                                                             const gchar *fileprefix,
                                                             const gchar *filename,
                                                             gint fileindex);

Creates a local path constructed from `basepath` / `fileprefix` + "-" + `filename`, and makes sure the path `basepath` exists. If creation of the path fails, then NULL is returned.

`basepath` : | base path of a file name; this is left unchanged
`fileprefix` : | prefix for the filename; this is encoded
`filename` : | file name to use; this is encoded; can be `NULL`
`fileindex` : | used when `filename` is NULL, then the filename is generated as "file" + fileindex
Returns : | Full local path like `g_build_filename()` except that `fileprefix` and `filename` are encoded to create a proper file elements for a file system. Free returned pointer with `g_free()`.

Since 3.4

### e_utf8_strftime ()

    gsize               e_utf8_strftime                     (gchar *string,
                                                             gsize max,
                                                             const gchar *fmt,
                                                             const struct tm *tm);

The UTF-8 equivalent of `e_strftime()`.

`string` : | The string array to store the result in.
`max` : | The size of array `s`.
`fmt` : | The formatting to use on `tm`.
`tm` : | The time value to format.
Returns : | The number of characters placed in `s`.

### e_strftime ()

    gsize               e_strftime                          (gchar *string,
                                                             gsize max,
                                                             const gchar *fmt,
                                                             const struct tm *tm);

This function is a wrapper around the strftime (3) function, which converts the &percnt;l and &percnt;k (12h and 24h) format variables if necessary.

`string` : | The string array to store the result in.
`max` : | The size of array `s`.
`fmt` : | The formatting to use on `tm`.
`tm` : | The time value to format.
Returns : | The number of characters placed in `s`.

### e_util_slist_to_strv ()

    gchar **            e_util_slist_to_strv                (const GSList *strings);

Convert list of strings into NULL-terminates array of strings.

`strings` : | a GSList of strings (const gchar *)
Returns : | Newly allocated NULL-terminated array of strings. Returned pointer should be freed with `g_strfreev()`. Note: Pair function for this is `e_util_strv_to_slist()`. [transfer full]

Since 3.4

### e_util_strv_to_slist ()

    GSList *            e_util_strv_to_slist                (const gchar * const *strv);

Convert NULL-terminated array of strings to a list of strings.

`strv` : | a NULL-terminated array of strings (const gchar *)
Returns : | Newly allocated GSList of newly allocated strings. Returned pointer should be freed with `e_util_free_string_slist()`. Note: Pair function for this is `e_util_slist_to_strv()`. [transfer full]

Since 3.4

### e_util_copy_string_slist ()

    GSList *            e_util_copy_string_slist            (GSList *copy_to,
                                                             const GSList *strings);

Copies GSList of strings at the end of `copy_to`.

`copy_to` : | Where to copy; can be NULL
`strings` : | GSList of strings to be copied
Returns : | New head of `copy_to`. Returned pointer can be freed with `e_util_free_string_slist()`. [transfer full]

Since 3.4

### e_util_copy_object_slist ()

    GSList *            e_util_copy_object_slist            (GSList *copy_to,
                                                             const GSList *objects);

Copies GSList of GObject-s at the end of `copy_to`.

`copy_to` : | Where to copy; can be NULL
`objects` : | GSList of GObject-s to be copied
Returns : | New head of `copy_to`. Returned pointer can be freed with `e_util_free_object_slist()`. [transfer full]

Since 3.4

### e_util_free_string_slist ()

    void                e_util_free_string_slist            (GSList *strings);

Frees memory previously allocated by `e_util_strv_to_slist()`.

`strings` : | a GSList of strings (gchar *)

Since 3.4

### e_util_free_object_slist ()

    void                e_util_free_object_slist            (GSList *objects);

Calls `g_object_unref()` on each member of `objects` and then frees also `objects` itself.

`objects` : | a GSList of GObject-s

Since 3.4

### e_binding_transform_enum_value_to_nick ()

    gboolean            e_binding_transform_enum_value_to_nick
                                                            (GBinding *binding,
                                                             const GValue *source_value,
                                                             GValue *target_value,
                                                             gpointer not_used);

Transforms an enumeration value to its corresponding nickname.

`binding` : | a GBinding
`source_value` : | a GValue whose type is derived from G_TYPE_ENUM
`target_value` : | a GValue of type G_TYPE_STRING
`not_used` : | not used
Returns : | `TRUE` if the enum value has a corresponding nickname

Since 3.4

### e_binding_transform_enum_nick_to_value ()

    gboolean            e_binding_transform_enum_nick_to_value
                                                            (GBinding *binding,
                                                             const GValue *source_value,
                                                             GValue *target_value,
                                                             gpointer not_used);

Transforms an enumeration nickname to its corresponding value.

`binding` : | a GBinding
`source_value` : | a GValue of type G_TYPE_STRING
`target_value` : | a GValue whose type is derived from G_TYPE_ENUM
`not_used` : | not used
Returns : | `TRUE` if the enum nickname has a corresponding value

Since 3.4

### e_util_get_prefix ()

    const gchar *       e_util_get_prefix                   (void);

### e_util_get_cp_prefix ()

    const gchar *       e_util_get_cp_prefix                (void);

### e_util_get_localedir ()

    const gchar *       e_util_get_localedir                (void);

### e_util_replace_prefix ()

    gchar *             e_util_replace_prefix               (const gchar *configure_time_prefix,
                                                             const gchar *runtime_prefix,
                                                             const gchar *configure_time_path);

### e_data_server_util_get_dbus_call_timeout ()

    gint                e_data_server_util_get_dbus_call_timeout
                                                            (void);

Returns the value set by `e_data_server_util_set_dbus_call_timeout()`.

Returns : | the D-Bus call timeout in milliseconds

Since 3.0

### e_data_server_util_set_dbus_call_timeout ()

    void                e_data_server_util_set_dbus_call_timeout
                                                            (gint timeout_msec);

Sets default timeout, in milliseconds, for calls of `g_dbus_proxy_call()` family functions.

-1 means the default value as set by D-Bus itself. G_MAXINT means no timeout at all.

Default value is set also by configure option --with-dbus-call-timeout=ms and -1 is used when not set.

`timeout_msec` : | default timeout for D-Bus calls in miliseconds

Since 3.0

### e_pointer_tracker_track()

    #define             e_pointer_tracker_track(ptr)

FIXME: Document me.

Since 3.2

### e_pointer_tracker_track_with_info ()

    void                e_pointer_tracker_track_with_info   (gpointer ptr,
                                                             const gchar *info);

FIXME: Document me.

Since 3.2

### e_pointer_tracker_untrack ()

    void                e_pointer_tracker_untrack           (gpointer ptr);

FIXME: Document me.

Since 3.2

### e_pointer_tracker_dump ()

    void                e_pointer_tracker_dump              (void);

FIXME: Document me.

Since 3.2