diff options
Diffstat (limited to 'lib/libc/string/wcsxfrm.3')
-rw-r--r-- | lib/libc/string/wcsxfrm.3 | 122 |
1 files changed, 122 insertions, 0 deletions
diff --git a/lib/libc/string/wcsxfrm.3 b/lib/libc/string/wcsxfrm.3 new file mode 100644 index 0000000..b5add9c --- /dev/null +++ b/lib/libc/string/wcsxfrm.3 @@ -0,0 +1,122 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" 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. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.\" @(#)strxfrm.3 8.1 (Berkeley) 6/4/93 +.\" FreeBSD: src/lib/libc/string/strxfrm.3,v 1.16 2002/09/06 11:24:06 tjr Exp +.\" $FreeBSD$ +.\" +.Dd October 4, 2002 +.Dt WCSXFRM 3 +.Os +.Sh NAME +.Nm wcsxfrm +.Nd transform a wide string under locale +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In wchar.h +.Ft size_t +.Fn wcsxfrm "wchar_t * restrict dst" "const wchar_t * restrict src" "size_t n" +.Sh DESCRIPTION +The +.Fn wcsxfrm +function transforms a null-terminated wide character string pointed to by +.Fa src +according to the current locale collation order +then copies the transformed string +into +.Fa dst . +No more than +.Fa n +wide characters are copied into +.Fa dst , +including the terminating null character added. +If +.Fa n +is set to 0 +(it helps to determine an actual size needed +for transformation), +.Fa dst +is permitted to be a +.Dv NULL +pointer. +.Pp +Comparing two strings using +.Fn wcscmp +after +.Fn wcsxfrm +is equivalent to comparing +two original strings with +.Fn wcscoll . +.Sh RETURN VALUES +Upon successful completion, +.Fn wcsxfrm +returns the length of the transformed string not including +the terminating null character. +If this value is +.Fa n +or more, the contents of +.Fa dst +are indeterminate. +.Sh SEE ALSO +.Xr setlocale 3 , +.Xr strxfrm 3 , +.Xr wcscmp 3 , +.Xr wcscoll 3 +.Sh STANDARDS +The +.Fn wcsxfrm +function +conforms to +.St -isoC-99 . +.Sh BUGS +The current implementation of +.Fn wcsxfrm +only works in single-byte +.Dv LC_CTYPE +locales, and falls back to using +.Fn wcsncpy +in locales with extended character sets. +.Pp +Comparing two strings using +.Fn wcscmp +after +.Fn wcsxfrm +is +.Em not +always equivalent to comparison with +.Fn wcscoll ; +.Fn wcsxfrm +only stores information about primary collation weights into +.Fa dst , +whereas +.Fn wcscoll +compares characters using both primary and secondary weights. |