curs_insstr(3X)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

✨ curs_insstr(3X) ✨

okay bestie, gather round 💖 this is a library calls page from ncurses — specifically the curs_insstr(3X) one — and it's literally all about shoving strings into a curses window. no cap.

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 💅

so winsstr takes your string str and slides it in before the character sitting at the cursor in window win, like it's cutting the line — and it does it as if by calling winsch(3X) for each char in str. it's giving one-at-a-time, but make it fashion. ✨

no line wrapping is performed. like, none. periodt.

the characters to the right of the cursor get shifted right, and honestly? the ones at the right edge of the window may be lost 😭. it happens.

winsstr stops inserting if it would have to wrap to the next line to write the next char in str — it's not about to break that rule, bestie. 🛑

the cursor position does not change (after moving to (y, x), if specified). lowkey iconic behavior, it stays put. 👑

insnstr does the same thing, but inserts at most n characters — or as many as possible (up to the end of the line) if n is negative. ✨

and ncurses(3X) describes the variants of these functions, iykyk.

RETURN VALUE 🫶

these functions return OK on success and ERR on failure. simple as that.

in ncurses, they return ERR if:

win is NULL,
str is NULL, or
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. so like, stay in your lane or get ERR'd 💀

NOTES 🌸

all of these functions except winsnstr may be implemented as macros. sneaky little things 🙈

EXTENSIONS 🍓

insnstr, winsnstr, mvinsnstr, and mvwinsnstr's acceptance of negative n values is an ncurses extension. that's a ncurses-only flex, no cap. 💅

PORTABILITY 🌈

applications employing ncurses extensions should condition their use on the visibility of the NCURSES_VERSION preprocessor macro. like, check first, bestie 🫶

X/Open Curses Issue 4 describes these functions. it specifies no error conditions for them. wild, right?

SVr4 describes a successful return value only as "an integer value other than ERR". okay that's vague of 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 manifests this inconsistency, and Issue 7 removed the claim. so, yeah, drama in the standards committee 😭

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, and differs from the SVr4 curses and Solaris xcurses implementations. nevertheless, Issue 7 retains the language. they said "we're keeping it" 💀

HISTORY ⭐

SVr3.1 (1987) introduced winsstr and winsnstr and their variants. throwback era fr fr 🕰️