Add GtkOrdering

This is an enum that we're gonna use soon and it's worth introducing as a
separate commit.

The intention is to have meaningful names for return values in
comparison functions.

docs/reference/gtk/gtk4-sections.txt

@@ -4638,6 +4638,8 @@ GtkDeleteType
 GtkDirectionType
 GtkJustification
 GtkMovementStep
+GtkOrdering
+gtk_ordering_from_cmpfunc
 GtkOrientation
 GtkPackType
 GtkPositionType

gtk/gtkenums.h

@@ -550,6 +550,39 @@ typedef enum
   GTK_NUMBER_UP_LAYOUT_BOTTOM_TO_TOP_RIGHT_TO_LEFT  /*< nick=btrl >*/
 } GtkNumberUpLayout;
 
+/**
+ * GtkOrdering:
+ * @GTK_ORDERING_SMALLER: the first value is smaller than the second
+ * @GTK_ORDERING_EQUAL: the two values are equal
+ * @GTK_ORDERING_LARGER: the first value is larger than the second
+ *
+ * Describes the way two values can be compared.
+ *
+ * These values can be used with a #GCompareFunc. However, a
+ * #GCompareFunc is allowed to return any integer values.  
+ * For converting such a value to a #GtkOrdering, use
+ * gtk_ordering_from_cmpfunc().
+ */
+typedef enum {
+  GTK_ORDERING_SMALLER = -1,
+  GTK_ORDERING_EQUAL = 0,
+  GTK_ORDERING_LARGER = 1
+} GtkOrdering;
+
+/**
+ * gtk_ordering_from_cmpfunc:
+ * @cmpfunc_result: Result of a comparison function
+ *
+ * Converts the result of a #GCompareFunc like strcmp() to a #GtkOrdering.
+ *
+ * Returns: the corresponding #GtkOrdering
+ **/
+static inline GtkOrdering
+gtk_ordering_from_cmpfunc (int cmpfunc_result)
+{
+  return (GtkOrdering) ((cmpfunc_result > 0) - (cmpfunc_result < 0));
+}
+
 /**
  * GtkPageOrientation:
  * @GTK_PAGE_ORIENTATION_PORTRAIT: Portrait mode.