Standard Macros

Standard Macros — commonly-used macros

Functions

#define G_IS_DIR_SEPARATOR()
#define MIN()
#define MAX()
#define ABS()
#define CLAMP()
#define G_APPROX_VALUE()
#define G_SIZEOF_MEMBER()
#define G_STRUCT_MEMBER()
#define G_STRUCT_MEMBER_P()
#define G_STRUCT_OFFSET()
#define G_ALIGNOF()
#define G_N_ELEMENTS()

Types and Values

#define G_OS_WIN32
#define G_OS_UNIX
#define G_DIR_SEPARATOR
#define G_DIR_SEPARATOR_S
#define G_SEARCHPATH_SEPARATOR
#define G_SEARCHPATH_SEPARATOR_S
#define TRUE
#define FALSE
#define NULL
#define G_MEM_ALIGN
#define G_CONST_RETURN
#define G_NORETURN
#define G_NORETURN_FUNCPTR
#define G_ALWAYS_INLINE
#define G_NO_INLINE

Includes

#include <glib.h>

Description

These macros provide a few commonly-used features.

Functions

G_IS_DIR_SEPARATOR()

#define G_IS_DIR_SEPARATOR(c) ((c) == G_DIR_SEPARATOR || (c) == '/')

Checks whether a character is a directory separator. It returns TRUE for '/' on UNIX machines and for '\' or '/' under Windows.

Parameters

c

a character

 

Since: 2.6


MIN()

#define MIN(a, b)  (((a) < (b)) ? (a) : (b))

Calculates the minimum of a and b .

Parameters

a

a numeric value

 

b

a numeric value

 

Returns

the minimum of a and b .


MAX()

#define MAX(a, b)  (((a) > (b)) ? (a) : (b))

Calculates the maximum of a and b .

Parameters

a

a numeric value

 

b

a numeric value

 

Returns

the maximum of a and b .


ABS()

#define ABS(a)	   (((a) < 0) ? -(a) : (a))

Calculates the absolute value of a . The absolute value is simply the number with any negative sign taken away.

For example,

  • ABS(-10) is 10.

  • ABS(10) is also 10.

Parameters

a

a numeric value

 

Returns

the absolute value of a .


CLAMP()

#define CLAMP(x, low, high)  (((x) > (high)) ? (high) : (((x) < (low)) ? (low) : (x)))

Ensures that x is between the limits set by low and high . If low is greater than high the result is undefined.

For example,

  • CLAMP(5, 10, 15) is 10.

  • CLAMP(15, 5, 10) is 10.

  • CLAMP(20, 15, 25) is 20.

Parameters

x

the value to clamp

 

low

the minimum value allowed

 

high

the maximum value allowed

 

Returns

the value of x clamped to the range between low and high


G_APPROX_VALUE()

#define             G_APPROX_VALUE(a, b, epsilon)

Evaluates to a truth value if the absolute difference between a and b is smaller than epsilon , and to a false value otherwise.

For example,

  • G_APPROX_VALUE (5, 6, 2) evaluates to true

  • G_APPROX_VALUE (3.14, 3.15, 0.001) evaluates to false

  • G_APPROX_VALUE (n, 0.f, FLT_EPSILON) evaluates to true if n is within the single precision floating point epsilon from zero

Parameters

a

a numeric value

 

b

a numeric value

 

epsilon

a numeric value that expresses the tolerance between a and b

 

Returns

TRUE if the two values are within the desired range

Since: 2.58


G_SIZEOF_MEMBER()

#define             G_SIZEOF_MEMBER(struct_type, member)

Returns the size of member in the struct definition without having a declared instance of struct_type .

Parameters

struct_type

a structure type, e.g. GOutputVector

 

member

a field in the structure, e.g. size

 

Returns

the size of member in bytes.

Since: 2.64


G_STRUCT_MEMBER()

#define             G_STRUCT_MEMBER(member_type, struct_p, struct_offset)

Returns a member of a structure at a given offset, using the given type.

Parameters

member_type

the type of the struct field

 

struct_p

a pointer to a struct

 

struct_offset

the offset of the field from the start of the struct, in bytes

 

Returns

the struct member


G_STRUCT_MEMBER_P()

#define             G_STRUCT_MEMBER_P(struct_p, struct_offset)

Returns an untyped pointer to a given offset of a struct.

Parameters

struct_p

a pointer to a struct

 

struct_offset

the offset from the start of the struct, in bytes

 

Returns

an untyped pointer to struct_p plus struct_offset bytes


G_STRUCT_OFFSET()

#define             G_STRUCT_OFFSET(struct_type, member)

Returns the offset, in bytes, of a member of a struct.

Parameters

struct_type

a structure type, e.g. GtkWidget

 

member

a field in the structure, e.g. window

 

Returns

the offset of member from the start of struct_type


G_ALIGNOF()

#define             G_ALIGNOF(type)

