__crtLCMapStringW

Maps one character string to another, performing a specified locale-dependent transformation. This function can also be used to generate a sort key for the input string.

int __crtLCMapStringW(
   LCID    Locale,
   DWORD   dwMapFlags,
   LPCWSTR lpSrcStr,
   int     cchSrc,
   LPWSTR  lpDestStr,
   int     cchDest)

Parameters

• Locale
  Locale identifier. The locale provides a context for the string mapping or sort key generation. An application can use the MAKELCID macro to create a locale identifier.

• dwMapFlags
  The type of transformation to be used during string mapping or sort key generation.

• lpSrcStr
  Pointer to a source string that the function maps or uses for sort key generation. This parameter is assumed to be a Unicode string.

• cchSrc
  Size, in characters, of the string pointed to by the lpSrcStr parameter. This count can include the NULL terminator, or not include it.

  A cchSrc value of –1 specifies that the string pointed to by lpSrcStr is null-terminated. If this is the case, and this function is being used in its string-mapping mode, the function calculates the string's length itself, and null-terminates the mapped string stored into *lpDestStr.

• lpDestStr
  Long pointer to a buffer into which the function stores the mapped string or sort key.

• cchDest
  Size, in characters, of the buffer pointed to by lpDestStr.

Return Value

If the value of cchDest is nonzero, the number of characters, or bytes if LCMAP_SORTKEY is specified, written to the buffer indicates success. This count includes room for a NULL terminator.

If the value of cchDest is zero, the size of the buffer in characters, or bytes if LCMAP_SORTKEY is specified, required to receive the translated string or sort key indicates success. This size includes room for a NULL terminator.

Zero indicates failure. To get extended error information, call the GetLastError function.

Remarks

If cchSrc is greater than zero and lpSrcStr is a null-terminated string, __crtLCMapStringW sets cchSrc to the length of the string. Then __crtLCMapStringW calls the wide string (Unicode) version of the LCMapString function with the specified parameters. For more information about the parameters and return value of this function, see the LCMapString function at MSDN Library.

Requirements

Routine	Required header
__crtLCMapStringW	awint.h

Change History

Date	History	Reason
September 2010	Explained that __crtLCMapStringW calls LCMapString with an adjusted source buffer length.	Information enhancement.