add notcurses_ucs32_to_utf8()

NEWS.md

@@ -1,6 +1,9 @@
 This document attempts to list user-visible changes and any major internal
 rearrangements of Notcurses.
 
+* 1.7.0 (2020-08-30)
+  * Added `notcurses_ucs32_to_utf8()` conversion helper.
+
 * 1.6.20 (2020-08-30)
   * Added convenience functions `ncplane_y()` and `ncplane_x()`, components
     of longstanding `ncplane_yx()`.

include/notcurses/notcurses.h

@@ -107,6 +107,14 @@ mbswidth(const char* mbs){
   return cols;
 }
 
+// input functions like notcurses_getc() return ucs32-encoded char32_t. convert
+// a series of char32_t to utf8. result must be at least 4 bytes per input
+// char32_t (6 bytes per char32_t will future-proof against Unicode expansion).
+// the number of bytes used is returned, or -1 if passed illegal ucs32, or too
+// small of a buffer.
+API int notcurses_ucs32_to_utf8(const char32_t* ucs32, unsigned ucs32count,
+                                unsigned char* resultbuf, size_t buflen);
+
 // extract these bits to get a channel's alpha value
 #define NCCHANNEL_ALPHA_MASK    0x30000000ull
 // background cannot be highcontrast, only foreground

src/lib/notcurses.c

@@ -12,6 +12,7 @@
 #include <string.h>
 #include <unistd.h>
 #include <stdlib.h>
+#include <unistr.h>
 #include <signal.h>
 #include <locale.h>
 #include <uniwbrk.h>
@@ -2352,3 +2353,11 @@ int ncplane_putnstr_yx(struct ncplane* n, int y, int x, size_t s, const char* gc
   }
   return ret;
 }
+
+int notcurses_ucs32_to_utf8(const char32_t* ucs32, unsigned ucs32count,
+                            unsigned char* resultbuf, size_t buflen){
+  if(u32_to_u8(ucs32, ucs32count, resultbuf, &buflen) == NULL){
+    return -1;
+  }
+  return buflen;
+}