gwymacros (HEAD)

gwymacros — Utility macros

Functions

#define	gettext()
#define	ngettext()
#define	_()
#define	N_()
#define	GWY_SWAP()
#define	GWY_ORDER()
#define	gwy_strequal()
#define	GWY_CLAMP()
#define	gwy_clear()
#define	gwy_assign()
#define	GWY_OBJECT_UNREF()
#define	GWY_SIGNAL_HANDLER_DISCONNECT()
#define	GWY_FIND_PSPEC()
#define	GWY_SI_VALUE_FORMAT_FREE()
#define	GWY_FREE()
#define	gwy_debug()
#define	gwy_info()
void	gwy_debug_gnu ()

Types and Values

#define	gwy_object_unref
#define	gwy_signal_handler_disconnect

Includes

#include <libgwyddion/gwyddion.h>

Description

Functions

gettext()

#define gettext(x) (x)

ngettext()

#define ngettext(sing, plur, n) ((n) == 1 ? (sing) : (plur))

_()

#define _(x) gettext(x)

N_()

#define N_(x) gettext_noop(x)

GWY_SWAP()

#define             GWY_SWAP(t, x, y)

Swaps two variables (more precisely lhs and rhs expressions) of type t in a single statement.

Both x and y are evaluated multiple times as both lhs and rhs expressions. If their evaluation has any side effect the result is undefined.

Parameters

t	A C type.
x	A variable of type t to swap with x .
y	A variable of type t to swap with y .

GWY_ORDER()

#define             GWY_ORDER(t, x, y)

Ensures ascending order of two variables (more precisely lhs and rhs expressions) of type t in a single statement.

The macro makes y not smaller than x . They may be still equal or their relation can be undefined (if either is NaN).

Both x and y are evaluated multiple times as both lhs and rhs expressions. If their evaluation has any side effect the result is undefined.

Parameters

t	A C type.
x	A variable of type t to possibly swap with x .
y	A variable of type t to possibly swap with y .

Since: 2.62

gwy_strequal()

#define             gwy_strequal(a, b)

Expands to TRUE if strings are equal, to FALSE otherwise.

Parameters

a	A string.
b	Another string.

GWY_CLAMP()

#define             GWY_CLAMP(x, low, hi)

Ensures that x is between the limits set by low and hi .

This macro differs from GLib's CLAMP() by G_UNLIKELY() assertions on the tests that x is smaller than low and larger than hi . This makes x already being in the right range the fast code path.

It is supposed to be used on results of floating-point operations that should fall to a known range but may occasionaly fail to due to rounding errors and in similar situations. Under normal circumstances, use CLAMP().

Parameters

x	The value to clamp.
low	The minimum value allowed.
hi	The maximum value allowed.

gwy_clear()

#define             gwy_clear(array, n)

Fills memory block representing an array with zeroes.

This is a shorthand for memset(), with the number of bytes to fill calculated from the type of the pointer.

Parameters

array	Pointer to an array of values to clear. This argument may be evaluated several times.
n	Number of items to clear.

Since: 2.12

gwy_assign()

#define             gwy_assign(dest, source, n)

Copies items from one memory block representing an array to another.

This is a shorthand for memcpy(), with the number of bytes to fill calculated from the type of the dest pointer (the type of source does not enter the calculation!)

As with memcpy(), the memory blocks may not overlap.

Parameters

dest	Pointer to the destination array of values. This argument may be evaluated several times.
source	Pointer to the source array of values.
n	Number of items to copy.

Since: 2.46

GWY_OBJECT_UNREF()

#define             GWY_OBJECT_UNREF(obj)

Unreferences and nulls an object if it exists.

If obj is not NULL, g_object_unref() is called on it and NULL is assigned to the variable. In all cases obj will be NULL at the end.

A useful property of this macro is its idempotence.

If the object reference count is greater than one, ensure it should be referenced elsewhere, otherwise it leaks memory.

