![]() | ![]() | Gwyddion Library Reference Manual | ![]() |
---|
gwyutils — Various utility functions
struct 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); gchar* gwy_get_user_dir (void);
Various utility functions: creating GLib lists from hash tables, converting between enums and flags and their string representations, protably finding Gwyddion application directories.
struct GwyEnum { const gchar *name; gint value; };
Enumerated type with named values.
const gchar *name | Value name. |
gint value | The (integer) enum value. |
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*). |
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*). |
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. |
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. |
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. |
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. |
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.
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.
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. |
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. |
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 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. |
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]. |
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. |
Since 1.3.
<< GwySIUnit | gwydebugobjects >> |