Provide termkey_keycmp() for sorting purposes

4 files changed, 102 insertions, 0 deletions

diff --git a/t/13cmpkey.c b/t/13cmpkey.c
new file mode 100644
index 0000000..75f5ad7
--- /dev/null
+++ b/t/13cmpkey.c
@@ -0,0 +1,50 @@
+#include "../termkey.h"
+#include "taplib.h"
+
+int main(int argc, char *argv[])
+{
+  TermKey   *tk;
+  TermKeyKey key1, key2;
+
+  plan_tests(10);
+
+  tk = termkey_new(0, TERMKEY_FLAG_NOTERMIOS);
+
+  key1.type = TERMKEY_TYPE_UNICODE;
+  key1.code.codepoint = 'A';
+  key1.modifiers = 0;
+
+  is_int(termkey_keycmp(tk, &key1, &key1), 0, "cmpkey same structure");
+
+  key2.type = TERMKEY_TYPE_UNICODE;
+  key2.code.codepoint = 'A';
+  key2.modifiers = 0;
+
+  is_int(termkey_keycmp(tk, &key1, &key2), 0, "cmpkey identical structure");
+
+  key2.modifiers = TERMKEY_KEYMOD_CTRL;
+
+  ok(termkey_keycmp(tk, &key1, &key2) > 0, "cmpkey orders CTRL after nomod");
+  ok(termkey_keycmp(tk, &key2, &key1) < 0, "cmpkey orders nomod before CTRL");
+
+  key2.code.codepoint = 'B';
+  key2.modifiers = 0;
+
+  ok(termkey_keycmp(tk, &key1, &key2) > 0, "cmpkey orders 'B' after 'A'");
+  ok(termkey_keycmp(tk, &key2, &key1) < 0, "cmpkey orders 'A' before 'B'");
+
+  key1.modifiers = TERMKEY_KEYMOD_CTRL;
+
+  ok(termkey_keycmp(tk, &key1, &key2) > 0, "cmpkey orders nomod 'B' after CTRL 'A'");
+  ok(termkey_keycmp(tk, &key2, &key1) < 0, "cmpkey orders CTRL 'A' before nomod 'B'");
+
+  key2.type = TERMKEY_TYPE_KEYSYM;
+  key2.code.sym = TERMKEY_SYM_UP;
+
+  ok(termkey_keycmp(tk, &key1, &key2) > 0, "cmpkey orders KEYSYM after UNICODE");
+  ok(termkey_keycmp(tk, &key2, &key1) < 0, "cmpkey orders UNICODE before KEYSYM");
+
+  termkey_destroy(tk);
+
+  return exit_status();
+}
diff --git a/termkey.c b/termkey.c
index 7995871..384b5a4 100644
--- a/termkey.c
+++ b/termkey.c
@@ -1144,3 +1144,29 @@ char *termkey_strpkey(TermKey *tk, const char *str, TermKeyKey *key, TermKeyForm
 
   return (char *)str;
 }
+
+int termkey_keycmp(TermKey *tk, const TermKeyKey *key1, const TermKeyKey *key2)
+{
+  if(key1->type != key2->type)
+    return key2->type - key1->type;
+
+  switch(key1->type) {
+    case TERMKEY_TYPE_UNICODE:
+      if(key1->code.codepoint != key2->code.codepoint)
+        return key2->code.codepoint - key1->code.codepoint;
+    case TERMKEY_TYPE_KEYSYM:
+      if(key1->code.sym != key2->code.sym)
+        return key2->code.sym - key1->code.sym;
+    case TERMKEY_TYPE_FUNCTION:
+      if(key1->code.number != key2->code.number)
+        return key2->code.number - key1->code.number;
+    case TERMKEY_TYPE_MOUSE:
+      {
+        int cmp = strncmp(key2->code.mouse, key1->code.mouse, 4);
+        if(cmp != 0)
+          return cmp;
+      }
+  }
+
+  return key2->modifiers - key1->modifiers;
+}
diff --git a/termkey.h.in b/termkey.h.in
index c4e9cb2..c91f954 100644
--- a/termkey.h.in
+++ b/termkey.h.in
@@ -193,6 +193,8 @@ typedef enum {
 size_t  termkey_strfkey(TermKey *tk, char *buffer, size_t len, TermKeyKey *key, TermKeyFormat format);
 char   *termkey_strpkey(TermKey *tk, const char *str, TermKeyKey *key, TermKeyFormat format);
 
+int termkey_keycmp(TermKey *tk, const TermKeyKey *key1, const TermKeyKey *key2);
+
 // Old name for termkey_strfkey()
 size_t termkey_snprint_key(TermKey *tk, char *buffer, size_t len, TermKeyKey *key, TermKeyFormat format);
 
diff --git a/termkey_keycmp.3 b/termkey_keycmp.3
new file mode 100644
index 0000000..519752b
--- /dev/null
+++ b/termkey_keycmp.3
@@ -0,0 +1,24 @@
+.TH TERMKEY_KEYCMP 3
+.SH NAME
+termkey_keycmp \- compare two key events
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "int termkey_keycmp(TermKey *" tk ", const TermKeyKey *" key1 ",
+.BI "             const TermKeyKey *" key2 );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_keycmp\fP compares two key structures and applies a total ordering, returning a value that is positive, zero, or negative, to indicate if the given structures are increasing, identical, or decreasing.
+.PP
+Two structures of differing type are ordered \fBTERMKEY_TYPE_UNICODE\fP, \fBTERMKEY_TYPE_KEYSYM\fP, \fBTERMKEY_TYPE_FUNCTION\fP, \fBTERMKEY_TYPE_MOUSE\fP. Unicode structures are ordered by codepoint, keysym structures are ordered by keysym number, function structures are ordered by function key number, and mouse structures are ordered opaquely by an unspecified but consistent ordering. Within these values, keys different in modifier bits are ordered by the modifiers.
+.SH "RETURN VALUE"
+\fBtermkey_keycmp\fP() returns an integer greater than, equal to, or less than zero to indicate the relation between the two given key structures.
+.SH NOTES
+This function does not perform any canonicalisation of the key structures, and performs a simple comparison of the fields in the structures. In particular, it will not consider as equal \fBTERMKEY_TYPE_UNICODE\fP containing the Space codepoint (U+0020) vs. \fBTERMKEY_TYPE_KEYSYM\fP containing \fBTERMKEY_SYM_SPACE\fP. 
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_getkey (3)
+.BR termkey_strpkey (3)