diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index 32a7664e8..1a5c9fa5e 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -219,6 +219,7 @@ MAX ABS CLAMP +G_APPROX_VALUE G_STRUCT_MEMBER diff --git a/glib/docs.c b/glib/docs.c index 080c1b0de..5a786311c 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -1788,6 +1788,26 @@ * Returns: the value of @x clamped to the range between @low and @high */ +/** + * G_APPROX_VALUE: + * @a: a numeric value + * @b: a numeric value + * @epsilon: a numeric value that expresses the tolerance between @a and @b + * + * 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 + * + * Returns: %TRUE if the two values are within the desired range + * + * Since: 2.58 + */ + /** * G_STRUCT_MEMBER: * @member_type: the type of the struct field diff --git a/glib/gmacros.h b/glib/gmacros.h index 0e180bb09..cfeb9a00b 100644 --- a/glib/gmacros.h +++ b/glib/gmacros.h @@ -329,6 +329,9 @@ #undef CLAMP #define CLAMP(x, low, high) (((x) > (high)) ? (high) : (((x) < (low)) ? (low) : (x))) +#define G_APPROX_VALUE(a, b, epsilon) \ + (((a) > (b) ? (a) - (b) : (b) - (a)) < (epsilon)) + /* Count the number of elements in an array. The array must be defined * as such; using this with a dynamically allocated array will give * incorrect results.