string/wcsxfrm.3

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Chris Torek and the American National Standards Committee X3,
   6 .\" on Information Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)strxfrm.3   8.1 (Berkeley) 6/4/93
  37 .\" FreeBSD: src/lib/libc/string/strxfrm.3,v 1.16 2002/09/06 11:24:06 tjr Exp
  38 .\" $FreeBSD: src/lib/libc/string/wcsxfrm.3,v 1.2 2002/12/09 14:04:05 ru Exp $
  39 .\"
  40 .Dd October 4, 2002
  41 .Dt WCSXFRM 3
  42 .Os
  43 .Sh NAME
  44 .Nm wcsxfrm ,
  45 .Nm wcsxfrm_l
  46 .Nd transform a wide string under locale
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In wchar.h
  51 .Ft size_t
  52 .Fo wcsxfrm
  53 .Fa "wchar_t *restrict ws1"
  54 .Fa "const wchar_t *restrict ws2"
  55 .Fa "size_t n"
  56 .Fc
  57 .In wchar.h
  58 .In xlocale.h
  59 .Ft size_t
  60 .Fo wcsxfrm_l
  61 .Fa "wchar_t *restrict ws1"
  62 .Fa "const wchar_t *restrict ws2"
  63 .Fa "size_t n"
  64 .Fa "locale_t loc"
  65 .Fc
  66 .Sh DESCRIPTION
  67 The
  68 .Fn wcsxfrm
  69 function transforms a null-terminated wide character string pointed to by
  70 .Fa ws2 ,
  71 according to the current locale's collation order,
  72 then copies the transformed string into
  73 .Fa ws1 .
  74 No more than
  75 .Fa n
  76 wide characters are copied into
  77 .Fa ws1 ,
  78 including the terminating null character.
  79 If
  80 .Fa n
  81 is set to 0
  82 (it helps to determine an actual size needed
  83 for transformation),
  84 .Fa ws1
  85 is permitted to be a
  86 .Dv NULL
  87 pointer.
  88 .Pp
  89 Comparing two strings using
  90 .Fn wcscmp
  91 after
  92 .Fn wcsxfrm
  93 is equivalent to comparing
  94 two original strings with
  95 .Fn wcscoll .
  96 .Pp
  97 Although the
  98 .Fn wcsxfrm
  99 function uses the current locale, the
 100 .Fn wcsxfrm_l
 101 function may be passed a locale directly. See
 102 .Xr xlocale 3
 103 for more information.
 104 .Sh RETURN VALUES
 105 Upon successful completion,
 106 .Fn wcsxfrm
 107 returns the length of the transformed string not including
 108 the terminating null character.
 109 If this value is
 110 .Fa n
 111 or more, the contents of
 112 .Fa ws1
 113 are indeterminate.
 114 .Sh SEE ALSO
 115 .Xr setlocale 3 ,
 116 .Xr strxfrm 3 ,
 117 .Xr wcscmp 3 ,
 118 .Xr wcscoll 3 ,
 119 .Xr xlocale 3
 120 .Sh STANDARDS
 121 The
 122 .Fn wcsxfrm
 123 function
 124 conforms to
 125 .St -isoC-99 .
 126 .Sh BUGS
 127 The current implementation of
 128 .Fn wcsxfrm
 129 only works in single-byte
 130 .Dv LC_CTYPE
 131 locales, and falls back to using
 132 .Fn wcsncpy
 133 in locales with extended character sets.
 134 .Pp
 135 Comparing two strings using
 136 .Fn wcscmp
 137 after
 138 .Fn wcsxfrm
 139 is
 140 .Em not
 141 always equivalent to comparison with
 142 .Fn wcscoll ;
 143 .Fn wcsxfrm
 144 only stores information about primary collation weights into
 145 .Fa ws1 ,
 146 whereas
 147 .Fn wcscoll
 148 compares characters using both primary and secondary weights.