◆ ConvertMBSToWide()

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

noexcept

Converts a multibyte string to its wide equivalent and returns a number of successfully converted characters using the current locale.

Parameters

[out]	pStringW	is an optional buffer capable to store cchStringW wide characters of the converted wide string. If the pointer is NULL, cchStringW specifies a number of wide characters that, at most, are required by the caller. Anyway the function returns a number of wide characters that would have been produced if a valid pStringW buffer of cchStringW character size have been passed to the function with the same other parameters. The resulting string is not zero-terminated.
[in]	cchStringW	specifies a capacity of the output buffer or, if the pStringW is NULL, a number of wide characters would have been written to the output as a result of the conversion.
[in]	pStringMB	specifies an input multibyte string. The length of the string is specified by cbStringMB in bytes or, if cbStringMB is (size_t) -1 by the terminating zero character. Also if the terminating zero appears among the first cbStringMB bytes of the input string it is ignored together with the rest characters. Thus if pStringMB is zero-terminated, a value of cbStringMB can be (size_t) -1; also if cbStringMB specifies an actual length of the converted string, the latter need not to be zero-terminated.
[in]	cbStringMB	is a length, in bytes, of the multibyte string. If cbStringMB is (size_t) -1, the string must be zero-terminated. If the null terminator is found among cbStringMB bytes of the multibyte string, the rest part of the string is not taken into account as well as the terminator itself.

Returns: If pStringW is NULL the function returns a number of characters would have been produced if a valid pStringW buffer of cchStringW character size have been passed to the function with the same other parameters. If pStringW is not NULL the function returns an actual length of the converted string in wide characters. The returned value does not include a terminating zero which is not converted. On failure the function returns (size_t) -1 setting corresponding chsvlib error code. If the conversion fails because of an invalid multibyte sequence, the function fails and sets chsvlib error code to CHSVERROR_INVALID_CHAR_SEQUENCE.

Remarks: The length of the source multibyte string is given by cbStringMB, in bytes, or by the null character if cbStringMB is (size_t) -1 or if 0 terminator appears among the cbStringMB characters of the source string.; If the pStringW is NULL, the function returns a number of characters would have been produced if a valid pStringW buffer of cchStringW character size have been passed to the function with the same other parameters.; If the size of the pStringW buffer is not large enough to store all of the converted symbols, the function stops conversion and returns a number of characters successfully written to the pStringW buffer.; If the null character is found in the input string the function stops the conversion and returns. The null terminator is not converted.; If the last part of the source string constitutes an incomplete but potentially valid multibyte character, it is ignored by the function.

Warning: The function neither converts nor generates the terminating zero character in the output string even if a zero 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 ConvertUTF8ToUCS function.