.\"*************************************************************************** .\" Copyright 2019-2024,2025 Thomas E. Dickey * .\" Copyright 2002-2012,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * .\" copy of this software and associated documentation files (the * .\" "Software"), to deal in the Software without restriction, including * .\" without limitation the rights to use, copy, modify, merge, publish, * .\" distribute, distribute with modifications, sublicense, and/or sell * .\" copies of the Software, and to permit persons to whom the Software is * .\" furnished to do so, subject to the following conditions: * .\" * .\" The above copyright notice and this permission notice shall be included * .\" in all copies or substantial portions of the Software. * .\" * .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * .\" * .\" Except as contained in this notice, the name(s) of the above copyright * .\" holders shall not be used in advertising or otherwise to promote the * .\" sale, use or other dealings in this Software without prior written * .\" authorization. * .\"*************************************************************************** .\" .\" $Id: curs_ins_wstr.3x,v 1.60 2025/03/01 21:30:14 tom Exp $ .TH curs_ins_wstr 3X 2025-03-01 "ncurses 6.5" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq .\} .el \{\ .ie t .ds `` `` .el .ds `` "" .ie t .ds '' '' .el .ds '' "" .\} . .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 .. .SH NAME \fB\%ins_wstr\fP, \fB\%wins_wstr\fP, \fB\%mvins_wstr\fP, \fB\%mvwins_wstr\fP, \fB\%ins_nwstr\fP, \fB\%wins_nwstr\fP, \fB\%mvins_nwstr\fP, \fB\%mvwins_nwstr\fP \- insert a wide-character string in a \fIcurses\fR window .SH SYNOPSIS .nf \fB#include .PP \fBint ins_wstr(const wchar_t * \fIwstr\fP); \fBint wins_wstr(WINDOW * \fIwin\fP, const wchar_t * \fIwstr\fP); \fBint mvins_wstr(int \fIy\fP, int \fIx\fP, const wchar_t * \fIwstr\fP); \fBint mvwins_wstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t * \fIwstr\fP); .PP \fBint ins_nwstr(const wchar_t * \fIwstr\fP, int \fIn\fP); \fBint wins_nwstr(WINDOW * \fIwin\fP, const wchar_t * \fIwstr\fP, int \fIn\fP); \fBint mvins_nwstr(int \fIy\fP, int \fIx\fP, const wchar_t * \fIwstr\fP, int \fIn\fP); \fBint mvwins_nwstr(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, const wchar_t * \fIwstr\fP, int \fIn\fP); .fi .SH DESCRIPTION .B \%wins_wstr inserts a wide-character string .I wstr before the character at the cursor in window .I win as if by calling \fBwins_wch\fP(3X) for each .I \%wchar_t in .IR wstr "." 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. .B \%wins_wstr stops inserting if it would have to wrap to the next line to write the next .I \%wchar_t in .IR wstr "." The cursor position does not change (after moving to .RI ( y , .IR x ")," if specified). .B \%wins_nwstr does the same, but inserts at most .I n wide characters, or as many as possible (up to the end of the line) if .I n is negative. \fB\%ncurses\fP(3X) describes the variants of these functions. .SH RETURN VALUE These functions return .B OK on success and .B ERR on failure. .PP In .IR \%ncurses "," they return .B ERR if .bP .I win is .IR NULL "," .bP .I wstr is .IR NULL "," .bP the first wide character in .I wstr is a non-spacing character, or .bP an internal \fB\%wins_wch\fP(3X) call returns .BR ERR "." .PP Functions prefixed with \*(``mv\*('' first perform cursor movement and fail if the position .RI ( y , .IR x ) is outside the window boundaries. .SH NOTES All of these functions except .B \%wins_nwstr may be implemented as macros. .SH EXTENSIONS .BR \%ins_nwstr "," .BR \%wins_nwstr "," .BR \%mvins_nwstr "," and .BR \%mvwins_nwstr "'s" acceptance of negative .I n values is an .I \%ncurses extension. .SH PORTABILITY Applications employing .I \%ncurses extensions should condition their use on the visibility of the .B \%NCURSES_VERSION preprocessor macro. .PP X/Open Curses Issue\ 4 describes these functions. It specifies no error conditions for them. .PP X/Open Curses does not specify what happens if a non-spacing character follows a control character. .PP Issue\ 4 states that the entire string is inserted if .I n is less than 1. This is probably an error, .\" ...copied from SVID 4, which made the same error; see p. 513. because it is inconsistent with other functions such as .IR \%waddwstr "," and differs from the SVr4 .I curses and Solaris .I xcurses implementations. Nevertheless, Issue\ 7 retains the language. .SH HISTORY X/Open Curses Issue\ 4 (1995) initially specified these functions. The System\ V Interface Definition Version\ 4 (1995), specified functions named .I \%winswstr and .I \%winsnwstr (and the usual variants). .\" SVID 4, vol 3., p. 513 .\" The prototypes also identify the data type as `wchar`, not .\" `wchar_t`, but this may be an error since the "DESCRIPTION" section .\" consistently uses the latter. --GBR These were later additions to .RI SVr4. x , not appearing in the first SVr4 (1989). They differ from X/Open's later .I \%wins_wstr and .I \%wins_nwstr in that their .I wstr parameters are not .IR const "-qualified." .SH SEE ALSO \fB\%curs_insstr\fP(3X) describes comparable functions of the .I \%ncurses library in its non-wide-character configuration. .PP \fB\%curses\fP(3X), \fB\%curs_ins_wch\fP(3X), \fB\%curs_in_wch\fP(3X)