git.saurik.com Git - apple/libc.git/blob - locale/FreeBSD/wcwidth.3

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 .\"

25 .\" $FreeBSD: src/lib/libc/locale/wcwidth.3,v 1.6 2004/08/17 04:56:03 trhodes Exp $

26 .\"

27 .Dd August 17, 2004

28 .Dt WCWIDTH 3

29 .Os

30 .Sh NAME

31 .Nm wcwidth ,

32 .Nm wcwidth_l

33 .Nd "number of column positions of a wide-character code"

34 .Sh LIBRARY

35 .Lb libc

36 .Sh SYNOPSIS

37 .In wchar.h

38 .Ft int

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

49 .Sh DESCRIPTION

50 The

51 .Fn wcwidth

52 function determines the number of column positions required to

53 display the wide character

54 .Fa wc .

55 .Pp

56 Although the

57 .Fn wcwidth

58 function uses the current locale, the

59 .Fn wcwidth_l

60 function may be passed a locale directly. See

61 .Xr xlocale 3

62 for more information.

63 .Sh RETURN VALUES

64 The

65 .Fn wcwidth

66 function returns 0 if the

67 .Fa wc

68 argument is a null wide character (L'\e0'),

69 \-1 if

70 .Fa wc

71 is not printable;

72 otherwise, it returns the number of column positions the

73 character occupies.

74 .Sh EXAMPLES

75 This code fragment reads text from standard input and

76 breaks lines that are more than 20 column positions wide,

77 similar to the

78 .Xr fold 1

79 utility:

80 .Bd -literal -offset indent

81 wint_t ch;

82 int column, w;

84 column = 0;

85 while ((ch = getwchar()) != WEOF) {

86 w = wcwidth(ch);

87 if (w > 0 && column + w >= 20) {

88 putwchar(L'\en');

89 column = 0;

90 }

91 putwchar(ch);

92 if (ch == L'\en')

93 column = 0;

94 else if (w > 0)

95 column += w;

96 }

97 .Ed

98 .Sh SEE ALSO

99 .Xr iswprint 3 ,

100 .Xr wcswidth 3 ,

101 .Xr xlocale 3

102 .Sh STANDARDS

103 The

104 .Fn wcwidth

105 function conforms to

106 .St -p1003.1-2001 .