notcurses_output - output to ncplanes

       nick black <nickblack@linux.com>.

                                                     v3.0.7                                  notcurses_output(3)

       These functions write EGCs (Extended Grapheme Clusters) to the specified structncplanes.  The  following
       inputs are supported:

       • ncplane_putc(): writes a single nccell (see notcurses_cell(3))

       • ncplane_putchar(): writes a single 7-bit ASCII character

       • ncplane_putwc(): writes a single wchar_t (following UTF-8 conversion)

       • ncplane_putwegc(): writes a single EGC from an array of wchar_t

       • ncplane_putegc(): writes a single EGC from an array of UTF-8

       • ncplane_putstr(): writes a set of EGCs from an array of UTF-8

       • ncplane_putwstr(): writes a set of EGCs from an array of wchar_t

       • ncplane_vprintf(): formatted output using va_list

       • ncplane_printf(): formatted output using variadic arguments

       • ncplane_puttext(): multi-line, line-broken, aligned text

       All  of  these  use the ncplane's active styling, save notcurses_putc(), which uses the nccell's styling.
       Functions accepting a single EGC expect a series of wchar_t terminated by L'\0' or a series of UTF-8 char
       terminated by '\0'.  The EGC must be well-formed, and must not contain any cluster breaks.  For more  in‐
       formation,  consult Unicode® Standard Annex #29 (https://unicode.org/reports/tr29/).  Functions accepting
       a set of EGCs must consist of a series of well-formed EGCs, broken by cluster breaks, terminated  by  the
       appropriate NUL terminator.

       Control  characters  are  rejected,  aside from two exceptions: a horizontal tab (', 0x09), and a newline
       ('', 0x0a) whentheoutputplaneisinscrollingmode.  A newline outside of scrolling mode will  be  re‐
       jected.   A  tab will advance to the next tab stop, filling the space between with spaces.  Tab stops are
       separated by eight columns, and the first character of each line is a tab stop.

       These functions output to the ncplane's current cursor location.  Aside from ncplane_puttext(),  they  donot  move  to  the next line upon reaching the right extreme of the containing plane.  If the entirety of
       the content cannot be output, they will output as much as possible.

       Each of these base functions has two additional forms:

       • ncplane_putc_aligned(), etc.: accepts a row and an alignment type

       • ncplane_putc_yx(), etc.: accepts a row and column

       If a positional parameter is -1, no movement will be made along that axis.  Passing -1,-1 to  e.g.   nc‐plane_putc_yx()  is  equivalent  to calling the base form.  These functions are implemented by moving the
       cursor, and then performing the output.  The two steps are atomic on success (it is not possible for  an‐
       other  caller  to  move the cursor between when it is positioned, and when output begins), and thus these
       functions ought generally be preferred to an explicit ncplane_cursor_move_yx().

       Upon successful return, the cursor will follow the last cell output.

       notcurses_output - output to ncplanes

ncplane_cursor_move_yx() returns -1 on error (invalid coordinate), or 0 on success.

       For output functions, a negative return indicates an error with the inputs.   Otherwise,  the  number  of
       screencolumns output is returned.  It is entirely possible to get a short return, if there was insuffi‐
       cient room to output all EGCs.

fprintf(3)notcurses(3), notcurses_cell(3), notcurses_plane(3), stdarg(3), ascii(7), unicode(7), utf-8(7)

#include<notcurses/notcurses.h>staticinlineintncplane_putc(structncplane*n,constnccell*c);intncplane_putc_yx(structncplane*n,inty,intx,constnccell*c);staticinlineintncplane_putchar(structncplane*n,charc);staticinlineintncplane_putchar_yx(structncplane*n,inty,intx,charc);intncplane_putchar_stained(structncplane*n,charc);staticinlineintncplane_putwc(structncplane*n,wchar_tw);intncplane_putwc_yx(structncplane*n,inty,intx,wchar_tw);staticinlineintncplane_putwc_stained(structncplane*n,wchar_tw);staticinlineintncplane_putegc(structncplane*n,constchar*gclust,int*sbytes);intncplane_putegc_yx(structncplane*n,inty,intx,constchar*gclust,int*sbytes);intncplane_putegc_stained(structncplane*n,constchar*gclust,int*sbytes);staticinlineintncplane_putwegc(structncplane*n,constwchar_t*gclust,int*sbytes);staticinlineintncplane_putwegc_yx(structncplane*n,inty,intx,constwchar_t*gclust,int*sbytes);intncplane_putwegc_stained(structncplane*n,constwchar_t*gclust,int*sbytes);intncplane_putstr_yx(structncplane*n,inty,intx,constchar*gclustarr);staticinlineintncplane_putstr(structncplane*n,constchar*gclustarr);intncplane_putstr_aligned(structncplane*n,inty,ncalign_ealign,constchar*s);intncplane_putstr_stained(structncplane*n,constchar*s);staticinlineintncplane_putwstr(structncplane*n,constwchar_t*gclustarr);intncplane_putwstr_yx(structncplane*n,inty,intx,constwchar_t*gclustarr);staticinlineintncplane_putwstr_aligned(structncplane*n,inty,ncalign_ealign,constwchar_t*gclustarr);intncplane_putwstr_stained(structncplane*n,constwchar_t*gclustarr);staticinlineintncplane_putnstr(structncplane*n,size_ts,constchar*gclustarr);intncplane_putnstr_yx(structncplane*n,inty,intx,size_ts,constchar*gclusters);intncplane_putnstr_aligned(structncplane*n,inty,ncalign_ealign,size_ts,constchar*s);intncplane_vprintf_aligned(structncplane*n,inty,ncalign_ealign,constchar*format,va_listap);intncplane_vprintf_yx(structncplane*n,inty,intx,constchar*format,va_listap);staticinlineintncplane_vprintf(structncplane*n,constchar*format,va_listap);staticinlineintncplane_printf(structncplane*n,constchar*format,...);staticinlineintncplane_printf_yx(structncplane*n,inty,intx,constchar*format,...);staticinlineintncplane_printf_aligned(structncplane*n,inty,ncalign_ealign,constchar*format,...);intncplane_cursor_move_yx(structncplane*n,inty,intx);intncplane_puttext(structncplane*n,inty,ncalign_ealign,constchar*text,size_t*bytes);