OpenersNotesSection(Spacer1)Details

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

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

Use MLNewUnicodeContainer() to allocate (NonWLLink[MLUnicodeContainer, paclet:/ref/c/MLUnicodeContainer]) objects for use in MathLink template files.

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

MLNewUnicodeContainer() is declared in the MathLink header file (RefLink[mathlink.h, paclet:/ref/file/mathlink.h]).

OpenersPrimaryExamplesSection(Spacer1)Examples  (1)

OpenersExampleSection0(Spacer1)Basic Examples  (1)

#include "mathlink.h"

/* A MathLink template program for converting a string to a symbol */

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

MLUnicodeContainer * convertStringToSymbol(const char *s)
{
	MLUnicodeContainer *newContainer;
	MLINK 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 = MLLoopbackOpen(stdenv, &error);
	if(link == NULL || error != MLEOK)
	{ /* Unable to create loopback link */ }

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

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

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

	/* The MLUnicodeContainer object is just for passing around
	Unicode strings and their lengths in an easy manner.  The
	MathLink template code will call MLReleaseUnicodeContainer()
	for the memory allocated by MLNewUnicodeContainer() */

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

	newContainer = MLNewUnicodeContainer(utf8String, utf8Length,
		UTF8ContainerType);

	MLReleaseUTF8String(link, utf8String, utf8Length);

	return newContainer;
}


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

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(NonWLLink[MLReleaseUnicodeContainer(), paclet:/ref/c/MLReleaseUnicodeContainer])  ▪  (NonWLLink[MLUnicodeContainer, paclet:/ref/c/MLUnicodeContainer])  ▪  (NonWLLink[MLUnicodeContainerType, paclet:/ref/c/MLUnicodeContainerType])  ▪  mprep  ▪  mcc  ▪  file.tm}})}})

({{DocumentationFooterIconsRelatedTutorial.png, ({{Tutorials}, {▪(RefLinkPlain[Setting Up External Functions to Be Called from the Wolfram Language, paclet:tutorial/SettingUpExternalFunctionsToBeCalledFromTheWolframLanguage])}})}})

({{DocumentationFooterIconsRelatedGuide.png, ({{Related Guides}, {▪(RefLinkPlain[Calling External Programs, paclet:guide/CallingExternalPrograms])}})}})