curs_ins_wstr(3X)

💖 curs_ins_wstr — bestie, we're inserting wide strings 💖

okay so this is a page from the ncurses library calls section of the manual, and it's all about sliding a wide-character string into a curses window. no cap, it's giving "sneaky little text insertion" energy. let's get into it 🦋

---

✨ NAME ✨

ins_wstr, wins_wstr, mvins_wstr, mvwins_wstr, ins_nwstr, wins_nwstr, mvins_nwstr, mvwins_nwstr — insert a wide-character string in a curses window 💅

---

🌸 SYNOPSIS 🌸

#include <curses.h>

int ins_wstr(const wchar_t * wstr);
int wins_wstr(WINDOW * win, const wchar_t * wstr);
int mvins_wstr(int y, int x, const wchar_t * wstr);
int mvwins_wstr(WINDOW * win, int y, int x,
      const wchar_t * wstr);

int ins_nwstr(const wchar_t * wstr, int n);
int wins_nwstr(WINDOW * win, const wchar_t * wstr, int n);
int mvins_nwstr(int y, int x, const wchar_t * wstr, int n);
int mvwins_nwstr(WINDOW * win, int y, int x,
      const wchar_t * wstr, int n);

eight whole functions, bestie. pick your fighter. 👑

---

🎀 DESCRIPTION 🎀

So wins_wstr takes your wide-character string wstr and inserts it before the character sitting at the cursor in window win — and it does that as if it called wins_wch(3X) once for each wchar_t in wstr. one at a time, like a lil assembly line. ✨

No line wrapping is performed. like, none. zero. it does not do that.

The characters to the right of the cursor get shifted right to make room 🫶 — but heads up, the ones hanging out at the right edge of the window may be lost. gone. poof. it's giving "we ran out of runway".

And wins_wstr will literally stop inserting if writing the next wchar_t in wstr would mean it has to wrap to the next line. it's just not gonna do that.

The cursor position does not change (well — after moving to (y, x), if you specified one).

Then wins_nwstr is the same vibe but with a limit: it inserts at most n wide characters, or as many as possible (up to the end of the line) if n is negative. yes bestie, negative. we'll get to that. 🙈

and ncurses(3X) describes the variants of these functions, if you wanna go deeper. 🌈

---

💀 RETURN VALUE 💀

These functions return OK when everything slays and ERR when it does not. periodt.

In ncurses, they return ERR if:

• win is NULL,
• wstr is NULL,
• the first wide character in wstr is a non-spacing character, or
• an internal wins_wch(3X) call returns ERR.

And the ones with the mv prefix? They do cursor movement first, and they fail if the position (y, x) is outside the window boundaries. like, you can't move somewhere that doesn't exist, babe. 😭

---

🧚 NOTES 🧚

All of these functions except wins_nwstr may be implemented as macros. iykyk, so don't go taking their address like it's nothing. 💅

---

🌟 EXTENSIONS 🌟

The fact that ins_nwstr, wins_nwstr, mvins_nwstr, and mvwins_nwstr accept negative n values? yeah, that's an ncurses extension. not standard, just our thing. ✨

---

🦋 PORTABILITY 🦋

If your app is out here using ncurses extensions, bestie, please condition that use on whether the NCURSES_VERSION preprocessor macro is even visible. vibe check your environment first. 🫶

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

X/Open Curses also does not specify what happens if a non-spacing character follows a control character. it's just... unspecified. 💀

Issue 4 states that the entire string is inserted if n is less than 1. and honestly? that's probably an error, because it's inconsistent with other functions such as waddwstr, and it differs from the SVr4 curses and Solaris xcurses implementations. but nevertheless — Issue 7 retains the language. iconic of them, honestly. 🎀

---

👑 HISTORY 👑

X/Open Curses Issue 4 (1995) initially specified these functions. The System V Interface Definition Version 4 (1995) specified functions named winswstr and winsnwstr (and the usual variants). These were later additions to SVr4.x — they were not in the first SVr4 (1989). and the tea? They differ from X/Open's later wins_wstr and wins_nwstr in that their wstr parameters are not const-qualified. the audacity. 🙈

---

💜 SEE ALSO 💜

• curs_insstr(3X) — describes comparable functions of the ncurses library in its non-wide-character configuration. the little sibling, basically. 🍓
• curses(3X)
• curs_ins_wch(3X)
• curs_in_wch(3X)

---

okay that's the whole page, bestie, you ate it 💅✨ this was pulled from the ncurses 6.6 manual, dated 2025-03-01 — so if you're reading this and the version number looks different, no you didn't 🎀🦋💖