DynaPDF Manual - Page 819

Previous Page 818   Index   Next Page 820

Function Reference
Page 819 of 839
The used conversion algorithm is binary save. The parameter Len holds the string length in
characters before and after conversion. The new string length is normally not longer then original
one, but it is possible that the new string length will be shorter because surrogates are expressed as
two character sequence in UTF-16, but as one character in UTF-32.
The return value is a pointer to the original conversion buffer; it must not be freed or changed. The
function can be called multiple times without causing a memory leak. However, if the conversion
buffer is no longer needed it can be released with the function FreeUniBuf(). The buffer is
automatically released when CloseFile() or FreePDF() is called.
The function requires no open PDF file; it can be used at any time. Invalid character sequences are
skipped by the algorithm, they do not break conversion.
Return values:
If the function succeeds the return value is a pointer to the converted UTF-32 Unicode string. If the
function fails the return value is NULL. The only possible error during conversion is out of memory.
UTF32ToUTF16
Syntax:
UI16* pdfUTF32ToUTF16(
const PPDF* IPDF,
// Instance pointer
const UI32* Source) // Null-terminated UTF-32 Unicode string
The function converts a UTF-32 Unicode string to UTF-16. UTF-32 is the default Unicode format on
Linux and UNIX operating systems. This function uses the macro ToUTF16() which can be used to
convert UTF-32 strings to UTF-16.
The macro is mostly used to convert literal strings in parameterized function calls which can contain
more than one Unicode parameter. To enable the usage in functions with more than one string
parameter, the function holds an array of six separate conversion buffers so that a second or third
call of the macro does not override or free the buffer of a previous call.
Example:
// Linux uses UTF-32 as Unicode string format
Anyfunction(pdf, ToUTF16(pdf, L"First"), ToUTF16(pdf, L"Second"),
ToUTF16(pdf, L"Third!"));
The code above produces no access violation because each call of the macro ToUTF16() uses its own
conversion buffer. DynaPDF contains no function that supports more than three Unicode string
parameters so that the number of six separate conversion buffers is large enough for all functions
which are currently defined in DynaPDF.
The number of conversion buffers is defined by the constant PDF_UTF16_BUF_COUNT in the
header file pdf_main.h; it can be changed if necessary (you need the source code of DynaPDF and
the library must be recompiled when changing the value).
 

Previous topic: UnLockLayer, UTF16ToUTF32, UTF16ToUTF32Ex

Next topic: UTF32ToUTF16Ex