◆ ConvertWideToMBS()

std:: size_t Chusov::String::ConvertWideToMBS	(	char *restrict	pStringMB,
		std::size_t	cbStringMB,
		const wchar_t *restrict	pStringW,
		std::size_t *	pcchStringW
	)

noexcept

Converts a wide string to a multibyte equivalent and returns a number of bytes occupied by the converted multibyte string using the current locale.

Parameters

[out]	pStringMB	is a pointer to an output buffer receiving the converted multibyte string. The size of the buffer, in bytes, is specified by cbStringMB value. An actual length of the converted string, in bytes, is returned by the function. If the null character is found in the input string the function stops the conversion and returns. The null terminator is not converted.
[in]	cbStringMB	specifies a byte size of the pStringMB buffer. If the pStringMB is NULL the parameter specifies a number of bytes of the output required by the caller or that would have been written if the caller would have passed a non-NULL buffer of cbStringMB bytes of size.
[in]	pStringW	is a pointer to a wide string to be converted to its multibyte equivalent. Its size, in wide characters is given by an input value of pcchStringW or by an input zero-terminator. Thus if pcchStringW is not NULL or if it holds a value that is not (size_t) -1, the input wide string need not to be zero-terminated.
[in,out]	pcchStringW	on input specifies a length, in wide characters, of the string to be converted. On output the pointer holds a number of wide characters successfully converted and, if pStringMB is not NULL, written to the output buffer. The parameter can be NULL. If it is NULL, or the value it is associated with is (size_t) -1, the input string must be zero-terminated. Also if a null character appears among the first *pcchStringW characters of the string, the last part of the string is ignored.

Returns: On success the function returns a number of bytes that are written (or could been written if pStringMB was NULL) to cbStringMB bytes of the output buffer without the zero-terminator which is not converted. No incomplete symbols finishing the string are considered. On failure the function returns (size_t) -1 setting corresponding chsvlib error code.

Remarks: The length of the source wide string is given in characters by the input value of pcchStringW parameter or by the null character if pcchStringW is NULL, *pcchStringMB is (size_t) -1 or if 0 terminator appears among the *pcchStringW characters of the source string.; If the size of the pStringMB buffer is not large enough to store all of the converted complete symbols, the function stops the conversion and returns a number of bytes successfully written to the pString buffer. No incomplete symbols are written to the output.; If the pcchStringW is NULL or if *pcchStringW is (size_t) -1, the input string must be zero-terminated.; If the pStringMB is NULL, the function returns a number of bytes needed to store *pcchStringW characters of the converted string (or the whole string if pcchStringW is NULL) without the null terminator. In both cases output value of the pcchStringW (if specified) contains a number of characters converted so that the resulting string is not longer than cbStringMB bytes.

Note: Set cbStringMB to (size_t) -1 to get the required size of the output buffer to hold the entire converted string.

Warning: The function neither converts nor generates the terminating zero character in the output string even if a zero wide character is in the input.; MS C/C++ compilers do not provide support for UTF-8 or any other encodings with variable-length characters. Therefore the function cannot be used for converting strings to these encodings. For UTF-8 and UCS-2/UCS-4 encodings use the ConvertUCSToUTF8 function.