add ncplane_putstr_stainable() #754

NEWS.md

@@ -14,6 +14,7 @@ rearrangements of Notcurses.
   * Added `ncdirect_hline_interp()`, `ncdirect_vline_interp()`,
     `ncdirect_rounded_box()`, `ncdirect_double_box()`, and the ridiculously
     flexible `ncdirect_box()`.
+  * Added `ncplane_putstr_stainable()`.
 
 * 1.6.0 (2020-07-04)
   * Behavior has changed regarding use of the provided `FILE*` (which, when

USAGE.md

@@ -982,6 +982,10 @@ ncplane_putstr(struct ncplane* n, const char* gclustarr){
 
 int ncplane_putstr_aligned(struct ncplane* n, int y, ncalign_e align, const char* s);
 
+// Replace a string's worth of glyphs at the current cursor location, but
+// retain the styling. The current styling of the plane will not be changed.
+int ncplane_putstr_stainable(struct ncplane* n, const char* s);
+
 // ncplane_putstr(), but following a conversion from wchar_t to UTF-8 multibyte.
 static inline int
 ncplane_putwstr_yx(struct ncplane* n, int y, int x, const wchar_t* gclustarr){

doc/man/man3/notcurses_output.3.md

@@ -42,6 +42,8 @@ notcurses_output - output to ncplanes
 
 **int ncplane_putstr_aligned(struct ncplane* n, int y, ncalign_e align, const char* s);**
 
+**int ncplane_putstr_stainable(struct ncplane* n, const char* s);**
+
 **int ncplane_putwstr_yx(struct ncplane* n, int y, int x, const wchar_t* gclustarr);**
 
 **static inline int ncplane_putwstr_aligned(struct ncplane* n, int y, ncalign_e align, const wchar_t* gclustarr);**

include/notcurses/notcurses.h

@@ -1440,6 +1440,10 @@ ncplane_putstr(struct ncplane* n, const char* gclustarr){
 API int ncplane_putstr_aligned(struct ncplane* n, int y, ncalign_e align,
                                const char* s);
 
+// Replace a string's worth of glyphs at the current cursor location, but
+// retain the styling. The current styling of the plane will not be changed.
+API int ncplane_putstr_stainable(struct ncplane* n, const char* s);
+
 // Write a series of EGCs to the current location, using the current style.
 // They will be interpreted as a series of columns (according to the definition
 // of ncplane_putc()). Advances the cursor by some positive number of columns

python/src/notcurses/build_notcurses.py

@@ -209,6 +209,7 @@ int ncplane_putwc_yx(struct ncplane* n, int y, int x, wchar_t w);
 int ncplane_putwc(struct ncplane* n, wchar_t w);
 int ncplane_putegc_yx(struct ncplane* n, int y, int x, const char* gclust, int* sbytes);
 int ncplane_putstr_aligned(struct ncplane* n, int y, ncalign_e align, const char* s);
+int ncplane_putstr_stainable(struct ncplane* n, const char* s);
 struct ncplane* ncplane_dup(const struct ncplane* n, void* opaque);
 void cell_init(cell* c);
 int cell_load(struct ncplane* n, cell* c, const char* gcluster);

src/lib/notcurses.c

@@ -2265,6 +2265,24 @@ int ncplane_putstr_yx(struct ncplane* n, int y, int x, const char* gclusters){
   return ret;
 }
 
+int ncplane_putstr_stainable(struct ncplane* n, const char* gclusters){
+  int ret = 0;
+  // FIXME speed up this blissfully naive solution
+  while(*gclusters){
+    int wcs;
+    int cols = ncplane_putegc_stainable(n, gclusters, &wcs);
+    if(cols < 0){
+      return -ret;
+    }
+    if(wcs == 0){
+      break;
+    }
+    gclusters += wcs;
+    ret += wcs;
+  }
+  return ret;
+}
+
 int ncplane_putnstr_yx(struct ncplane* n, int y, int x, size_t s, const char* gclusters){
   size_t ret = 0;
   // FIXME speed up this blissfully naive solution