## gwyutils

gwyutils — Various utility functions

## Synopsis

    #include <libgwyddion/gwyddion.h>

    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_strisident                      (const gchar *s,
                                                             const gchar *more,
                                                             const gchar *startmore);
    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);
    const gchar*        gwy_get_user_dir                    (void);
    const gchar*        gwy_get_home_dir                    (void);
    gchar*              gwy_canonicalize_path               (const gchar *path);
    gboolean            gwy_filename_ignore                 (const gchar *filename_sys);
    gchar*              gwy_sgettext                        (const gchar *msgid);
    gchar*              gwy_str_next_line                   (gchar **buffer);
    void                gwy_memcpy_byte_swap                (const guint8 *source,
                                                             guint8 *dest,
                                                             gsize item_size,
                                                             gsize nitems,
                                                             gsize byteswap);
    void                gwy_object_set_or_reset             (gpointer object,
                                                             GType type,
                                                             ...);

## 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_strisident ()

    gboolean            gwy_strisident                      (const gchar *s,
                                                             const gchar *more,
                                                             const gchar *startmore);

Checks whether a string is valid identifier.

Valid identifier must start with an alphabetic character or a character from `startmore`, and it must continue with alphanumeric characters or characters from `more`.

Note underscore is not allowed by default, you have to pass it in `more` and/or `startmore`.

`s` : | A NUL-terminated string.
`more` : | List of additional ASCII characters allowed inside identifier, empty list can be passed as `NULL`.
`startmore` : | List of additional ASCII characters allowed as the first identifier characters, empty list can be passed as `NULL`.
Returns : | `TRUE` if `s` is valid identifier, `FALSE` otherwise.

### 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 a system Gwyddion directory.

On Unix, a compiled-in path is returned, unless it's overriden with environment variables (see gwyddion manual page).

On Win32, the directory where the libgwyddion DLL from which this function was called resides is taken as the base and the location of other Gwyddion directories is calculated from it.

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

To obtain the Gwyddion user directory see `gwy_get_user_dir()`.

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

### gwy_get_user_dir ()

    const gchar*        gwy_get_user_dir                    (void);

Returns the directory where Gwyddion user settings and data should be stored.

On Unix this is usually a dot-directory in user's home directory. On modern Win32 the returned directory resides in user's Documents and Settings. On silly platforms or silly occasions, silly locations (namely a temporary directory) can be returned as fallback.

To obtain a Gwyddion system directory see `gwy_find_self_dir()`.

Returns : | The directory as a constant 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_filename_ignore ()

    gboolean            gwy_filename_ignore                 (const gchar *filename_sys);

Checks whether file should be ignored.

This function checks for common file names indicating files that should be normally ignored. Currently it means backup files (ending with ~ or .bak) and Unix hidden files (starting with a dot).

`filename_sys` : | File name in GLib encoding.
Returns : | `TRUE` to ignore this file, `FALSE` otherwise.

### 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`.

### gwy_memcpy_byte_swap ()

    void                gwy_memcpy_byte_swap                (const guint8 *source,
                                                             guint8 *dest,
                                                             gsize item_size,
                                                             gsize nitems,
                                                             gsize byteswap);

Copies a block of memory swapping bytes along the way.

The bits in `byteswap` correspond to groups of bytes to swap: if j-th bit is set, adjacent groups of 2j bits are swapped. For example, value 3 means items will be divided into couples (bit 1) of bytes and adjacent couples of bytes swapped, and then divided into single bytes (bit 0) and adjacent bytes swapped. The net effect is reversal of byte order in groups of four bytes. More generally, if you want to reverse byte order in groups of size 2j, use byte swap pattern j-1.

When `byteswap` is zero, this function reduces to plain `memcpy()`.

`source` : | Source memory block.
`dest` : | Destination memory location.
`item_size` : | Size of one copied item, it should be a power of two.
`nitems` : | Number of items of size `item_size` to copy.
`byteswap` : | Byte swap pattern.

Since 2.1

### gwy_object_set_or_reset ()

    void                gwy_object_set_or_reset             (gpointer object,
                                                             GType type,
                                                             ...);

Sets object properties, resetting other properties to defaults.

All explicitly specified properties are set. In addition, all unspecified settable properties of type `type` (or all unspecified properties if `type` is 0) are reset to defaults. Settable means the property is writable and not construction-only.

The order in which properties are set is undefined beside keeping the relative order of explicitly specified properties, therefore this function is not generally usable for objects with interdependent properties.

Unlike `g_object_set()`, it does not set properties that already have the requested value, as a consequences notifications are emitted only for properties which actually change.

`object` : | A GObject.
`type` : | The type whose properties are to reset, may be zero for all types. The object must be of this type (more precisely `object` is-a `type` must hold).
`...` : | `NULL`-terminated list of name/value pairs of properties to set as in `g_object_set()`. It can be `NULL` alone to only reset properties to defaults.

## See Also

gwymacros -- utility macros