git.saurik.com Git - apple/libc.git/blob - string/FreeBSD/wcswidth.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/string/wcswidth.3,v 1.2 2002/12/09 14:04:05 ru Exp $

26 .\"

27 .Dd August 20, 2002

28 .Dt WCSWIDTH 3

29 .Os

30 .Sh NAME

31 .Nm wcswidth ,

32 .Nm wcswidth_l

33 .Nd "number of column positions in wide-character string"

34 .Sh LIBRARY

35 .Lb libc

36 .Sh SYNOPSIS

37 .In wchar.h

38 .Ft int

39 .Fo wcswidth

40 .Fa "const wchar_t *pwcs"

41 .Fa "size_t n"

42 .Fc

43 .In wchar.h

44 .In xlocale.h

45 .Ft int

46 .Fo wcswidth_l

47 .Fa "const wchar_t *pwcs"

48 .Fa "size_t n"

49 .Fa "locale_t loc"

50 .Fc

51 .Sh DESCRIPTION

52 The

53 .Fn wcswidth

54 function determines the number of column positions required for the first

55 .Fa n

56 characters of

57 .Fa pwcs ,

58 or until a null wide character (L'\e0') is encountered.

59 .Pp

60 Although the

61 .Fn wcswidth

62 function uses the current locale, the

63 .Fn wcswidth_l

64 function may be passed a locale directly. See

65 .Xr xlocale 3

66 for more information.

67 .Sh RETURN VALUES

68 The

69 .Fn wcswidth

70 function returns 0 if

71 .Fa pwcs

72 is an empty string (L""),

73 \-1 if a non-printing wide character is encountered;

74 otherwise, it returns the number of column positions occupied.

75 .Sh SEE ALSO

76 .Xr iswprint 3 ,

77 .Xr wcwidth 3 ,

78 .Xr xlocale 3

79 .Sh STANDARDS

80 The

81 .Fn wcswidth

82 function conforms to

83 .St -p1003.1-2001 .