## gwymacros

gwymacros — Utility macros

## Synopsis

    #include <libgwyddion/gwyddion.h>

    #define             gettext                             (x)
    #define             ngettext                            (sing, plur, n)
    #define             _                                   (x)
    #define             N_                                  (x)
    #define             GWY_SWAP                            (t, x, y)
    #define             gwy_strequal                        (a, b)
    #define             GWY_CLAMP                           (x, low, hi)
    #define             gwy_object_unref                    (obj)
    #define             gwy_signal_handler_disconnect       (obj, hid)
    #define             GWY_FIND_PSPEC                      (type, id, spectype)
    #define             gwy_debug                           (format...)
    void                gwy_debug_gnu                       (const gchar *domain,
                                                             const gchar *fileline,
                                                             const gchar *funcname,
                                                             const gchar *format,
                                                             ...);

## Description

## Details

### gettext()

    #define gettext(x) (x)

`x` : |

### ngettext()

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

`sing` : |
`plur` : |
`n` : |

### _()

    #define _(x) gettext(x)

`x` : |

### N_()

    #define             N_(x)

`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.

`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_strequal()

    #define             gwy_strequal(a, b)

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

`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()`.

`x` : | The value to clamp.
`low` : | The minimum value allowed.
`hi` : | The maximum value allowed.

### gwy_object_unref()

    #define             gwy_object_unref(obj)

Unreferences an object if it exists.

If `obj` is not `NULL`, `g_object_unref()` is called on it. In all cases `obj` is set to `NULL`.

A useful property of this macro is its idempotence.

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

`obj` : | A pointer to GObject or `NULL` (must be an l-value).

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

A useful property of this macro is its idempotence.

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

### 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`).

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

### gwy_debug()

    #define             gwy_debug(format...)

Prints a debugging message.

Does nothing if compiled without DEBUG defined.

`format...` : | A format string followed by stuff to print.

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

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

## See Also

gwyutils -- utility functions