WSGetByteSymbol (C Function)

int WSGetByteSymbol(WSLINK link,const unsigned char **sp,int *len,long spec)

gets a character string corresponding to the name of a symbol from the WSTP connection specified by link, storing the resulting string in sp and the number of characters in len. The code spec is used for any character whose Wolfram Language character code is larger than 255.

Details

  • WSGetByteSymbol() allocates memory for the array of character codes. You must call WSReleaseByteSymbol() to disown this memory. If WSGetByteSymbol() fails the function's return value indicates an error, do not call WSReleaseByteSymbol() on the value contained in sp.
  • WSGetByteSymbol() is convenient in situations where no special characters occur.
  • The character codes used by WSGetByteSymbol() are exactly the ones returned by ToCharacterCode in the Wolfram Language.
  • The array of character codes returned by WSGetByteSymbol() is not terminated by a null character.
  • Characters such as newlines are specified by their raw character codes, not by ASCII forms such as .
  • WSGetByteSymbol() returns immutable data.
  • WSGetByteSymbol() returns 0 in the event of an error, and a nonzero value if the function succeeds.
  • Use WSError() to retrieve the error code if WSGetByteSymbol() fails.
  • WSGetByteSymbol() is declared in the WSTP header file wstp.h.

Examples

Basic Examples  (1)

#include "wstp.h"

/* read a symbol encoded with codes from ToCharacterCode[] from a link */

void f(WSLINK lp)
{
    const unsigned char *symbol;
    int length;

    if(! WSGetByteSymbol(lp, &symbol, &length, 0))
        {
            /* unable to read the byte-encoded symbol from lp */
            return;
        }

    /* ... */

    WSReleaseByteSymbol(lp, symbol, length);
}