[gtk/wip/otte/listview: 9/155] Add GtkOrdering

[Benjamin Otte <otte src gnome org>]

commit d6c83a2881edf471ea55840b1c48813e672c4095
Author: Benjamin Otte <otte redhat com>
Date:   Thu Dec 12 05:16:31 2019 +0100

    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 |  2 ++
 gtk/gtkenums.h                       | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+)
---
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 02417b0004..553367c343 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -5054,6 +5054,8 @@ GtkDeleteType
 GtkDirectionType
 GtkJustification
 GtkMovementStep
+GtkOrdering
+gtk_ordering_from_cmpfunc
 GtkOrientation
 GtkPackType
 GtkPositionType
diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h
index edf1c2d373..76c2e33352 100644
--- a/gtk/gtkenums.h
+++ b/gtk/gtkenums.h
@@ -607,6 +607,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.