gwyutils

gwyutils — Various utility functions

Synopsis




typedef     GwyEnum;
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);
gint        gwy_string_to_enum              (const gchar *str,
                                             const GwyEnum *enum_table,
                                             gint n);
gchar*      gwy_enum_to_string              (gint enumval,
                                             const GwyEnum *enum_table,
                                             gint n);
gint        gwy_string_to_flags             (const gchar *str,
                                             const GwyEnum *enum_table,
                                             gint n,
                                             const gchar *delimiter);
gchar*      gwy_flags_to_string             (gint enumval,
                                             const GwyEnum *enum_table,
                                             gint n,
                                             const gchar *glue);
gchar*      gwy_strkill                     (gchar *s,
                                             const gchar *killchars);
gchar*      gwy_strreplace                  (const gchar *haystack,
                                             const gchar *needle,
                                             const gchar *replacement,
                                             gsize maxrepl);
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);

Description

Various utility functions: creating GLib lists from hash tables, converting between enums and flags and their string representations, protably finding Gwyddion application directories.

Details

GwyEnum

typedef struct {
    const gchar *name;
    gint value;
} GwyEnum;

Enumerated type with named values.


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_string_to_enum ()

gint        gwy_string_to_enum              (const gchar *str,
                                             const GwyEnum *enum_table,
                                             gint n);

Creates an integer representation of a string enum value str.

str: A string containing one of enum_table string values.
enum_table: A table of corresponding string-integer pairs.
n: The number of elements in enum_table, may be -1 when enum_table is terminated by a NULL name.
Returns : The integer enum value (NOT index in the table), or -1 if str was not found.

gwy_enum_to_string ()

gchar*      gwy_enum_to_string              (gint enumval,
                                             const GwyEnum *enum_table,
                                             gint n);

Creates a string representation of an integer enum value enumval.

enumval: A one integer value from enum_table.
enum_table: A table of corresponding string-integer pairs.
n: The number of elements in enum_table, may be -1 when enum_table is terminated by a NULL name.
Returns : The name as a string from enum_table, thus it generally should not be modified or freed, unless enum_table is supposed to be modified too. If the value is not found, an empty string is returned.

gwy_string_to_flags ()

gint        gwy_string_to_flags             (const gchar *str,
                                             const GwyEnum *enum_table,
                                             gint n,
                                             const gchar *delimiter);

Creates an integer flag combination of its string representation str.

str: A string containing one of enum_table string values.
enum_table: A table of corresponding string-integer pairs.
n: The number of elements in enum_table, may be -1 when enum_table is terminated by a NULL name.
delimiter: A delimiter to split str on, when NULL space is used.
Returns : All the flags present in str, bitwise ORer.

gwy_flags_to_string ()

gchar*      gwy_flags_to_string             (gint enumval,
                                             const GwyEnum *enum_table,
                                             gint n,
                                             const gchar *glue);

Creates a string representation of integer flag combination enumval.

enumval: Some ORed integer flags from enum_table.
enum_table: A table of corresponding string-integer pairs.
n: The number of elements in enum_table, may be -1 when enum_table is terminated by a NULL name.
glue: A glue to join string values with, when NULL space is used.
Returns : The string representation as a newly allocated string. It should be freed when no longer used.

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.

Since 1.1.


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.

Since 1.1.


gwy_file_get_contents ()

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

Reads or maps 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 unmaps 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 gwyddion directory.

This function exists only because of insane Win32 instalation manners. On sane systems is just returns a copy of GWY_PIXMAP_DIR, etc. instead.

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 like "pixmaps" or "modules".
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.

argv0: Program's argv[0].