Windows Safe String Function

HRESULT StringCchCopyN(LPTSTR pszDest, size_t cchDest, LPCTSTR pszSrc, size_t cchSrc);

HRESULT StringCchCopyNA(LPSTR pszDest, size_t cchDest, LPCSTR pszSrc, size_t cchSrc);

HRESULT StringCchCopyNW(LPWSTR pszDest, size_t cchDest, LPCWSTR pszSrc, size_t cchSrc);

HRESULT StringCchCopyNEx(LPTSTR pszDest, size_t cchDest, LPCTSTR pszSrc, size_t cchSrc, LPTSTR *ppszDestEnd, size_t *pcchRemaining, DWORD dwFlags);

HRESULT StringCchCopyNExA(LPSTR pszDest, size_t cchDest, LPCSTR pszSrc, size_t cchSrc, LPSTR *ppszDestEnd, size_t *pcchRemaining, DWORD dwFlags);

HRESULT StringCchCopyNExW(LPWSTR pszDest, size_t cchDest, LPCWSTR pszSrc, size_t cchSrc, LPWSTR *ppszDestEnd, size_t *pcchRemaining, DWORD dwFlags);

Internationalization (I18n) Function Overview

The StringCchCopyN function is a replacement for locale-sensitive string copy functions. It copies no more than cchSrc characters of pszStr to the end of pszDest, using the character size of the buffer stored in cchDest 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.

StringCchCopyNEx 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, StringCchCopyNA and StringCchCopyNExA, pass in single-byte or multibyte strings and lengths that refer to the number of single-byte characters.

The wide versions of these functions, StringCchCopyNW and StringCchCopyNExW, 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.

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	StringCchCopyN/StringCchCopyNEx or StringCchCopyNA/StringCchCopyNExA
Microsoft Windows Unicode	StringCchCopyN/StringCchCopyNEx or StringCchCopyNW/StringCchCopyNExW
Microsoft Windows Generic	StringCchCopyN/StringCchCopyNEx

Windows Safe String Functions