Macros: Gwyddion Library Reference Manual

## Macros Macros — General utility macros |

## Functions

#define | gwy_NC()
#define | gwy_C()
#define | GWY_SWAP()
#define | GWY_ORDER()
#define | gwy_strequal()
#define | GWY_CLAMP()
#define | gwy_clear()
#define | gwy_clear1()
#define | gwy_assign()
#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

### gwy_NC()

    #define gwy_NC(context, string) context "\004" string

Form a source code prefixed translatable message.

The macro expands to `context` and `string` joined by `"\004"`. It is similar to the standard `NC_()` macro, but it is also very different because `NC_()` drops the context. The actual translation functions expect you to provide it again. This macro creates a string which carries the context and can be used with a function such as `gwy_sgettext()` or macro `gwy_C()`.

#### Parameters

context | Translation context. |
string | Translatable message. |

### gwy_C()

    #define gwy_C(string) gwy_sgettext(GETTEXT_PACKAGE, string)

Translate a prefixed translatable message in the default domain.

The macro expands to `gwy_sgettext()` with the first argument set to GETTEXT_DOMAIN. It thus relies on GETTEXT_DOMAIN being correctly defined where the macro is used. See `gwy_sgettext()` documentation for a discussion where this can be a useful function and where you should stick to the standard `C_()` macro.

#### Parameters

string | Translatable message. |

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

arr | 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

str | 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)

Standard property flags (read, write, static strings and explicitit notify).

Most object properties have the same standard GParamSpecFlags: `G_PARAM_READWRITE`, `G_PARAM_STATIC_STRINGS` and `G_PARAM_EXPLICIT_NOTIFY` (some of them being combinations of multiple flags themselves). This macro can be used to write them in a concise manner.

## See Also

utils -- utility functions