gwymacros

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_clear1()
#define gwy_assign()
#define GWY_SI_VALUE_FORMAT_FREE()
#define GWY_FREE_ARRAY()
#define GWY_FREE_STRING()
#define GWY_FREE()
#define gwy_debug()
#define gwy_info()
void gwy_debug_gnu ()

Types and Values

#define GWY_GPARAM_RWE

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 .

 

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 a 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. See gwy_clear1() for a more convenient macro for clearing a single variable.

Parameters

array

Pointer to an array of values to clear.

 

n

Number of items to clear.

 

gwy_clear1()

#define             gwy_clear1(var)

Fills the memory occupied by a single variable with zeroes.

This is a shorthand for memset(), with the number of bytes to fill calculated from the type of the variable. See gwy_clear() for clearing arrays and/or passing the address already as a pointer.

Parameters

var

A variable name (or other l-value expression). The argument is the variable itself, not a pointer to it.

 

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.

 

GWY_SI_VALUE_FORMAT_FREE()

#define             GWY_SI_VALUE_FORMAT_FREE(vf)

GWY_FREE_ARRAY()

#define             GWY_FREE_ARRAY(arr)

Frees and nulls a pointer to a GArray if it exists.

The array memory must have been allocated using g_array_new() or a similar function.

If ptr is not NULL, g_array_free() is called on it, freeing also array data, 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 GArray pointer to free or NULL.

 

GWY_FREE_STRING()

#define             GWY_FREE_STRING(str)

Frees and nulls a pointer to a GString if it exists.

The array memory must have been allocated using g_string_new() or a similar function.

If ptr is not NULL, g_string_free() is called on it, freeing also string data, 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 GString pointer to free or NULL.

 

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.

 

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.

 

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_GPARAM_RWE

#define GWY_GPARAM_RWE (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY)

See Also

gwyutils -- utility functions