Windows Safe String Function

HRESULT StringCbPrintf(LPTSTR pszDest, size_t cbDest, LPCTSTR pszFormat, ...);

HRESULT StringCbPrintfA(LPSTR pszDest, size_t cbDest, LPCSTR pszFormat, ...);

HRESULT StringCbPrintfW(LPWSTR pszDest, size_t cbDest, LPCWSTR pszFormat, ...);

HRESULT StringCbPrintfEx(LPTSTR pszDest, size_t cbDest, LPTSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags, LPCTSTR pszFormat, ...);

HRESULT StringCbPrintfExA(LPSTR pszDest, size_t cbDest, LPSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags, LPCSTR pszFormat, ...);

HRESULT StringCbPrintfExW(LPWSTR pszDest, size_t cbDest, LPWSTR *ppszDestEnd, size_t *pcbRemaining, DWORD dwFlags, LPCWSTR pszFormat, ...);

Internationalization (I18n) Function Overview

The StringCbPrintf is a replacement for locale-sensitive formatting functions. It returns a formatted string in pszDest, using the format string pzsFormat and a variable list of arguments. 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.

StringCbPrintfEx 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, StringCbPrintfA and StringCbPrintfExA, pass in single-byte or multibyte strings and lengths that refer to the number of bytes.

The wide versions of these functions, StringCbPrintfW and StringCbPrintfExW, 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:

Microsoft Windows MBCS	StringCbPrintf/StringCbPrintfEx or StringCbPrintfA/StringCbPrintfExA
Microsoft Windows Unicode	StringCbPrintf/StringCbPrintfEx or StringCbPrintfW/StringCbPrintfExW
Microsoft Windows Generic	StringCbPrintf/StringCbPrintfEx

Windows Safe String Functions