Locale-Sensitive Length Function

char *stpncpy(char *restrict to, const char *restrict from, size_t size);

wchar_t *wcpncpy(wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size);

Internationalization (I18n) Function Overview

stpncpy is similar to stpcpy but copies always exactly size bytes into to.

wcpncpy is similar to wcpcpy but copies always exactly wsize wide characters into wto.

If the length of from or wfrom is more than size, then stpncpy or wcpncpy copies just the first size bytes or characters respectively, and returns a pointer to the character directly following the one which was copied last. Note that in this case there is no null terminator written into to or wto.

I18n Issues

Note that while the documentation says stpncpy copies size characters it actually copies size bytes. This makes this function locale-sensitive in UTF-8 multibyte environments. For example, consider the simple case of a string which consists of a single multibyte character which contains 2 bytes. If stpncpy is used with a parameter of 1, only half of the multibyte character will be copied, resulting in an ill-formed string.

Special care therefore must be taken with the size parameter for UTF-8 strings. If there is potential for the string to contain multibyte UTF-8 characters and the size parameter may by chance truncate one of these characters as in the example above, or if its important that size characters are copied instead of size bytes, then you will have to do the following.

In this case, the parameters will have to be converted to wide characters (wchar_t) and then the wide function wcpncpy can be used. The resulting wide string will then have to be converted back to multibyte UTF-8 characters afterwards. Note that the pointer returned by wcpncpy is into the wide string and not the subsequently reconverted UTF-8 string.

See Locale-Sensitive Length Functions for further discussion of the issues involved with functions that pass length parameters.

Recommended Replacements*

ANSI UTF-8	convert and use wcpncpy
	(See "I18n Issues" above)
ANSI UTF-16	wcpncpy

Locale-Sensitive Length Functions