OpenersNotesSection(Spacer1)Details

Use the convenience macro WSUnicodeStringLength(container) to access the number of code units used to store the Unicode string. The code unit type varies according to the type of Unicode string contained in the container.

Use the convenience macros WSUCS2String(container), WSUTF8String(container), WSUTF16String(container), and WSUTF32String(container) to get a pointer to the first code unit of the string contained in the container.

Use the convenience macro WSUnicodeStringType(container) to access the (NonWLLink[WSUnicodeContainerType, paclet:ref/c/WSUnicodeContainerType]) value of the string in the container.

The convenience macros operate on pointers to WSUnicodeContainer.

In most cases the programmer will not need to access the contents of the WSUnicodeContainer object, but instead will pass it as a return value to a WSTP template function when using one of the following mprep return types: UCS2String, UCS2Symbol, UTF8String, UTF8Symbol, UTF16String, UTF16Symbol, UTF32String, and UTF32Symbol.

Use the WSTP API function (NonWLLink[WSNewUnicodeContainer(), paclet:ref/c/WSNewUnicodeContainer]) to allocate a new container object. Use (NonWLLink[WSReleaseUnicodeContainer(), paclet:ref/c/WSReleaseUnicodeContainer]) to release the memory used by the object.

In most cases the programmer will not need to directly invoke (NonWLLink[WSReleaseUnicodeContainer(), paclet:ref/c/WSReleaseUnicodeContainer]) to free an WSUnicodeContainer object. Instead, mprep will generate code that automatically releases an WSUnicodeContainer object.

WSUnicodeContainer is declared in the WSTP header file (RefLink[wstp.h, paclet:ref/file/wstp.h]).

OpenersPrimaryExamplesSection(Spacer1)Examples  (1)

OpenersExampleSection0(Spacer1)Basic Examples  (1)

#include "wstp.h"

/* A simple function for sending a Unicode string using a WSUnicodeContainer object */

void f(WSUnicodeContainer *container, WSLINK link)
{
	if(container == (WSUnicodeContainer *)0)
		return;

	switch(WSUnicodeStringType(container))
	{
		case UCS2ContainerType:
			if(! WSPutUCS2String(link, WSUCS2String(container),
				WSUnicodeStringLength(container)))
			{ /* Unable to send the UCS-2 encoded string */ }
			break;
		case UTF8ContainerType:
			if(! WSPutUTF8String(link, WSUTF8String(container), 
				WSUnicodeStringLength(container)))
			{ /* Unable to send the UTF-8 encoded string */ }
			break;
		case UTF16ContainerType:
			if(! WSPutUTF16String(link, WSUTF16String(container), 
				WSUnicodeStringLength(container)))
			{ /* Unable to send the UTF-16 encoded string */ }
			break;
		case UTF32ContainerType:
			if(! WSPutUTF32String(link, WSUTF32String(container), 
				WSUnicodeStringLength(container)))
			{ /* Unable to send the UTF-32 encoded string */ }
			break;
	}

	WSReleaseUnicodeContainer(container);
}

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(NonWLLink[WSNewUnicodeContainer(), paclet:ref/c/WSNewUnicodeContainer])  ▪  (NonWLLink[WSReleaseUnicodeContainer(), paclet:ref/c/WSReleaseUnicodeContainer])  ▪  (NonWLLink[WSUnicodeContainerType, paclet:ref/c/WSUnicodeContainerType])  ▪  mprep  ▪  mcc  ▪  file.tm}})}})

({{DocumentationFooterIconsRelatedTutorial.png, ({{Tutorials}, {▪(RefLinkPlain[Setting Up External Functions to Be Called from the Wolfram Language, paclet:tutorial/SettingUpExternalFunctionsToBeCalledFromTheWolframLanguage])}, {▪(RefLinkPlain[WSTP and External Program Communication, paclet:tutorial/WSTPAndExternalProgramCommunicationOverview])}, {▪(RefLinkPlain[WSTP Developer Guide (Windows), paclet:tutorial/WSTPDeveloperGuide-WindowsOverview])}, {▪(RefLinkPlain[WSTP Developer Guide (Mac), paclet:tutorial/WSTPDeveloperGuide-MacintoshOverview])}, {▪(RefLinkPlain[WSTP Developer Guide (Linux), paclet:tutorial/WSTPDeveloperGuide-UnixOverview])}})}})

({{DocumentationFooterIconsRelatedGuide.png, ({{Related Guides}, {▪(RefLinkPlain[Calling External Programs, paclet:guide/CallingExternalPrograms])}, {▪(RefLinkPlain[C/C++ Language Interface, paclet:guide/CLanguageInterface])}, {▪(RefLinkPlain[Installable WSTP Programs, paclet:guide/InstallableWSTPPrograms])}, {▪(RefLinkPlain[WSTP API, paclet:guide/WSTPAPI])}})}})