.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2024 Oxide Computer Company
.\"
.Dd September 15, 2024
.Dt WCSWIDTH 3C
.Os
.Sh NAME
.Nm wcswidth ,
.Nm wcswidth_l
.Nd determine number of columns for wide-character string
.Sh SYNOPSIS
.In wchar.h
.Ft int
.Fo wcswidth
.Fa "const wchar_t *str"
.Fa "size_t len"
.Fc
.In wchar.h
.In xlocale.h
.Ft int
.Fo wcswidth_l
.Fa "const wchar_t *str"
.Fa "size_t len"
.Fa "locale_t loc"
.Fc
.Sh DESCRIPTION
The
.Fn wcswidth
and
.Fn wcswidth_l
functions count the total number of columns that are required
to display the contents of the wide-character string
.Fa str .
For each wide-character in the string
.Fa str ,
the equivalent of
.Xr wcwidth 3C
is called and the result summed to a running total which is returned.
.Pp
Up to
.Fa len
wide-characters from
.Fa str
will be evaluated; however, the functions will stop iterating if they
encounter the null wide-character
.Pq L'\e0' .
.Pp
The wide-characters in
.Fa str
must be valid characters in the current locale or in the case of the
.Fn wcswidth_l
function, the locale specified by
.Fa loc .
The functions will fail if any of the wide-characters in
.Fa str
are valid in the current
locale, but considered non-printable
.Po
as in
.Xr iswprint 3C
would fail for the character
.Pc
or the wide-character does not represent a valid character in the
locale.
.Sh RETURN VALUES
Upon successful completion, the
.Fn wcswidth
and
.Fn wcswidth_l
functions return the total number of columns that are required to
display the wide-character string.
Otherwise,
.Sy -1
is returned to indicate that an invalid or non-printable wide-character
was encountered.
.Sh EXAMPLES
.Sy Example 1
Using the
.Fn wcswidth
function to count characters in a string.
.Bd -literal
#include <wchar.h>
#include <stdio.h>

int
main(void)
{
        wchar_t *str = L"Hello world";
        int ret = wcswidth(str, wcslen(str));
        (void) printf("wcswidth returned: %d\en", ret);
        return (0);
}
.Ed
.Pp
When compiled and run, this program outputs:
.Bd -literal
$ gcc -Wall -Wextra example.c
$ ./a.out
wcswidth returned: 11
.Ed
.Sh MT-LEVEL
The
.Fn wcswidth
function is
.Sy MT-Safe
as long as the thread-specific or global locale is not changed while it
is running.
.Pp
The
.Fn wcswidth_l
function is
.Sy MT-Safe
as long as the locale
.Fa loc
is not freed while the function is running.
.Sh INTERFACE STABILITY
.Sy Committed
.Sh SEE ALSO
.Xr iswprint 3C ,
.Xr newlocale 3C ,
.Xr setlocale 3C ,
.Xr uselocale 3C ,
.Xr wcwidth 3C