WSGetInteger8Array (C Function)

int WSGetInteger8Array( WSLINK l , unsigned char ** s , int ** d , char *** h , int * depth )

gets an array of 8-bit integers from the WSTP connection specified by l, storing the array in s, its dimensions in d, heads in h, and its depth in depth.

Details

  • The array s is laid out in memory like a C array declared as unsigned char s[m][n].
  • h gives a list of character strings corresponding to the names of the symbols that appear as heads at each level in the array.
  • WSGetInteger8Array() allocates memory that must be released by calling WSReleaseInteger8Array(). If WSGetInteger8Array() fails and the function's return value indicates an error, do not call WSReleaseInteger8Array() on the contents of s.
  • WSGetInteger8Array() returns immutable data.
  • WSGetInteger8Array() returns 0 in the event of an error, and a nonzero value if the function succeeds.
  • Use WSError() to retrieve the error code if WSGetInteger8Array() fails.
  • WSGetInteger8Array() is declared in the WSTP head file wstp.h.

Examples

Basic Examples  (1)

#include "wstp.h"

/* A function for reading an array of 8-bit integers from a link */

void f(WSLINK l)
{
    unsigned char *data;
    int *dims;
    char **heads;
    int depth;

    if(! WSGetInteger8Array(l, &data, &dims, &heads, &depth))
    { /* Unable to read the array of integers from l */ }

    /* ... */

    WSReleaseInteger8Array(l, data, dims, heads, depth);
}