Return the minimal alignment required by the platform ABI for values of the given type. The address of a variable or struct member of the given type must always be a multiple of this alignment. For example, most platforms require int variables to be aligned at a 4-byte boundary, so G_ALIGNOF (int) is 4 on most platforms.

Note this is not necessarily the same as the value returned by GCC’s __alignof__ operator, which returns the preferred alignment for a type. The preferred alignment may be a stricter alignment than the minimal alignment.

Parameters

type

a type-name

 

Since: 2.60


G_N_ELEMENTS()

#define G_N_ELEMENTS(arr)		(sizeof (arr) / sizeof ((arr)[0]))

Determines the number of elements in an array. The array must be declared so the compiler knows its size at compile-time; this macro will not work on an array allocated on the heap, only static arrays or arrays on the stack.

Parameters

arr

the array

 

Types and Values

G_OS_WIN32

#define G_OS_WIN32

This macro is defined only on Windows. So you can bracket Windows-specific code in "#ifdef G_OS_WIN32".


G_OS_UNIX

#define G_OS_UNIX

This macro is defined only on UNIX. So you can bracket UNIX-specific code in "#ifdef G_OS_UNIX".


G_DIR_SEPARATOR

#define G_DIR_SEPARATOR '/'

The directory separator character. This is '/' on UNIX machines and '\' under Windows.


G_DIR_SEPARATOR_S

#define G_DIR_SEPARATOR_S "/"

The directory separator as a string. This is "/" on UNIX machines and "\" under Windows.


G_SEARCHPATH_SEPARATOR

#define G_SEARCHPATH_SEPARATOR ':'

The search path separator character. This is ':' on UNIX machines and ';' under Windows.


G_SEARCHPATH_SEPARATOR_S

#define G_SEARCHPATH_SEPARATOR_S ":"

The search path separator as a string. This is ":" on UNIX machines and ";" under Windows.


TRUE

#define TRUE (!FALSE)

Defines the TRUE value for the gboolean type.


FALSE

#define FALSE (0)

Defines the FALSE value for the gboolean type.


NULL

#  define NULL        (0L)

Defines the standard NULL pointer.


G_MEM_ALIGN

#  define G_MEM_ALIGN GLIB_SIZEOF_VOID_P

Indicates the number of bytes to which memory will be aligned on the current platform.


G_CONST_RETURN

#define G_CONST_RETURN GLIB_DEPRECATED_MACRO_IN_2_30_FOR(const)

G_CONST_RETURN has been deprecated since version 2.30 and should not be used in newly-written code.

API providers should replace all existing uses with const and API consumers should adjust their code accordingly

If G_DISABLE_CONST_RETURNS is defined, this macro expands to nothing. By default, the macro expands to const. The macro can be used in place of const for functions that return a value that should not be modified. The purpose of this macro is to allow us to turn on const for returned constant strings by default, while allowing programmers who find that annoying to turn it off. This macro should only be used for return values and for "out" parameters, it doesn't make sense for "in" parameters.


G_NORETURN

# define G_NORETURN __attribute__ ((__noreturn__))

Expands to the GNU C or MSVC noreturn function attribute depending on the compiler. It is used for declaring functions which never return. Enables optimization of the function, and avoids possible compiler warnings.

Note that G_NORETURN supersedes the previous G_GNUC_NORETURN macro, which will eventually be deprecated. G_NORETURN supports more platforms.

Place the attribute before the function declaration as follows:

1
G_NORETURN void g_abort (void);

Since: 2.68


G_NORETURN_FUNCPTR

#define             G_NORETURN_FUNCPTR

Expands to the GNU C or MSVC noreturn function attribute depending on the compiler. It is used for declaring function pointers which never return. Enables optimization of the function, and avoids possible compiler warnings.

Place the attribute before the function declaration as follows:

1
G_NORETURN_FUNCPTR void (*funcptr) (void);

Note that if the function is not a function pointer, you can simply use the G_NORETURN macro as follows:

1
G_NORETURN void g_abort (void);

Since: 2.68


G_ALWAYS_INLINE

#   define G_ALWAYS_INLINE [[gnu::always_inline]]

Expands to the GNU C always_inline or MSVC __forceinline function attribute depending on the compiler. It is used for declaring functions as always inlined, ignoring the compiler optimization levels.

The attribute may be placed before the declaration or definition, right before the static keyword.

1
2
3
4
5
6
G_ALWAYS_INLINE
static int
do_inline_this (void)
{
  ...
}

See the GNU C documentation and the MSVC documentation

Since: 2.74


G_NO_INLINE

#   define G_NO_INLINE [[gnu::noinline]]

Expands to the GNU C or MSVC noinline function attribute depending on the compiler. It is used for declaring functions preventing from being considered for inlining.

Note that G_NO_INLINE supersedes the previous G_GNUC_NO_INLINE macro, which will eventually be deprecated. G_NO_INLINE supports more platforms.

The attribute may be placed before the declaration or definition, right before the static keyword.

1
2
3
4
5
6
G_NO_INLINE
static int
do_not_inline_this (void)
{
  ...
}

Since: 2.74