Miscellaneous macros and inline functions

Miscellaneous macros and inline functions

Stability Level

Unstable, unless otherwise indicated

Functions

Types and Values

Includes

#include <gnuisance/gnui-definitions.h>

Description

These macros provide more specialized features which are not needed so often by application programmers.

Functions

GNUI_PP_CALL()

#define GNUI_PP_CALL(MACRO, ...) MACRO(__VA_ARGS__)

Call a function-like macro

Parameters

MACRO

The function-like macro to call

 

...

The arguments to pass to MACRO

 

Returns

The return value of MACRO


GNUI_PP_EAT()

#define GNUI_PP_EAT(...)

Eat the given preprocessor code

Parameters

...

The preprocessor code to eat

 

GNUI_PP_EXPAND()

#define GNUI_PP_EXPAND(...) __VA_ARGS__

Expand the given preprocessor code

Parameters

...

The preprocessor code to expand

 

Returns

The expanded preprocessor code


GNUI_PP_PASTE2()

#define GNUI_PP_PASTE2(MACRO, ...) GNUI_PP_LITERAL_PASTE2(MACRO, __VA_ARGS__)

Paste together the expansion of two macros

Parameters

MACRO1

The first macro name

 

MACRO2

The second macro name

 

Returns

The expansions of the two macros MACRO1 and MACRO2 pasted together


GNUI_PP_PASTE3()

#define             GNUI_PP_PASTE3(MACRO1, MACRO2, ...)

Paste together the expansion of three macros

Parameters

MACRO1

The first macro name

 

MACRO2

The second macro name

 

MACRO3

The third macro name

 

Returns

The expansions of the three macros MACRO1 , MACRO2 and MACRO3 pasted together


GNUI_PP_STRINGIFY()

#define GNUI_PP_STRINGIFY(MACRO) GNUI_PP_LITERAL_STRINGIFY(MACRO)

Stringify the expansion of a macro

Parameters

MACRO

The macro to stringify after being expanded

 

Returns

The MACRO argument stringified after being expanded


GNUI_PP_BOOL()

#define GNUI_PP_BOOL(COND) _GNUI_PPX_NEGA_(GNUI_PP_BOOL_NOT(COND))

Transform a condition into a literal boolean

Parameters

COND

The condition to check

 

Returns

1 if COND is non-zero or empty, 0 otherwise


GNUI_PP_BOOL_NOT()

#define             GNUI_PP_BOOL_NOT(COND)

Transform a condition into a literal boolean and negate the result

Parameters

COND

The condition to check

 

Returns

0 if COND is non-zero or empty, 1 otherwise


GNUI_PP_IF_NONZERO()

#define             GNUI_PP_IF_NONZERO(COND, ...)

Inline preprocessor if-else

Parameters

COND

The condition to check

 

IF_TRUE

The preprocessor code to expand if COND is non-zero

 

IF_FALSE

The preprocessor code to expand if COND is zero.

[omittable]

Returns

IF_TRUE if COND is non-zero, IF_FALSE otherwise


GNUI_PP_IF_ONE_OR_ZERO()

#define             GNUI_PP_IF_ONE_OR_ZERO(COND, ...)

Check if a condition is exactly one or zero

If COND is neither 0 nor 1 the behavior is undefined.

Parameters

COND

The condition to check

 

IF_TRUE

The preprocessor code to expand if COND is 1

 

IF_FALSE

The preprocessor code to expand if COND is 0.

[omittable]

Returns

IF_TRUE if COND is 1, IF_FALSE if COND is 0


GNUI_PP_LITERAL_PASTE2()

#define GNUI_PP_LITERAL_PASTE2(MACRO, ...) MACRO##__VA_ARGS__

Paste two macro names without expanding them

Parameters

MACRO1

The first macro name

 

MACRO2

The second macro name

 

Returns

The two macro names MACRO1 and MACRO2 pasted together, without performing macro expansion


GNUI_PP_LITERAL_PASTE3()

#define GNUI_PP_LITERAL_PASTE3(MACRO1, MACRO2, ...) MACRO1##MACRO2##__VA_ARGS__

Paste three macro names without expanding them

Parameters

MACRO1

The first macro name

 

MACRO2

The second macro name

 

MACRO3

The third macro name

 

Returns

The three macro names MACRO1 , MACRO2 and MACRO3 pasted together, without performing macro expansion


GNUI_PP_LITERAL_STRINGIFY()

#define GNUI_PP_LITERAL_STRINGIFY(MACRO) #MACRO

Stringify a macro name without expanding it

Parameters

MACRO

The macro name to stringify

 

Returns

The MACRO argument stringified, without expansions


GNUI_PP_WHEN_NONZERO()

#define             GNUI_PP_WHEN_NONZERO(MACRO)

Expand a macro only if non-zero

Parameters

MACRO

The macro to expand

 

Returns

The expansion MACRO only if it is non-zero, nothing otherwise


GNUI_CONTAINER_OF()

#define             GNUI_CONTAINER_OF(PTR, TYPE, MEMBER)

Get the struct that contains the pointed address as one of its members

Parameters

PTR

The pointed address

 

TYPE

The type of struct expected

 

MEMBER

The name of the member the pointed address refers to

 

Returns

The container struct


GNUI_SET_POINTED_VALUE_IF_GIVEN__2_1()

#define             GNUI_SET_POINTED_VALUE_IF_GIVEN__2_1(PTR, VAL)

