# curs_add_wchstr 3x 2025-03-15 ncurses 6.5 Library calls

    curs_add_wchstr(3x)              Library calls             curs_add_wchstr(3x)

## NAME

           add_wchstr,   wadd_wchstr,  mvadd_wchstr,  mvwadd_wchstr,  add_wchnstr,
           wadd_wchnstr, mvadd_wchnstr, mvwadd_wchnstr  -  add  a  curses  complex
           character string to a window

## SYNOPSIS

           #include <curses.h>

           int add_wchstr(const cchar_t * wchstr);
           int wadd_wchstr(WINDOW *  win, const cchar_t * wchstr);
           int mvadd_wchstr(int y, int x, const cchar_t * wchstr);
           int mvwadd_wchstr(WINDOW * win, int y, int x,
                 const cchar_t * wchstr);

           int add_wchnstr(const cchar_t * wchstr, int n);
           int wadd_wchnstr(WINDOW *  win, const cchar_t * wchstr,
                 int n);
           int mvadd_wchnstr(int y, int x, const cchar_t * wchstr,
                 int n);
           int mvwadd_wchnstr(WINDOW * win, int y, int x,
                 const cchar_t * wchstr, int n);

## DESCRIPTION

           wadd_wchstr  copies  the  string  of  complex  characters wchstr to the
           window win.  A null complex character  terminates  the  string.   If  a
           complex  character  does  not  completely  fit  at the end of the line,
           curses  fills  its  remaining  cells  with  the   window's   background
           character;  see  bkgrnd(3x).  wadd_wchnstr does the same, but copies at
           most n characters, or as many as possible  if  n  is  -1.   ncurses(3x)
           describes the variants of these functions.

           Because  these  functions do not call wadd_wch(3x) internally, they are
           faster than waddwstr(3x) and waddnwstr(3x).  On the other hand, they

           o   do  not  treat  the  backspace,  carriage  return,  or  line   feed
               characters specially;

           o   do not represent unprintable characters with wunctrl(3x);

           o   do  not  update  the  cursor  position to follow the last character
               written;

           o   truncate the string at  the  window's  right  margin,  rather  than
               wrapping it to the next line and potentially scrolling.

## RETURN VALUE

           These functions return OK on success and ERR on failure.

           In ncurses, these functions fail if

           o   the curses screen has not been initialized,

           o   wchstr is a null pointer, or

           o   (for  functions  taking  a  WINDOW  pointer argument) win is a null
               pointer.

           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  wadd_wchnstr  may  be implemented as
           macros.

## PORTABILITY

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

## HISTORY

           X/Open  Curses Issue 4 (1995) initially specified these functions.  The
           System V Interface Definition Version 4  of  the  same  year  specified
           functions  named  waddwchstr  and waddwchnstr (and the usual variants).
           These were later additions to SVr4.x, not appearing in the  first  SVr4
           (1989).  They differed from X/Open's later wadd_wchstr and wadd_wchnstr
           in that they each took an argument of type wchar_t instead of cchar_t.

## SEE ALSO

           curs_addchstr(3x) describes comparable functions of the ncurses library
           in its non-wide-character configuration.

           curses(3x), curs_addwstr(3x), curs_add_wch(3x)

    ncurses 6.5                       2025-03-15               curs_add_wchstr(3x)