Top | ![]() |
![]() |
![]() |
![]() |
enum | GwyParseDoublesFlags |
enum | GwyParseDoublesError |
#define | GWY_PARSE_DOUBLES_ERROR |
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()
).
gboolean
(*GwySetFractionFunc) (gdouble fraction
);
Type of function for reporting progress of a long computation.
Usually you want to use gwy_app_wait_set_fraction()
.
gboolean
(*GwySetMessageFunc) (const gchar *message
);
Type of function for reporting what a long computation is doing now.
Usually you want to use gwy_app_wait_set_message()
.
GQuark
gwy_parse_doubles_error_quark (void
);
Returns error domain for floating point value parsing and evaluation.
See and use GWY_PARSE_DOUBLES_ERROR
.
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.
gchar * gwy_strreplace (const gchar *haystack
,const gchar *needle
,const gchar *replacement
,gsize maxrepl
);
Replaces occurences of string needle
in haystack
with replacement
.
See gwy_gstring_replace()
for a function which does in-place replacement on a GString.
gint gwy_strdiffpos (const gchar *s1
,const gchar *s2
);
Finds position where two strings differ.
gboolean gwy_ascii_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
.
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.
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.
guint gwy_stramong (const gchar *str
,...
);
Checks whether a string is equal to any from given list.
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 but may be a bit slower.
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.
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 |
|
size |
Buffer size. |
|
error |
Return location for a GError. Since 2.22 no error can occur; safely pass |
gchar * gwy_find_self_path (const gchar *dirname
,...
);
Finds a system Gwyddion directory.
On all operating system, the directories can be overriden with environment variables which have the highest priority (see gwyddion manual page). Otherwise…
In an OS X bundle, a location in the bundle is returned.
On Unix, a compiled-in path is returned.
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 is up to the caller.
Icons, modules and system resources like gradients reside in subdirectories. Use the additional path components to construct their path directly. If you are looking for a single file you can use them to construct path to this specific file, although usually one looks for directories.
To obtain the Gwyddion user directory see 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()
.
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).
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.
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).
const gchar * gwy_sgettext (const gchar *domain
,const gchar *msgid
);
Translate a message id containing disambiguating prefix ending with ‘\004’.
The control ASCII character 0x04 is used to separate message context in gettext and is used by macros such
as C_()
. It is not allowed in translatable strings.
If the message is translated then the translation is returned. If it is not translated and it contains the
character ‘\004’ a pointer into msgid
is returned, to the byte after the separator character.
If you can pass both the context and message separately, use the standard macros. Whenever you would need to write ‘\004’ literally or pass a literal string at all, it is probably an incorrect usage. In particular, in direct calls do
1 |
foo(C_("context", "Message")); |
instead of
1 |
foo(gwy_C("context\004Message")); |
However, using NC_()
and C_()
requires duplicating the context and/or passing them around separately. It is
sometimes awkward or even not possible to pass the context where it is finally needed.
If you need to pass the context and message already in a single string (separated with ‘\004’) you can use this
function. It is a simpler alternative to g_dpgettext()
which tries to use both ‘|’ and ‘\004’ in a complicated
manner when the context is not passed separately. You can use macro gwy_NC()
to form source code strings with
context. See also macro GWY_C()
which expands to gwy_sgettext()
with the first argument set to GETTEXT_PACKAGE.
The function uses g_dgettext()
internally to avoid mixing translated and untranslated messages.
This function description is about ten times longer than the implementation. So the entire situation is clearly a mess.
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 } |
guint
gwy_str_fixed_font_width (const gchar *str
);
Measures the width of UTF-8 encoded string in fixed-width font.
This corresponds to width of the string displayed on a text terminal, for instance. Zero and double width characters are taken into account. It is not guaranteed all terminals display the string with the calculated width.
guint gwy_gstring_replace (GString *str
,const gchar *old
,const gchar *replacement
,gint count
);
Replaces non-overlapping occurrences of one string with another in a GString.
Passing NULL
or the empty string for replacement
will cause the occurrences of old
to be removed.
Passing NULL
or the empty string for old
means a match occurs at every position in the string, including after
the last character. So replacement
will be inserted at every position in this case.
See gwy_strreplace()
for a function which creates a new plain C string with substring replacement.
str |
A GString string to modify in place. |
|
old |
The character sequence to find and replace. Passing |
|
replacement |
The character sequence that should replace |
|
count |
The maximum number of replacements to make. A negative number means replacing all occurrences of |
void
gwy_gstring_to_native_eol (GString *str
);
Converts "\n" in a string to operating system native line terminators.
Text files are most easily written by opening them in the text mode. This function can be useful for writing text
files using functions such as g_file_set_contents()
that do not permit the conversion to happen automatically.
It is a no-op on all POSIX systems, including OS X. So at present, it actually performs any conversion at all only on MS Windows.
const gchar *
gwy_get_decimal_separator (void
);
Find the decimal separator for the current locale.
This is a localeconv()
wrapper.
void gwy_append_doubles_to_gstring (GString *str
,const gdouble *values
,guint n
,gint precision
,const gchar *field_separator
,gboolean force_decimal_dot
);
Formats a sequence of double values to a GString.
str |
String to append the formated numbers to. |
|
values |
Array of double values to format. |
|
n |
Number of values in |
|
precision |
Format precision, within the standard precision of double. |
|
field_separator |
String to put between each two formatted numbers, usually a space or tab character. |
|
force_decimal_dot |
|
gdouble * gwy_parse_doubles (const gchar *s
,gdouble *values
,GwyParseDoublesFlags flags
,gint *nlines
,gint *ncols
,gchar **endptr
,GError **error
);
Parse a block of text floating point values.
Any combinations of a priori known and unknown dimensions is possible. For an unknown number of columns the number
of columns must still be the same on each line, unless the flag GWY_PARSE_DOUBLES_FREE_FORM
is passed. If any
dimension is unknown, values
cannot be preallocated as must be NULL
.
Currently the values must be whitespace separated and in the POSIX format.
If the flag GWY_PARSE_DOUBLES_EMPTY
is passed and the string contains not data, it is not considered an error
and error
is not set. However, the function returns NULL
in such case. If you allow empty data you need to check
the error to distinguish them from failure.
s |
String with floating point data to parse. |
|
values |
Pre-allocated array where to store values (for a fixed number of values). |
|
flags |
Parsing flags. |
|
nlines |
Location where to store the number of lines. Initialise to the number of lines for a fixed number of lines or to -1 for unknown. The value is only changed if initially -1. |
|
ncols |
Location where to store the number of columns. Initialise to the number of columns for a fixed number of columns or to -1 for unknown. The value is only changed if initially -1. |
|
endptr |
Location where to store pointer after the last parsed character in |
|
error |
Return location for a GError. |
gchar * gwy_convert_to_utf8 (const guchar *str
,glong len
,const gchar *codeset
);
Converts a string to UTF-8.
This is a g_convert()
wrapper for the typical SPM file reading use case. Conversion failure is indicated just by
a NULL
return value. Conversion is either completely successful or fails. Use g_convert()
or g_iconv()
if you
need to handle partial conversions and failure details.
gchar * gwy_utf16_to_utf8 (const gunichar2 *str
,glong len
,GwyByteOrder byteorder
);
Convert a string from UTF-16 to UTF-8. The result will be terminated with a 0 byte.
This functions differs from g_utf16_to_utf8()
mainly by the handling of byte order. In particular, the caller
specifies the byte order explicitly and it can differ from the native byte order.
It is possible to pass GWY_BYTE_ORDER_IMPLICIT
as byteorder
. In such case str
is checked for a byte-order mark.
When one is present it is used for the byte order. Otherwise the behaviour is the same as for
GWY_BYTE_ORDER_NATIVE
. The output string never begins with a byte-order mark.
Conversion failure is indicated just by a NULL
return value. Conversion is either completely successful or fails.
Use g_utf16_to_utf8()
if you need to handle partial conversions and failure details.
gchar * gwy_utf8_strescape (const gchar *source
,const gchar *exceptions
);
Escapes special characters in a string.
Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\' and '"' in the string source by writing them using the above-mentioned escape sequences or inserting a '\' before them. Additionally all characters in the range 0x01-0x1F (everything below SPACE), the character 0x7F, characters 0xC0 and 0xC1, and all characters in the range 0xF5-0xFF are replaced with a '\' followed by their octal representation. Characters supplied in exceptions are not escaped.
In essence, this functions differs from g_strescape()
by preserving valid UTF-8 strings, unless they contain ‘odd’
characters. Passing strings which are not valid UTF-8 is possible, but generally not advised.
Function g_strcompress()
does the reverse conversion.
gboolean gwy_assign_string (gchar **target
,const gchar *newvalue
);
Assigns a string, checking for equality and handling NULL
s.
This function simplifies handling of string value setters.
The new value is duplicated and the old string is freed in a safe manner (it is possible to pass a pointer
somewhere within the old value as the new value, for instance). Any of the old and new value can be NULL
. If
both values are equal (including both unset), the function returns FALSE
.
gboolean gwy_assign_gstring (GString *str
,const gchar *newvalue
);
Assings a string to a GString.
This function is very similar to g_string_assign()
, with two exceptions.
First, the new value can be NULL
, with the same meaning as an empty string. It makes gwy_assign_gstring()
simpler
and less error prone to use if the string originates from some getter which may also return a NULL
.
Second, the return value indicates whether the string has changed. It makes it less useful for chaining string operations but more useful for chaining logic and creating fast paths.
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 |
|
... |
|
gboolean gwy_set_member_object (gpointer instance
,gpointer member_object
,GType expected_type
,gpointer member_field
,...
);
Replaces a member object of another object, handling signal connection and disconnection.
If member_object
is not NULL
a reference is taken, sinking any floating objects (and conversely, the reference to
the previous member object is released).
The purpose is to simplify bookkeeping in classes that have settable member objects and (usually but not necessarily) need to connect to some signals of these member objects. Since this function both connects and disconnects signals it must be always called with the same set of signals, including callbacks and flags, for a specific member object.
Example for a GwyFoo class owning a GwyGradient member object, assuming the usual conventions:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
typedef struct _GwyFooPrivate GwyFooPrivate; struct _GwyFooPrivate { GwyGradient *gradient; gulong gradient_data_changed_id; }; static gboolean set_gradient(GwyFoo *foo) { GwyFooPrivate *priv = G_TYPE_INSTANCE_GET_PRIVATE(foo, GWY_TYPE_FOO, GwyFooPrivate); if (!gwy_set_member_object(foo, gradient, GWY_TYPE_GRADIENT, &priv->gradient, "data-changed", &foo_gradient_data_changed, &priv->gradient_data_changed_id, G_CONNECT_SWAPPED, NULL)) return FALSE; // Do whatever else needs to be done if the gradient changes. return TRUE; } |
The gradient setter then usually only calls
and disposing of the member object
again only calls set_gradient()
but with set_gradient()
NULL
gradient.
instance |
An object instance. |
|
member_object |
Another object to be owned by |
|
expected_type |
The type of |
|
member_field |
Pointer to location storing the current member object to be replaced by |
|
... |
List of quadruplets of the form signal name, GCallback callback, gulong pointer to location to hold the signal handler id, and GConnectFlags connection flags. |
FILE * gwy_fopen (const gchar *filename
,const gchar *mode
);
A wrapper for the stdio fopen()
function. The fopen()
function opens a file and associates a new stream with it.
Because file descriptors are specific to the C library on Windows, and a file descriptor is part of the FILE
struct, the FILE* returned by this function makes sense only to functions in the same C library. Thus if the
GLib-using code uses a different C library than GLib does, the FILE* returned by this function cannot be passed to
C library functions like fprintf()
or fread()
.
See your C library manual for more details about fopen()
.
gint gwy_fprintf (FILE *file
,gchar const *format
,...
);
An implementation of the standard fprintf()
function which supports positional parameters, as specified in the
Single Unix Specification.
Type of flags passed to gwy_parse_doubles()
.
Do not set error (and return |
||
For unknown number of values, consider an error when they are followed by non-numerical garbage. This flag has no effect for a known number of values. |
||
Do not distinguish line breaks from other whitespace; just read the requested number of values. For an unknown number of values they will be reported as single-column. |
Type of error which can occur in gwy_parse_doubles()
.