Windows Safe String Function
HRESULT StringCchVPrintf(LPTSTR pszDest, size_t cchDest, LPCTSTR pszFormat, va_list argList);
HRESULT StringCchVPrintfA(LPSTR pszDest, size_t cchDest, LPCSTR pszFormat, va_list argList);
HRESULT StringCchVPrintfW(LPWSTR pszDest, size_t cchDest, LPCWSTR pszFormat, va_list argList);
HRESULT StringCchVPrintfEx(LPTSTR pszDest, size_t cchDest, LPTSTR *ppszDestEnd, size_t *pcchRemaining, DWORD dwFlags, LPCTSTR pszFormat, va_list argList);
HRESULT StringCchVPrintfExA(LPSTR pszDest, size_t cchDest, LPSTR *ppszDestEnd, size_t *pcchRemaining, DWORD dwFlags, LPCSTR pszFormat, va_list argList);
HRESULT StringCchVPrintfExW(LPWSTR pszDest, size_t cchDest, LPWSTR *ppszDestEnd, size_t *pcchRemaining, DWORD dwFlags, LPCWSTR pszFormat, va_list argList);
Internationalization (I18n) Function Overview
The StringCchVPrintf is a replacement for locale-sensitive formatting functions.
It returns a formatted string in pszDest, using the format string in pzsFormat and a variable list of arguments stored in argList. The character size of pszDest, stored in cchDest, is used to ensure that the destination string buffer is not overrun.
In the event of an error, a negative HRESULT value is returned, indicating the error.
StringCchVPrintfEx adds advanced functionality: It returns a pointer to the end of the destination string as well as the number of characters left unused in that string, and uses dwFlags for additional control.
The narrow versions of these functions, StringCchVPrintfA and
StringCchVPrintfExA, pass in single-byte or multibyte strings and lengths that refer to
the number of single-byte characters.
The wide versions of these functions, StringCchVPrintfW and
StringCchVPrintfExW, pass in wide-character strings and lengths that refer to
the number of wide (wchar_t) characters.
I18n Issues
Use the appropriate version of the function as required for internationalization support, and ensure that cchDest is set to the character size of the destination string buffer: on Windows MBCS, the size of a character is one byte; on Windows Unicode, it's two bytes.
See Locale-Sensitive Length Functions for a discussion on multibyte
and wide character sizes.
Prior to calling one of these functions, ensure that the current locale is set properly by calling setlocale, as string formatting is dependent on the LC_NUMERIC locale category.
See String Formatting in C and C++ for a discussion on locale-sensitive formatting in internationalized applications.
Recommended Replacements*
When possible, use the Generic version of the function, rather than the narrow or wide versions, and let the Windows #define UNICODE switch determine which version of the function will be called.
These are shown as the first choices in the following table:
*If you're already using the recommended function, see I18n Issues for other reasons why Globalyzer is detecting the function.
Windows Safe String
Functions
|