Set a pointed value only if the pointer is not NULL

Parameters

PTR

The pointer.

[out][optional]

VAL

The value

 

GNUI_SET_IF_GREATER__2_2()

#define             GNUI_SET_IF_GREATER__2_2(VAR, VAL)

Assign a value to a variable only if the value to assign is greater than the current value of the variable

Parameters

VAR

The variable

 

VAL

The value

 

GNUI_NORMALIZE_INT_UINT_CAST__2()

#define             GNUI_NORMALIZE_INT_UINT_CAST__2(UINT)

Sanitize a cast between a signed and an unsigned integer

Parameters

UINT

The unsigned variable to sanitize

 

GNUI_ROUND_UINT_DIVISION__1_2()

#define             GNUI_ROUND_UINT_DIVISION__1_2(NUM, DEN)

Round a division between two unsigned integers without float computations

Parameters

NUM

The numerator

 

DEN

The dividend

 

Returns

The rounded result


GNUI_ROUND_INT_DIVISION__2_3()

#define             GNUI_ROUND_INT_DIVISION__2_3(NUM, DEN)

Round a division between two signed integers

Parameters

NUM

The numerator

 

DEN

The dividend

 

Returns

The rounded result


GNUI_PERPENDICULAR_ORIENTATION()

#define             GNUI_PERPENDICULAR_ORIENTATION(ORIENTATION)

Find the perpendicular GtkOrientation

Returns

The perpendicular GtkOrientation


gnui_list_prepend_llink ()

GList *
gnui_list_prepend_llink (GList * const list,
                         GList * const detached_llink);

Prepend a detached list link to a list

Parameters

list

The doubly-linked list.

[nullable]

detached_llink

A detached list link.

[not nullable]

Returns

The new beginning of the list


gnui_list_u_detach_and_move_to_next ()

GList *
gnui_list_u_detach_and_move_to_next (GList ** const list,
                                     GList ** const llink);

Like gnui_list_detach_and_move_to_next(), but the .prev and .next members of the removed element are not set to NULL (please use it only if you know what you are doing)

Please refer to gnui_list_detach_and_move_to_next() for an example.

Parameters

list

A pointer to the doubly-linked list.

[out][not nullable]

llink

A pointer that before the call must point to the member to remove and which after the call will be set to the next member in the list.

[out][not nullable]

Returns

The removed element


GNUI_LIST_DELETE_AND_MOVE_TO_NEXT()

#define             GNUI_LIST_DELETE_AND_MOVE_TO_NEXT(LIST, LLINK)

Removes a pointed member from a GList, set the pointer to the next member in the list (or to NULL if the list is over) and free the removed element.

This function is only sugar for loops (useful for deleting elements from a list while the loop must keep going).

Writing

1
GNUI_LIST_DELETE_AND_MOVE_TO_NEXT(&list, &current);

is equivalent to writing

1
2
3
4
removed = current;
current = current->next;
list = g_list_remove_link(list, removed);
g_list_free_1(removed);

Parameters

LIST

A pointer to the doubly-linked list.

[out][not nullable]

LLINK

A pointer that before the call must point to the member to remove and which after the call will be set to the next member in the list.

[out][not nullable]

gnui_list_detach_and_move_to_next ()

GList *
gnui_list_detach_and_move_to_next (GList ** const list,
                                   GList ** const llink);

Removes a pointed member from a GList, set the pointer to the next member in the list (or to NULL if the list is over) and return the removed element.

This function is only sugar for loops (useful for removing elements from a list while the loop must keep going).

Writing

1
do_something(gnui_list_detach_and_move_to_next(&list, &current));

is equivalent to writing

1
2
3
4
removed = current;
current = current->next;
list = g_list_remove_link(list, removed);
do_something(removed);

Parameters

list

A pointer to the doubly-linked list.

[out][not nullable]

llink

A pointer that before the call must point to the member to remove and which after the call will be set to the next member in the list.

[out][not nullable]

Returns

The removed element


gnui_lists_are_equal ()

bool
gnui_lists_are_equal (const GList * const list1,
                      const GList * const list2);

Check if two GLists have the same elements in the same order

Parameters

list1

The first list.

[not nullable]

list2

The second list.

[not nullable]

Returns

true if the two lists are equal, false otherwise


gnui_signal_handlers_block_by_func ()

guint
gnui_signal_handlers_block_by_func (const gpointer instance,
                                    const GCallback func,
                                    const gpointer data);

Like g_signal_handlers_block_by_func(), but suppresses the function-pointer-to-object-pointer cast warning

return The number of handlers that matched

Parameters

instance

The GObject instance.

[not nullable]

func

The event handler to block.

[not nullable]

data

The closure data of the handlers' closures.

[nullable]

gnui_signal_handlers_unblock_by_func ()

guint
gnui_signal_handlers_unblock_by_func (const gpointer instance,
                                      const GCallback func,
                                      const gpointer data);

Like g_signal_handlers_unblock_by_func(), but suppresses the function-pointer-to-object-pointer cast warning

Parameters

instance

The GObject instance.

[not nullable]

func

The event handler to unblock.

[not nullable]

data

The closure data of the handlers' closures.

[nullable]

Types and Values

GNUI_GNUC_CONSTRUCTOR

#define GNUI_GNUC_CONSTRUCTOR __attribute__((constructor))

Mark a function as auto-init

Returns

The attribute to include