![]() |
![]() |
Gwyddion Library Reference Manual | ![]() |
|
---|---|---|---|---|
Top | Description |
#include <libgwyddion/gwyddion.h> enum GwyRawDataType; enum GwyByteOrder; 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_ascii_strcase_equal (gconstpointer v1
,gconstpointer v2
); guint gwy_ascii_strcase_hash (gconstpointer v
); guint gwy_stramong (const gchar *str
,...
); gpointer gwy_memmem (gconstpointer haystack
,gsize haystack_len
,gconstpointer needle
,gsize needle_len
); 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_convert_raw_data (gconstpointer data
,gsize nitems
,gssize stride
,GwyRawDataType datatype
,GwyByteOrder byteorder
,gdouble *target
,gdouble scale
,gdouble offset
); guint gwy_raw_data_size (GwyRawDataType datatype
); void gwy_object_set_or_reset (gpointer object
,GType type
,...
);
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()
).
typedef enum { GWY_RAW_DATA_SINT8, GWY_RAW_DATA_UINT8, GWY_RAW_DATA_SINT16, GWY_RAW_DATA_UINT16, GWY_RAW_DATA_SINT32, GWY_RAW_DATA_UINT32, GWY_RAW_DATA_SINT64, GWY_RAW_DATA_UINT64, GWY_RAW_DATA_HALF, GWY_RAW_DATA_FLOAT, GWY_RAW_DATA_REAL, GWY_RAW_DATA_DOUBLE, } GwyRawDataType;
Types of raw data.
Multibyte types usually need to be complemented with GwyByteOrder to get a full type specification.
Signed 8bit integer (one byte). | |
Unsigned 8bit integer (one byte). | |
Signed 16bit integer (two bytes). | |
Unsigned 16bit integer (two bytes). | |
Signed 32bit integer (four bytes). | |
Unsigned 32bit integer (four bytes). | |
Signed 64bit integer (eight bytes). | |
Unsigned 64bit integer (eight bytes). | |
Half-precision floating point number (two bytes). | |
Single-precision floating point number (four bytes). | |
Pascal ‘real’ floating point number (six bytes). | |
Double-precision floating point number (eight bytes). |
Since 2.25
typedef enum { GWY_BYTE_ORDER_NATIVE = 0, GWY_BYTE_ORDER_LITTLE_ENDIAN = G_LITTLE_ENDIAN, GWY_BYTE_ORDER_BIG_ENDIAN = G_BIG_ENDIAN, } GwyByteOrder;
Type of byte order.
Native byte order. | |
Little endian byte order (the same as
G_LITTLE_ENDIAN ).
|
|
Big endian byte order (the same as
G_BIG_ENDIAN ).
|
Since 2.25
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.
|
Hash key (unused). |
|
Hash value. |
|
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.
|
Hash key (unused). |
|
Hash value. |
|
User data (a pointer to GList*). |
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.
|
A NUL-terminated string. |
|
A string containing characters to kill. |
Returns : |
s itself, the return value is to allow function call nesting. |
gchar * gwy_strreplace (const gchar *haystack
,const gchar *needle
,const gchar *replacement
,gsize maxrepl
);
Replaces occurences of string needle
in haystack
with replacement
.
|
A NUL-terminated string to search in. |
|
A NUL-terminated string to search for. |
|
A NUL-terminated string to replace needle with. |
|
Maximum number of occurences to replace (use (gsize)-1 to replace all occurences). |
Returns : |
A newly allocated string. |
gint gwy_strdiffpos (const gchar *s1
,const gchar *s2
);
Finds position where two strings differ.
|
A string. |
|
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. |
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
.
|
A NUL-terminated string. |
|
List of additional ASCII characters allowed inside identifier, empty
list can be passed as NULL . |
|
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. |
gboolean gwy_ascii_strcase_equal (gconstpointer v1
,gconstpointer v2
);
Compares two strings for equality, ignoring case.
The case folding is performed only on ASCII characters.
This function is intended to be passed to g_hash_table_new()
as
key_equal_func
, namely in conjuction with gwy_ascii_strcase_hash()
hashing
function.
|
String key. |
|
String key to compare with v1 . |
Returns : |
TRUE if the two string keys match, ignoring case. |
Since 2.26
guint gwy_ascii_strcase_hash (gconstpointer v
);
Converts a string to a hash value, ignoring case.
The case folding is performed only on ASCII characters.
This function is intended to be passed to g_hash_table_new()
as hash_func
,
namely in conjuction with gwy_ascii_strcase_equal()
comparison function.
|
String key. |
Returns : |
The hash value corresponding to the key v . |
Since 2.26
guint gwy_stramong (const gchar *str
,...
);
Checks whether a string is equal to any from given list.
|
A string to find. |
|
NULL -terminated list of string to compare str with. |
Returns : |
Zero if str does not equal to any string from the list, nozero
othwerise. More precisely, the position + 1 of the first string
str equals to is returned in the latter case. |
Since 2.11
gpointer gwy_memmem (gconstpointer haystack
,gsize haystack_len
,gconstpointer needle
,gsize needle_len
);
Find a block of memory in another block of memory.
This function is very similar to strstr()
, except that it works with
arbitrary memory blocks instead of NUL
-terminated strings.
If needle_len
is zero, haystack
is always returned.
On GNU systems with glibc at least 2.1 this is a just a trivial memmem()
wrapper. On other systems it emulates memmem()
behaviour.
|
Memory block to search in. |
|
Size of haystack , in bytes. |
|
Memory block to find. |
|
Size of needle , in bytes. |
Returns : |
Pointer to the first byte of memory block in haystack that matches
needle ; NULL if no such block exists. |
Since 2.12
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.
|
A file to read contents of. |
|
Buffer to store the file contents. |
|
Location to store buffer (file) size. |
|
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 unmmaps memory allocated by gwy_file_get_contents()
.
|
Buffer with file contents as created by gwy_file_get_contents() . |
|
Buffer size. |
|
Return location for a GError. Since 2.22 no error can occur;
safely pass NULL . |
Returns : |
Whether it succeeded. Since 2.22 it always return TRUE . |
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()
.
|
A gwyddion directory name:
"modules" ,
"plugins" ,
"pixmaps" ,
"locale" , or
"data" . |
Returns : |
The path as a newly allocated string. |
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. |
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. |
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.
|
A filesystem path. |
Returns : |
The canonical path, as a newly created string. |
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).
gchar * gwy_sgettext (const gchar *msgid
);
Translate a message id containing disambiguating prefix ending with `|'.
|
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. |
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" or "\r\n") is replaced with "\0", if present.
The final line may or may not be terminated with an EOL marker, its contents
is returned in either case. Note, however, that the empty string "" is not
interpreted as an empty unterminated line. Instead, NULL
is immediately
returned.
The typical usage of gwy_str_next_line()
is:
1 2 3 4 5 6 7 |
gchar *p = text; for (gchar *line = gwy_str_next_line(&p); line; line = gwy_str_next_line(&p)) { g_strstrip(line); // Do something more with line } |
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 memory block. |
|
Destination memory location. |
|
Size of one copied item, it should be a power of two. |
|
Number of items of size item_size to copy. |
|
Byte swap pattern. |
Since 2.1
void gwy_convert_raw_data (gconstpointer data
,gsize nitems
,gssize stride
,GwyRawDataType datatype
,GwyByteOrder byteorder
,gdouble *target
,gdouble scale
,gdouble offset
);
Converts a block of raw data items to doubles.
Note that conversion from 64bit integral types may lose information as they have more bits than the mantissa of doubles. All other conversions should be precise.
|
Pointer to the input raw data to be converted to doubles. The data
type is given by datatype and byteorder . |
|
Data block length, i.e. the number of consecutive items to convert. |
|
Item stride in the raw data, measured in raw values. Pass 1 for
consecutive raw data. For backward reading, pass -1 and point
data to the last raw item instead of the first. |
|
Type of the raw data items. |
|
Byte order of the raw data. |
|
Array of nitems to store the converted input data to. |
|
Factor to multiply the data with. |
|
Constant to add to the data after multiplying with scale . |
Since 2.25
guint gwy_raw_data_size (GwyRawDataType datatype
);
Reports the size of a single raw data item.
|
Raw data type. |
Returns : |
The size of a single raw data item of type datatype . |
Since 2.25
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.
|
A GObject. |
|
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. |