WSNewUnicodeContainer (C Function)

WSUnicodeContainer * WSNewUnicodeContainer(void *s, int l, enum WSUnicodeContainerType t)

allocates and returns a new Unicode container containing a copy of the contents of the Unicode string s of length l, a string of type t.

Details

  • WSNewUnicodeContainer() allocates memory to store the Unicode string s that must be released. To release that memory, call WSReleaseUnicodeContainer() on the WSUnicodeContainer * object returned by WSNewUnicodeContainer().
  • WSNewUnicodeContainer() will return NULL in the event of an error.
  • Use WSNewUnicodeContainer() to allocate WSUnicodeContainer objects for use in WSTP template files.
  • WSNewUnicodeContainer() is used in conjunction with WSReleaseUnicodeContainer() to create and destroy 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 wstp.h.

Examples

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);
}