file.tm

file.tm

is a WSTP template file.

Details

  • WSTP template files contain templates for linking external C functions to Wolfram Language functions.
  • Each template can contain the following:
  • :Begin:begin the template for a particular function
    :Function:the name of the function in the external program
    :Pattern:the pattern to be defined to call the function
    :Arguments:the arguments to the function
    :ArgumentTypes:the types of the arguments to the function
    :ReturnType:the type of value returned from the function
    :End:end the template
    :Evaluate:Wolfram Language input to evaluate when the function is installed
    ::texttreat as a comment
  • Arbitrary C code can be interspersed between templates in a .tm file.
  • The following argument and return type specifications can be used:
  • Integer16short
    Integer32int
    Integer64mlint64
    Real32float
    Real64double
    Real128mlextended_double
    Integer16Listshort*, int (length)
    Integer32Listint*, int (length)
    Integer64Listmlint64*, int (length)
    Real32Listfloat*, int (length)
    Real64Listdouble*, int (length)
    Real128Listmlextended_double*, int (length)
    Stringchar*
    ByteStringunsigned char* and int (length)
    UCS2Stringunsigned short*
    UTF8Stringunsigned char*, int (bytes), int (characters)
    UTF16Stringunsigned short*, int (length), int (characters)
    UTF32Stringunsigned int*, and int (length)
    Symbolchar*
    ByteSymbolunsigned char*, int (length)
    UCS2Symbolunsigned short*, int (length)
    UTF8Symbolunsigned char*, int (bytes), int (characters)
    UTF16Symbolunsigned short*, int (length), int (characters)
    UTF32Symbolunsigned int*, int (length)
    ThisLinkWSLINK
    $CurrentLinkWSLINK
    Manualvoid
  • In order to use UCS2String, UCS2Symbol, UTF8String, UTF8Symbol, UTF16String, UTF16Symbol, UTF32String, and UTF32Symbol as a return type, the programmer must allocate a WSUnicodeContainer object to return in place of the Unicode string.
  • The WSUnicodeContainer object is a wrapper that contains a copy of the Unicode string and its length for easily passing Unicode strings between functions in a template file.
  • wsprep will only generate function signatures with WSUnicodeContainer as the return type when the return type is one of the listed Unicode string or symbol types. wsprep will not generate code that passes a WSUnicodeContainer object as an argument to a function when one of the arguments is a Unicode string or symbol type.
  • WSTP template files are converted to C code using wsprep. They are also processed automatically by wscc when available.

Examples

Basic Examples  (1)

Template file entry for a function named f that takes two integers as arguments and returns an integer:

:Begin:
:Function:        f
:Pattern:        f[x_Integer, y_Integer]
:Arguments:        {x, y}
:ArgumentTypes:    {Integer, Integer}
:ReturnType:    Integer
:End: