OpenersNotesSection(Spacer1)Details

WSNewUnicodeContainer() allocates memory to store the Unicode string s that must be released. To release that memory, call WSReleaseUnicodeContainer() on the (NonWLLink[WSUnicodeContainer, paclet:ref/c/WSUnicodeContainer]) * object returned by WSNewUnicodeContainer().

WSNewUnicodeContainer() will return NULL in the event of an error.

Use WSNewUnicodeContainer() to allocate (NonWLLink[WSUnicodeContainer, paclet:ref/c/WSUnicodeContainer]) objects for use in WSTP template files.

WSNewUnicodeContainer() is used in conjunction with (NonWLLink[WSReleaseUnicodeContainer(), paclet:ref/c/WSReleaseUnicodeContainer]) to create and destroy (NonWLLink[WSUnicodeContainer, paclet:ref/c/WSUnicodeContainer]) objects in WSTP template files. The WSUnicodeContainer is a convenient object for passing Unicode strings and their lengths between functions in template files.

WSNewUnicodeContainer() 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 WSTP template program for converting a string to a symbol */

:Begin:
:Function:       convertStringToSymbol
:Pattern:        ConvertStringToSymbol[string_String]
:Arguments:      {string}
:ArgumentTypes:  {String}
:ReturnType:     UTF8Symbol
:End:

WSUnicodeContainer * convertStringToSymbol(const char *s)
{
	WSUnicodeContainer *newContainer;
	WSLINK link;
	int error;

	unsigned char *utf8String;
	int utf8Length, utf8Chars;

	/* Use a loopback link to convert the string from Mathematica
	form to a UTF-8 encoded version */

	link = WSLoopbackOpen(stdenv, &error);
	if(link == NULL || error != WSEOK)
	{ /* Unable to create loopback link */ }

	if(! WSPutString(link, s))
	{ /* Unable to send the string to the loopback link */ }

	if(! WSFlush(link))
	[ /* Unable to flush the link buffers */ }

	if(! WSGetUTF8String(link, &utf8String, &utf8Length, &utf8Chars))
	{ /* Unable to read the UTF-8 encoded string */ }

	/* The WSUnicodeContainer object is just for passing around
	Unicode strings and their lengths in an easy manner.  The
	WSTP template code will call WSReleaseUnicodeContainer()
	for the memory allocated by WSNewUnicodeContainer() */

	/* UTF8ContainerType is the enum value that indicates the
	WSUnicodeContainer object contains an UTF-8 encoded string */

	newContainer = WSNewUnicodeContainer(utf8String, utf8Length,
		UTF8ContainerType);

	WSReleaseUTF8String(link, utf8String, utf8Length);

	return newContainer;
}


int main(int argc, char **argv)
{
	return WSMain(argc, argv);
}

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(NonWLLink[WSReleaseUnicodeContainer(), paclet:ref/c/WSReleaseUnicodeContainer])  ▪  (NonWLLink[WSUnicodeContainer, paclet:ref/c/WSUnicodeContainer])  ▪  (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])}})}})