gwymacros: Gwyddion Library Reference Manual

## 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_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