You are here: C++ API > Functions > dtssUtf8Encode2 Function
Close
dtSearch Text Retrieval Engine Programmer's Reference
dtssUtf8Encode2 Function

File: dtsearch.h

Syntax
C++
ptrdiff_t DLLFUNC dtssUtf8Encode2(char * dest, ptrdiff_t cchDest, const wchar_t * toEncode, ptrdiff_t cchSource, __int64 * cchNeeded);
Parameters
Description
char * dest
Buffer to receive UTF-8 text
ptrdiff_t cchDest
Size of dest buffer in bytes
ptrdiff_t cchSource
Number of unicode characters to convert
__int64 * cchNeeded
Pointer to 64-bit interer to hold the number of characters needed to store the encoded result, if the buffer provided was too small.
source
Unicode (UTF-16) text to convert

Number of characters in the conversion output, excluding the terminating null.

Convert Unicode to UTF-8

If the buffer provided in dest is insufficient to store the conversion result, the required buffer size will be provided in cchNeeded. 

If the buffer provided was large enough to store the result, cchNeeded will not be changed. 

To use this API efficiently, callers should initialize cchNeeded to zero, provide an output buffer that is large enough to handle the the most common cases, and then check cchNeeded after the conversion is done to determine whether a larger buffer is needed. This avoids the need to call the API twice in the most common cases. 

Conversion to UTF-8 can generate output with up to 5 times the number of characters as the input, so even with a 32-bit value for cchSource, the value in cchNeeded may be too large to fit in a 32-bit integer.

Copyright (c) 1995-2022 dtSearch Corp. All rights reserved.