https://invisible-island.net/ncurses/man/

curs_insstr 3x 2024-07-27 ncurses 6.5 Library calls

curs_insstr(3x)                  Library calls                 curs_insstr(3x)

NAME

       insstr,  winsstr,  mvinsstr,  mvinsnstr,  insnstr, winsnstr, mvwinsstr,
       mvwinsnstr - insert a string in a curses window

SYNOPSIS

       #include <curses.h>

       int insstr(const char * str);
       int winsstr(WINDOW * win, const char * str);
       int mvinsstr(int y, int x, const char * str);
       int mvwinsstr(WINDOW * win, int y, int x, const char * str);

       int insnstr(const char * str, int n);
       int winsnstr(WINDOW * win, const char * str, int n);
       int mvinsnstr(int y, int x, const char * str, int n);
       int mvwinsnstr(WINDOW * win, int y, int x, const char * str, int n);

DESCRIPTION

       winsstr inserts a string str before the  character  at  the  cursor  in
       window  win  as if by calling winsch(3x) for each char in str.  No line
       wrapping is performed.  Characters to  the  right  of  the  cursor  are
       shifted  right;  those  at  the  right  edge of the window may be lost.
       winsstr stops inserting if it would have to wrap to the  next  line  to
       write the next char in str.  The cursor position does not change (after
       moving to (y, x), if specified).  insnstr does the same, but inserts at
       most  n  characters, or as many as possible (up to the end of the line)
       if n is -1.  ncurses(3x) describes the variants of these functions.

RETURN VALUE

       These functions return OK on success and ERR on failure.

       In ncurses, they return ERR if

       o   win is NULL,

       o   str is NULL, or

       o   an internal winsch(3x) call returns ERR.

       Functions prefixed with "mv" first perform cursor movement and fail  if
       the position (y, x) is outside the window boundaries.

NOTES

       All of these functions except winsnstr may be implemented as macros.

PORTABILITY

       X/Open  Curses,  Issue  4  describes  these functions.  It specifies no
       error conditions for them.

       Issue 4 distinguished insnstr and winsnstr  from  the  other  functions
       documented  above  by stating they "do not perform wrapping".  This was
       probably an error, since it makes this group of functions inconsistent.
       No  implementation  of curses documents this inconsistency, and Issue 7
       removed it.

       Issue 4 states that the entire string is inserted if n is less than  1.
       This  is  probably  an  error,  because  it  is inconsistent with other
       functions such as waddstr(3x), and differs from  the  SVr4  curses  and
       Solaris  xcurses  implementations.   Nevertheless,  Issue 7 retains the
       language.

HISTORY

       SVr3.1 (1987) introduced winsstr and winsnstr.