Provide new API function to determine how much buffer space remains in the instance

t/02getkey.c

@@ -8,7 +8,7 @@ int main(int argc, char *argv[])
   TermKey   *tk;
   TermKeyKey key;
 
-  plan_tests(19);
+  plan_tests(29);
 
   pipe(fd);
 
@@ -17,6 +17,8 @@ int main(int argc, char *argv[])
 
   tk = termkey_new(fd[0], TERMKEY_FLAG_NOTERMIOS);
 
+  is_int(termkey_get_buffer_remaining(tk), 256, "buffer free initially 256");
+
   is_int(termkey_getkey(tk, &key), TERMKEY_RES_NONE, "getkey yields RES_NONE when empty");
 
   write(fd[1], "h", 1);
@@ -25,6 +27,8 @@ int main(int argc, char *argv[])
 
   is_int(termkey_advisereadable(tk), TERMKEY_RES_AGAIN, "advisereadable yields RES_AGAIN after h");
 
+  is_int(termkey_get_buffer_remaining(tk), 255, "buffer free 255 after advisereadable");
+
   is_int(termkey_getkey(tk, &key), TERMKEY_RES_KEY, "getkey yields RES_KEY after h");
 
   is_int(key.type,        TERMKEY_TYPE_UNICODE, "key.type after h");
@@ -32,6 +36,8 @@ int main(int argc, char *argv[])
   is_int(key.modifiers,   0,                    "key.modifiers after h");
   is_str(key.utf8,        "h",                  "key.utf8 after h");
 
+  is_int(termkey_get_buffer_remaining(tk), 256, "buffer free 256 after getkey");
+
   is_int(termkey_getkey(tk, &key), TERMKEY_RES_NONE, "getkey yields RES_NONE a second time");
 
   write(fd[1], "\x01", 1);
@@ -54,6 +60,24 @@ int main(int argc, char *argv[])
   is_int(key.code.sym,    TERMKEY_SYM_UP,       "key.code.sym after Up");
   is_int(key.modifiers,   0,                    "key.modifiers after Up");
 
+  write(fd[1], "\eO", 2);
+  termkey_advisereadable(tk);
+
+  is_int(termkey_get_buffer_remaining(tk), 254, "buffer free 254 after partial write");
+
+  is_int(termkey_getkey(tk, &key), TERMKEY_RES_AGAIN, "getkey yields RES_AGAIN after partial write");
+
+  write(fd[1], "C", 1);
+  termkey_advisereadable(tk);
+
+  is_int(termkey_getkey(tk, &key), TERMKEY_RES_KEY, "getkey yields RES_KEY after Right completion");
+
+  is_int(key.type,        TERMKEY_TYPE_KEYSYM,  "key.type after Right");
+  is_int(key.code.sym,    TERMKEY_SYM_RIGHT,    "key.code.sym after Right");
+  is_int(key.modifiers,   0,                    "key.modifiers after Right");
+
+  is_int(termkey_get_buffer_remaining(tk), 256, "buffer free 256 after completion");
+
   termkey_destroy(tk);
 
   return exit_status();

termkey.c

@@ -425,6 +425,13 @@ void termkey_set_canonflags(TermKey *tk, int flags)
     tk->flags &= ~TERMKEY_FLAG_SPACESYMBOL;
 }
 
+size_t termkey_get_buffer_remaining(TermKey *tk)
+{
+  /* Return the total number of free bytes in the buffer, because that's what
+   * is available to the user. */
+  return tk->buffsize - tk->buffcount;
+}
+
 static void eat_bytes(TermKey *tk, size_t count)
 {
   if(count >= tk->buffcount) {

termkey.h.in

@@ -171,6 +171,8 @@ void termkey_set_waittime(TermKey *tk, int msec);
 int  termkey_get_canonflags(TermKey *tk);
 void termkey_set_canonflags(TermKey *tk, int);
 
+size_t termkey_get_buffer_remaining(TermKey *tk);
+
 void termkey_canonicalise(TermKey *tk, TermKeyKey *key);
 
 TermKeyResult termkey_getkey(TermKey *tk, TermKeyKey *key);

termkey_get_buffer_remaining.3

@@ -0,0 +1,20 @@
+.TH TERMKEY_GET_BUFFER_REMAINING 3
+.SH NAME
+termkey_get_buffer_remaining \- returns the free buffer space
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "size_t termkey_get_buffer_remaining(TermKey *" tk ");
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+A termkey instance contains a buffer of pending bytes that have been read by \fBtermkey_advisereadable\fP(3) but not yet consumed by \fBtermkey_getkey\fP(3). \fBtermkey_get_buffer_remaining\fP() returns the number of bytes of buffer space currently free in the termkey instance.
+.PP
+.SH "RETURN VALUE"
+\fBtermkey_get_buffer_remaining\fP() returns a size in bytes.
+.SH "SEE ALSO"
+.BR termkey_new (3),
+.BR termkey_advisereadable (3),
+.BR termkey_getkey (3)

termkey_new.3

@@ -56,4 +56,5 @@ If successful, \fBtermkey_new\fP() returns a pointer to the new instance. On fai
 .BR termkey_advisereadable (3),
 .BR termkey_getkey (3),
 .BR termkey_get_flags (3),
-.BR termkey_get_fd (3)
+.BR termkey_get_fd (3),
+.BR termkey_get_buffer_remaining (3)