[apple/libc.git] / locale / FreeBSD / wctrans.3

.\" Copyright (c) 2002 Tim J. Robbins
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/lib/libc/locale/wctrans.3,v 1.3 2002/11/29 17:35:09 ru Exp $
.\"
.Dd October 3, 2002
.Dt WCTRANS 3
.Os
.Sh NAME
.Nm towctrans , wctrans
.Nd "wide character mapping functions"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In wctype.h
.Ft wint_t
.Fn towctrans "wint_t wc" "wctrans_t desc"
.Ft wctrans_t
.Fn wctrans "const char *charclass"
.Sh DESCRIPTION
The
.Fn wctrans
function returns a value of type
.Vt wctrans_t
which represents the requested wide character mapping operation and
may be used as the second argument for calls to
.Fn towctrans .
.Pp
The following character mapping names are recognised:
.Bl -column -offset indent ".Li tolower" ".Li toupper"
.It Li "tolower	toupper"
.El
.Pp
The
.Fn towctrans
function transliterates the wide character
.Fa wc
according to the mapping described by
.Fa desc .
.Sh RETURN VALUES
The
.Fn towctrans
function returns the transliterated character if successful, otherwise
it returns the character unchanged and sets
.Va errno .
.Pp
The
.Fn wctrans
function returns non-zero if successful, otherwise it returns zero
and sets
.Va errno .
.Sh EXAMPLES
Reimplement
.Fn towupper
in terms of
.Fn towctrans
and
.Fn wctrans :
.Bd -literal -offset indent
wint_t
mytowupper(wint_t wc)
{
	return (towctrans(wc, wctrans("toupper")));
}
.Ed
.Sh ERRORS
The
.Fn towctrans
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The supplied
.Fa desc
argument is invalid.
.El
.Pp
The
.Fn wctrans
function will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
The requested mapping name is invalid.
.El
.Sh SEE ALSO
.Xr tolower 3 ,
.Xr toupper 3 ,
.Xr wctype 3
.Sh STANDARDS
The
.Fn towctrans
and
.Fn wctrans
functions conform to
.St -p1003.1-2001 .
.Sh HISTORY
The
.Fn towctrans
and
.Fn wctrans
functions first appeared in
.Fx 5.0 .
Commit	Line	Data
9385eb3d A	1	.\" Copyright (c) 2002 Tim J. Robbins
	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	.\"
	25	.\" $FreeBSD: src/lib/libc/locale/wctrans.3,v 1.3 2002/11/29 17:35:09 ru Exp $
	26	.\"
	27	.Dd October 3, 2002
	28	.Dt WCTRANS 3
	29	.Os
	30	.Sh NAME
	31	.Nm towctrans , wctrans
	32	.Nd "wide character mapping functions"
	33	.Sh LIBRARY
	34	.Lb libc
	35	.Sh SYNOPSIS
	36	.In wctype.h
	37	.Ft wint_t
	38	.Fn towctrans "wint_t wc" "wctrans_t desc"
	39	.Ft wctrans_t
	40	.Fn wctrans "const char *charclass"
	41	.Sh DESCRIPTION
	42	The
	43	.Fn wctrans
	44	function returns a value of type
	45	.Vt wctrans_t
	46	which represents the requested wide character mapping operation and
	47	may be used as the second argument for calls to
	48	.Fn towctrans .
	49	.Pp
	50	The following character mapping names are recognised:
	51	.Bl -column -offset indent ".Li tolower" ".Li toupper"
	52	.It Li "tolower toupper"
	53	.El
	54	.Pp
	55	The
	56	.Fn towctrans
	57	function transliterates the wide character
	58	.Fa wc
	59	according to the mapping described by
	60	.Fa desc .
	61	.Sh RETURN VALUES
	62	The
	63	.Fn towctrans
	64	function returns the transliterated character if successful, otherwise
65	it returns the character unchanged and sets
66	.Va errno .
67	.Pp
68	The
69	.Fn wctrans
70	function returns non-zero if successful, otherwise it returns zero
71	and sets
72	.Va errno .
73	.Sh EXAMPLES
74	Reimplement
75	.Fn towupper
76	in terms of
77	.Fn towctrans
78	and
79	.Fn wctrans :
80	.Bd -literal -offset indent
81	wint_t
82	mytowupper(wint_t wc)
83	{
84	return (towctrans(wc, wctrans("toupper")));
85	}
86	.Ed
87	.Sh ERRORS
88	The
89	.Fn towctrans
90	function will fail if:
91	.Bl -tag -width Er
92	.It Bq Er EINVAL
93	The supplied
94	.Fa desc
95	argument is invalid.
96	.El
97	.Pp
98	The
99	.Fn wctrans
100	function will fail if:
101	.Bl -tag -width Er
102	.It Bq Er EINVAL
103	The requested mapping name is invalid.
104	.El
105	.Sh SEE ALSO
106	.Xr tolower 3 ,
107	.Xr toupper 3 ,
108	.Xr wctype 3
109	.Sh STANDARDS
110	The
111	.Fn towctrans
112	and
113	.Fn wctrans
114	functions conform to
115	.St -p1003.1-2001 .
116	.Sh HISTORY
117	The
118	.Fn towctrans
119	and
120	.Fn wctrans
121	functions first appeared in
122	.Fx 5.0 .