Windows Safe String Function
HRESULT StringCbVPrintf(LPTSTR pszDest, size_t cbDest, LPCTSTR pszFormat, va_list argList);
HRESULT StringCbVPrintfA(LPSTR pszDest, size_t cbDest, LPCSTR pszFormat, va_list argList);
HRESULT StringCbVPrintfW(LPWSTR pszDest, size_t cbDest, LPCWSTR pszFormat, va_list argList);
HRESULT StringCbVPrintfEx(LPTSTR pszDest, size_t cbDest, LPTSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags, LPCTSTR pszFormat, va_list argList);
HRESULT StringCbVPrintfExA(LPSTR pszDest, size_t cbDest, LPSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags, LPCSTR pszFormat, va_list argList);
HRESULT StringCbVPrintfExW(LPWSTR pszDest, size_t cbDest, LPWSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags, LPCWSTR pszFormat, va_list argList);
Internationalization (I18n) Function Overview
The StringCbVPrintf 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 byte size of pszDest, stored in cbDest, 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.
StringCbVPrintfEx adds advanced functionality: It returns a pointer to the end of the destination string as well as the number of bytes left unused in that string, and uses dwFlags for additional control.
The narrow versions of these functions, StringCbVPrintfA and
StringCbVPrintfExA, pass in single-byte or multibyte strings and lengths that refer to
the number of bytes.
The wide versions of these functions, StringCbVPrintfW and
StringCbVPrintfExW, pass in wide-character strings, but, like the narrow versions,
lengths that refer to the number of bytes.
I18n Issues
Use the appropriate version of the function as required for internationalization support, and ensure that cbDest is set to the byte size of the destination string buffer.
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
|