Parameters

obj

A pointer to GObject or NULL (must be an l-value).

Since: 2.46

GWY_SIGNAL_HANDLER_DISCONNECT()

#define             GWY_SIGNAL_HANDLER_DISCONNECT(obj, hid)

Disconnect a signal handler if it exists.

If hid is nonzero and obj is not NULL, the signal handler identified by hid is disconnected. In all cases hid is set to 0 while obj is not changed.

A useful property of this macro is its idempotence.

If you pass non-zero hid but NULL obj you are probably doing something wrong because you keep and try to disconnect a handler for a non-existent object. A warning may be emitted in the future.

Parameters

obj	A pointer to GObject or NULL.
hid	An obj signal handler id or 0 (must be an l-value).

Since: 2.46

GWY_FIND_PSPEC()

#define             GWY_FIND_PSPEC(type, id, spectype)

A convenience g_object_class_find_property() wrapper.

It expands to property spec cast to correct type (spec ).

Parameters

type	Object type (e.g. GWY_TYPE_CONTAINER).
id	Property id.
spectype	Param spec type (e.g. DOUBLE).

GWY_SI_VALUE_FORMAT_FREE()

#define             GWY_SI_VALUE_FORMAT_FREE(vf)

Frees and nulls a value format if it exists.

If vf is not NULL, gwy_si_unit_value_format_free() is called on it and NULL is assigned to the variable. In all cases vf will be NULL at the end.

A useful property of this macro is its idempotence.

Parameters

vf

A value format to free or NULL.

Since: 2.46

GWY_FREE()

#define             GWY_FREE(ptr)

Frees and nulls a pointer if it exists.

The memory must have been allocated using one of the g_new() and g_malloc() class of functions.

If ptr is not NULL, g_free() is called on it and NULL is assigned to the variable. In all cases ptr will be NULL at the end.

A useful property of this macro is its idempotence.

Parameters

ptr

A pointer to free or NULL.

Since: 2.46

gwy_debug()

#define             gwy_debug(format...)

Emits a debugging message to the program log.

The message is amended with additional information such as source file, line number or time (when possible) and emitted at log level G_LOG_LEVEL_DEBUG via g_log().

It should be noted that the default GLib log handler discards G_LOG_LEVEL_DEBUG messages but the default Gwyddion handler does not.

The macro expands to nothing if compiled without DEBUG defined.

Parameters

...

Format string, as in printf(), followed by arguments.

gwy_info()

#define             gwy_info(format...)

Emits an informational message.

The message is emitted at log level G_LOG_LEVEL_INFO via g_log(). This macro is primarily meant for reporting of non-fatal issues in file import modules.

It should be noted that the default GLib log handler discards G_LOG_LEVEL_INFO messages but the default Gwyddion handler does not.

Parameters

...

Format string, as in printf(), followed by arguments.

Since: 2.45

gwy_debug_gnu ()

void
gwy_debug_gnu (const gchar *domain,
               const gchar *fileline,
               const gchar *funcname,
               const gchar *format,
               ...);

Print a debugging message.

To be used via gwy_debug(), should not be used directly.

Parameters

domain	Log domain.
fileline	File and line info.
funcname	Function name.
format	Message format.
...	Message parameters.

Types and Values

gwy_object_unref

#define gwy_object_unref GWY_OBJECT_UNREF

Unreferences and nulls an object if it exists.

Legacy name for GWY_OBJECT_UNREF.

Parameters

obj

A pointer to GObject or NULL (must be an l-value).

gwy_signal_handler_disconnect

#define gwy_signal_handler_disconnect GWY_SIGNAL_HANDLER_DISCONNECT

Disconnect a signal handler if it exists.

Legacy name for GWY_SIGNAL_HANDLER_DISCONNECT.

Parameters

obj	A pointer to GObject or NULL.
hid	An obj signal handler id or 0 (must be an l-value).

See Also

gwyutils -- utility functions