]> git.saurik.com Git - apple/libc.git/blame - locale/FreeBSD/wcwidth.3
Libc-1082.20.4.tar.gz
[apple/libc.git] / locale / FreeBSD / wcwidth.3
CommitLineData
9385eb3d 1.\" Copyright (c) 2002 Tim J. Robbins
5b2abdfb
A
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
3d9156a7 25.\" $FreeBSD: src/lib/libc/locale/wcwidth.3,v 1.6 2004/08/17 04:56:03 trhodes Exp $
5b2abdfb 26.\"
3d9156a7 27.Dd August 17, 2004
9385eb3d 28.Dt WCWIDTH 3
5b2abdfb
A
29.Os
30.Sh NAME
ad3c9f2a
A
31.Nm wcwidth ,
32.Nm wcwidth_l
9385eb3d 33.Nd "number of column positions of a wide-character code"
5b2abdfb
A
34.Sh LIBRARY
35.Lb libc
36.Sh SYNOPSIS
9385eb3d 37.In wchar.h
5b2abdfb 38.Ft int
ad3c9f2a
A
39.Fo wcwidth
40.Fa "wchar_t wc"
41.Fc
42.In wchar.h
43.In xlocale.h
44.Ft int
45.Fo wcwidth_l
46.Fa "wchar_t wc"
47.Fa "locale_t loc"
48.Fc
5b2abdfb 49.Sh DESCRIPTION
9385eb3d
A
50The
51.Fn wcwidth
52function determines the number of column positions required to
53display the wide character
54.Fa wc .
ad3c9f2a
A
55.Pp
56Although the
57.Fn wcwidth
58function uses the current locale, the
59.Fn wcwidth_l
60function may be passed a locale directly. See
61.Xr xlocale 3
62for more information.
5b2abdfb 63.Sh RETURN VALUES
9385eb3d
A
64The
65.Fn wcwidth
66function returns 0 if the
67.Fa wc
68argument is a null wide character (L'\e0'),
69\-1 if
70.Fa wc
ad3c9f2a
A
71is not printable;
72otherwise, it returns the number of column positions the
9385eb3d
A
73character occupies.
74.Sh EXAMPLES
75This code fragment reads text from standard input and
76breaks lines that are more than 20 column positions wide,
77similar to the
78.Xr fold 1
79utility:
80.Bd -literal -offset indent
81wint_t ch;
82int column, w;
83
84column = 0;
85while ((ch = getwchar()) != WEOF) {
3d9156a7
A
86 w = wcwidth(ch);
87 if (w > 0 && column + w >= 20) {
9385eb3d
A
88 putwchar(L'\en');
89 column = 0;
90 }
91 putwchar(ch);
92 if (ch == L'\en')
93 column = 0;
3d9156a7
A
94 else if (w > 0)
95 column += w;
9385eb3d
A
96}
97.Ed
5b2abdfb 98.Sh SEE ALSO
9385eb3d 99.Xr iswprint 3 ,
ad3c9f2a
A
100.Xr wcswidth 3 ,
101.Xr xlocale 3
9385eb3d 102.Sh STANDARDS
5b2abdfb 103The
9385eb3d
A
104.Fn wcwidth
105function conforms to
106.St -p1003.1-2001 .