gwyutils

gwyutils — Various utility functions

Synopsis




void        gwy_hash_table_to_slist_cb      (gpointer unused_key,
                                             gpointer value,
                                             gpointer user_data);
void        gwy_hash_table_to_list_cb       (gpointer unused_key,
                                             gpointer value,
                                             gpointer user_data);
gchar*      gwy_strkill                     (gchar *s,
                                             const gchar *killchars);
gchar*      gwy_strreplace                  (const gchar *haystack,
                                             const gchar *needle,
                                             const gchar *replacement,
                                             gsize maxrepl);
gint        gwy_strdiffpos                  (const gchar *s1,
                                             const gchar *s2);
gboolean    gwy_file_get_contents           (const gchar *filename,
                                             guchar **buffer,
                                             gsize *size,
                                             GError **error);
gboolean    gwy_file_abandon_contents       (guchar *buffer,
                                             gsize size,
                                             GError **error);
gchar*      gwy_find_self_dir               (const gchar *dirname);
void        gwy_find_self_set_argv0         (const gchar *argv0);
const gchar* gwy_get_user_dir               (void);
const gchar* gwy_get_home_dir               (void);
gchar*      gwy_canonicalize_path           (const gchar *path);
gchar*      gwy_sgettext                    (const gchar *msgid);
gchar*      gwy_str_next_line               (gchar **buffer);

Description

Various utility functions: creating GLib lists from hash tables gwy_hash_table_to_list_cb()), protably finding Gwyddion application directories (gwy_find_self_dir()), string functions (gwy_strreplace()), path manipulation (gwy_canonicalize_path()).

Details

gwy_hash_table_to_slist_cb ()

void        gwy_hash_table_to_slist_cb      (gpointer unused_key,
                                             gpointer value,
                                             gpointer user_data);

GHashTable to GSList convertor.

Usble in g_hash_table_foreach(), pass a pointer to a GSList* as user data to it.

unused_key : Hash key (unused).
value : Hash value.
user_data : User data (a pointer to GSList*).

gwy_hash_table_to_list_cb ()

void        gwy_hash_table_to_list_cb       (gpointer unused_key,
                                             gpointer value,
                                             gpointer user_data);

GHashTable to GList convertor.

Usble in g_hash_table_foreach(), pass a pointer to a GList* as user data to it.

unused_key : Hash key (unused).
value : Hash value.
user_data : User data (a pointer to GList*).

gwy_strkill ()

gchar*      gwy_strkill                     (gchar *s,
                                             const gchar *killchars);

Removes characters in killchars from string s, modifying it in place.

Use gwy_strkill(g_strdup(s), killchars) to get a modified copy.

s : A NUL-terminated string.
killchars : A string containing characters to kill.
Returns : s itself, the return value is to allow function call nesting.

gwy_strreplace ()

gchar*      gwy_strreplace                  (const gchar *haystack,
                                             const gchar *needle,
                                             const gchar *replacement,
                                             gsize maxrepl);

Replaces occurences of string needle in haystack with replacement.

haystack : A NUL-terminated string to search in.
needle : A NUL-terminated string to search for.
replacement : A NUL-terminated string to replace needle with.
maxrepl : Maximum number of occurences to replace (use (gsize)-1 to replace all occurences).
Returns : A newly allocated string.

gwy_strdiffpos ()

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

Finds position where two strings differ.

s1 : A string.
s2 : A string.
Returns : The last position where the strings do not differ yet. Particularly, -1 is returned if either string is NULL, zero-length, or they differ in the very first character.

gwy_file_get_contents ()

gboolean    gwy_file_get_contents           (const gchar *filename,
                                             guchar **buffer,
                                             gsize *size,
                                             GError **error);

Reads or mmaps file filename into memory.

The buffer must be treated as read-only and must be freed with gwy_file_abandon_contents(). It is NOT guaranteed to be NUL-terminated, use size to find its end.

filename : A file to read contents of.
buffer : Buffer to store the file contents.
size : Location to store buffer (file) size.
error : Return location for a GError.
Returns : Whether it succeeded. In case of failure buffer and size are reset too.

gwy_file_abandon_contents ()

gboolean    gwy_file_abandon_contents       (guchar *buffer,
                                             gsize size,
                                             GError **error);

Frees or unmmaps memory allocated by gwy_file_get_contents().

buffer : Buffer with file contents as created by gwy_file_get_contents().
size : Buffer size.
error : Return location for a GError.
Returns : Whether it succeeded.

gwy_find_self_dir ()

gchar*      gwy_find_self_dir               (const gchar *dirname);

Finds some system gwyddion directory.

This function exists only because of insane Win32 instalation manners where user can decide to put precompiled binaries anywhere. On sane systems it just returns build-time defined directory, unless gwy_find_self_set_argv0() has been called, in which case it behaves like like on Win32 (accommodating running uninstalled).

The returned value is not actually tested for existence, it's up to caller.

On Win32, gwy_find_self_set_argv0() must be called before any call to gwy_find_self_dir().

dirname : A gwyddion directory name: "modules", "plugins", "pixmaps", or "data".
Returns : The path as a newly allocated string.

gwy_find_self_set_argv0 ()

void        gwy_find_self_set_argv0         (const gchar *argv0);

Sets argv0 so that gwy_find_self_dir() can find self.

Calling this function enforces Win32 (or uninstalled) directory layout, even on Unix.

argv0 : Program's argv[0].

gwy_get_user_dir ()

const gchar* gwy_get_user_dir               (void);

Return directory where Gwyddion user settings and data should be stored.

On Unix this is normally in home directory. On silly platforms or silly occasions, silly locations can be returned as fallback.

Returns : The directory as a string that should not be freed.

gwy_get_home_dir ()

const gchar* gwy_get_home_dir               (void);

Returns home directory, or temporary directory as a fallback.

Under normal circumstances the same string as g_get_home_dir() would return is returned. But on MS Windows, something like "C:\Windows\Temp" can be returned too, as it is as good as anything else (we can write there).

Returns : Something usable as user home directory. It may be silly, but never NULL or empty.

gwy_canonicalize_path ()

gchar*      gwy_canonicalize_path           (const gchar *path);

Canonicalizes a filesystem path.

Particularly it makes the path absolute, resolves `..' and `.', and fixes slash sequences to single slashes. On Win32 it also converts all backslashes to slashes along the way.

Note this function does NOT resolve symlinks, use g_file_read_link() for that.

path : A filesystem path.
Returns : The canonical path, as a newly created string.

gwy_sgettext ()

gchar*      gwy_sgettext                    (const gchar *msgid);

Translate a message id containing disambiguating prefix ending with `|'.

msgid : Message id to translate, containing `|'-separated prefix.
Returns : Translated message, or msgid itself with all text up to the last `|' removed if there is no translation.

gwy_str_next_line ()

gchar*      gwy_str_next_line               (gchar **buffer);

Extracts a next line from a character buffer, modifying it in place.

buffer is updated to point after the end of the line and the "\n" (or "\r\n") is replaced with "\0", if present.

buffer : A character buffer containing some text.
Returns : The start of the line. NULL if the buffer is empty or NULL. NOT a new string, the returned pointer points somewhere to buffer.