This is ForeignFunctions.info, produced by Macaulay2, version 1.24.11

ForeignFunctions -- foreign function interface
**********************************************

Description
===========

This package provides the ability to load and call "foreign" functions from
shared libraries and to convert back and forth between Macaulay2 things and the
foreign objects used by these functions.  It is powered by libffi (see
https://sourceware.org/libffi/ ).

As a simple example, we call the cos function from the C standard library,
which sends a double (a real number represented as a double-precision floating
point number) to another double, the cosine of the input.

+---------------------------------------------------+
|i1 : mycos = foreignFunction("cos", double, double)|
|                                                   |
|o1 = cos                                           |
|                                                   |
|o1 : ForeignFunction                               |
+---------------------------------------------------+
|i2 : mycos pi                                      |
|                                                   |
|o2 = -1                                            |
|                                                   |
|o2 : ForeignObject of type double                  |
+---------------------------------------------------+
|i3 : value oo                                      |
|                                                   |
|o3 = -1                                            |
|                                                   |
|o3 : RR (of precision 53)                          |
+---------------------------------------------------+

In this example, we created a ForeignFunction object using the
foreignFunction, constructor method and specified that both
its output and input were instances of the double, type,
which is one of several ForeignType, objects that are
available.

See also the following additional examples:

  * fast Fourier transform example, --
    fast Fourier transforms using foreign function calls to the FFTW library
  * general linear model example, --
    constrained least squares using foreign function calls to the LAPACK
    library
  * just-in-time compilation example,
    -- using foreign function calls for computing Fibonacci numbers using JIT

Author
======

  * Doug Torrance (see https://webwork.piedmont.edu/~dtorrance )
    <dtorrance@piedmont.edu>

Version
=======

This documentation describes version 0.4 of ForeignFunctions.

Source code
===========

The source code from which this documentation is derived is in the file
ForeignFunctions.m2 (see common/share/Macaulay2/ForeignFunctions.m2 ).

Exports
=======

  * Types
      * ForeignArrayType -- foreign array type
      * "ForeignFunction" -- see foreignFunction, --
        construct a foreign function
      * "char'" -- see ForeignIntegerType, -- foreign
        integer type
      * ForeignIntegerType -- foreign integer type
      * "int" -- see ForeignIntegerType, -- foreign
        integer type
      * "int8" -- see ForeignIntegerType, -- foreign
        integer type
      * "int16" -- see ForeignIntegerType, -- foreign
        integer type
      * "int32" -- see ForeignIntegerType, -- foreign
        integer type
      * "int64" -- see ForeignIntegerType, -- foreign
        integer type
      * "long" -- see ForeignIntegerType, -- foreign
        integer type
      * "short" -- see ForeignIntegerType, -- foreign
        integer type
      * "uchar" -- see ForeignIntegerType, -- foreign
        integer type
      * "uint" -- see ForeignIntegerType, -- foreign
        integer type
      * "uint8" -- see ForeignIntegerType, -- foreign
        integer type
      * "uint16" -- see ForeignIntegerType, --
        foreign integer type
      * "uint32" -- see ForeignIntegerType, --
        foreign integer type
      * "uint64" -- see ForeignIntegerType, --
        foreign integer type
      * "ulong" -- see ForeignIntegerType, -- foreign
        integer type
      * "ushort" -- see ForeignIntegerType, --
        foreign integer type
      * ForeignObject -- foreign object
      * "charstarstar" -- see ForeignPointerArrayType,
        -- foreign type for NULL-terminated arrays of
        pointers
      * ForeignPointerArrayType -- foreign type
        for NULL-terminated arrays of pointers
      * "voidstarstar" -- see ForeignPointerArrayType,
        -- foreign type for NULL-terminated arrays of
        pointers
      * ForeignPointerType -- foreign pointer type
      * "voidstar" -- see ForeignPointerType, --
        foreign pointer type
      * "double" -- see ForeignRealType, -- foreign real
        type
      * "float" -- see ForeignRealType, -- foreign real
        type
      * ForeignRealType -- foreign real type
      * "charstar" -- see ForeignStringType, --
        foreign string type
      * ForeignStringType -- foreign string type
      * ForeignStructType -- foreign struct type
      * ForeignType -- abstract foreign type
      * ForeignUnionType -- foreign union type
      * ForeignVoidType -- foreign void type
      * "void" -- see ForeignVoidType, -- foreign void
        type
      * mpfrT -- MPFR multiple-precision floating-point type
      * mpzT -- GMP arbitrary-precision integer type
      * Pointer -- pointer to memory address
      * SharedLibrary -- a shared library
  * Functions and commands
      * address -- pointer to type or object
      * foreignArrayType -- construct a foreign array
        type
      * foreignFunction -- construct a foreign function
      * foreignObject -- construct a foreign object
      * foreignPointerArrayType -- construct a
        foreign pointer array type
      * foreignStructType -- construct a foreign
        struct type
      * foreignSymbol -- get a foreign symbol
      * foreignUnionType -- construct a foreign union
        type
      * getMemory -- allocate memory using the garbage
        collector
      * openSharedLibrary -- open a shared library
  * Methods
      * "* Pointer = Thing" -- see * voidstar = Thing,
        -- assign value to object at address
      * * voidstar = Thing -- assign value to
        object at address
      * "address(ForeignObject)" -- see address, -- pointer to
        type or object
      * "address(ForeignType)" -- see address, -- pointer to
        type or object
      * address(Nothing) (missing documentation)
      * expression(mpfrT) (missing documentation)
      * "foreignArrayType(ForeignType,ZZ)" -- see foreignArrayType,
        -- construct a foreign array type
      * "foreignArrayType(String,ForeignType,ZZ)" -- see
        foreignArrayType, -- construct a foreign array type
      * "ForeignType * ZZ" -- see foreignArrayType, --
        construct a foreign array type
      * "ZZ * ForeignType" -- see foreignArrayType, --
        construct a foreign array type
      * ForeignArrayType VisibleList, --
        cast a Macaulay2 list to a foreign array
      * "foreignFunction(Pointer,String,ForeignType,VisibleList)" -- see
        foreignFunction, -- construct a foreign function
      * "foreignFunction(SharedLibrary,String,ForeignType,ForeignType)" -- see
        foreignFunction, -- construct a foreign function
      * "foreignFunction(SharedLibrary,String,ForeignType,VisibleList)" -- see
        foreignFunction, -- construct a foreign function
      * "foreignFunction(String,ForeignType,ForeignType)" -- see
        foreignFunction, -- construct a foreign function
      * "foreignFunction(String,ForeignType,VisibleList)" -- see
        foreignFunction, -- construct a foreign function
      * ForeignIntegerType Number -- cast a
        Macaulay2 number to a foreign integer object
      * "new int8 from ZZ" -- see ForeignIntegerType Number,
        -- cast a Macaulay2 number to a foreign
        integer object
      * "new int16 from ZZ" -- see ForeignIntegerType Number,
        -- cast a Macaulay2 number to a foreign
        integer object
      * "new int32 from ZZ" -- see ForeignIntegerType Number,
        -- cast a Macaulay2 number to a foreign
        integer object
      * "new int64 from ZZ" -- see ForeignIntegerType Number,
        -- cast a Macaulay2 number to a foreign
        integer object
      * "new uint8 from ZZ" -- see ForeignIntegerType Number,
        -- cast a Macaulay2 number to a foreign
        integer object
      * "new uint16 from ZZ" -- see ForeignIntegerType Number,
        -- cast a Macaulay2 number to a foreign
        integer object
      * "new uint32 from ZZ" -- see ForeignIntegerType Number,
        -- cast a Macaulay2 number to a foreign
        integer object
      * "new uint64 from ZZ" -- see ForeignIntegerType Number,
        -- cast a Macaulay2 number to a foreign
        integer object
      * "foreignObject(ForeignObject)" -- see foreignObject,
        -- construct a foreign object
      * "foreignObject(Number)" -- see foreignObject, --
        construct a foreign object
      * "foreignObject(Pointer)" -- see foreignObject, --
        construct a foreign object
      * "foreignObject(String)" -- see foreignObject, --
        construct a foreign object
      * "foreignObject(VisibleList)" -- see foreignObject,
        -- construct a foreign object
      * "foreignObject(ZZ)" -- see foreignObject, --
        construct a foreign object
      * "charstarstar _ ZZ" -- see ForeignPointerArrayType,
        -- foreign type for NULL-terminated arrays of
        pointers
      * "charstarstar _ ZZ = Thing" -- see ForeignPointerArrayType,
        -- foreign type for NULL-terminated arrays of
        pointers
      * "iterator(charstarstar)" -- see ForeignPointerArrayType,
        -- foreign type for NULL-terminated arrays of
        pointers
      * "iterator(voidstarstar)" -- see ForeignPointerArrayType,
        -- foreign type for NULL-terminated arrays of
        pointers
      * "length(charstarstar)" -- see ForeignPointerArrayType,
        -- foreign type for NULL-terminated arrays of
        pointers
      * "length(voidstarstar)" -- see ForeignPointerArrayType,
        -- foreign type for NULL-terminated arrays of
        pointers
      * "voidstarstar _ ZZ" -- see ForeignPointerArrayType,
        -- foreign type for NULL-terminated arrays of
        pointers
      * "voidstarstar _ ZZ = Thing" -- see ForeignPointerArrayType,
        -- foreign type for NULL-terminated arrays of
        pointers
      * "foreignPointerArrayType(ForeignType)" -- see
        foreignPointerArrayType, -- construct a
        foreign pointer array type
      * "foreignPointerArrayType(String,ForeignType)" -- see
        foreignPointerArrayType, -- construct a
        foreign pointer array type
      * ForeignPointerArrayType VisibleList
        -- cast a Macaulay2 list to a foreign pointer array
      * "new charstarstar from VisibleList" -- see
        ForeignPointerArrayType VisibleList,
        -- cast a Macaulay2 list to a foreign pointer array
      * "new voidstarstar from VisibleList" -- see
        ForeignPointerArrayType VisibleList,
        -- cast a Macaulay2 list to a foreign pointer array
      * ForeignPointerType Pointer -- cast a
        Macaulay2 pointer to a foreign pointer
      * ForeignRealType Number -- cast a
        Macaulay2 number to a foreign real object
      * "ForeignRealType RRi" -- see ForeignRealType Number,
        -- cast a Macaulay2 number to a foreign real
        object
      * "new double from RR" -- see ForeignRealType Number,
        -- cast a Macaulay2 number to a foreign real
        object
      * "new float from RR" -- see ForeignRealType Number,
        -- cast a Macaulay2 number to a foreign real
        object
      * ForeignStringType String -- cast a
        Macaulay2 string to a foreign string
      * "foreignStructType(String,Option)" -- see foreignStructType,
        -- construct a foreign struct type
      * "foreignStructType(String,VisibleList)" -- see foreignStructType,
        -- construct a foreign struct type
      * "ForeignStructType HashTable" -- see ForeignStructType VisibleList,
        -- cast a hash table to a
        foreign struct
      * ForeignStructType VisibleList, --
        cast a hash table to a foreign struct
      * "foreignSymbol(SharedLibrary,String,ForeignType)" -- see
        foreignSymbol, -- get a foreign symbol
      * "foreignSymbol(String,ForeignType)" -- see foreignSymbol,
        -- get a foreign symbol
      * "net(ForeignType)" -- see ForeignType, -- abstract
        foreign type
      * ForeignType * voidstar -- dereference
        a voidstar object
      * "ForeignStructType ForeignObject" -- see ForeignType ForeignObject,
        -- cast a foreign object to
        the given foreign type
      * ForeignType ForeignObject -- cast a
        foreign object to the given foreign type
      * ForeignType Pointer -- dereference a
        pointer
      * "foreignUnionType(String,Option)" -- see foreignUnionType,
        -- construct a foreign union type
      * "foreignUnionType(String,VisibleList)" -- see foreignUnionType,
        -- construct a foreign union type
      * ForeignUnionType Thing -- cast a thing
        to a foreign union
      * "ForeignVoidType Nothing" -- see ForeignVoidType,
        -- foreign void type
      * "getMemory(ForeignType)" -- see getMemory, -- allocate
        memory using the garbage collector
      * "getMemory(ForeignVoidType)" -- see getMemory, --
        allocate memory using the garbage collector
      * "getMemory(ZZ)" -- see getMemory, -- allocate memory
        using the garbage collector
      * "new mpfrT from RR" -- see mpfrT, -- MPFR
        multiple-precision floating-point type
      * "value(mpfrT)" -- see mpfrT, -- MPFR multiple-precision
        floating-point type
      * "new mpzT from ZZ" -- see mpzT, -- GMP arbitrary-precision
        integer type
      * "value(mpzT)" -- see mpzT, -- GMP arbitrary-precision
        integer type
      * net(ForeignFunction) (missing documentation)
      * new ForeignType (missing documentation)
      * "openSharedLibrary(String)" -- see openSharedLibrary,
        -- open a shared library
      * "Pointer + ZZ" -- see Pointer, -- pointer to memory
        address
      * "Pointer - ZZ" -- see Pointer, -- pointer to memory
        address
      * "ZZ + Pointer" -- see Pointer, -- pointer to memory
        address
      * registerFinalizer(ForeignObject,Function)
        -- register a
        finalizer for a foreign object
      * "describe(SharedLibrary)" -- see SharedLibrary, --
        a shared library
      * "expression(SharedLibrary)" -- see SharedLibrary,
        -- a shared library
      * "net(SharedLibrary)" -- see SharedLibrary, -- a
        shared library
      * "texMath(SharedLibrary)" -- see SharedLibrary, --
        a shared library
      * "toExternalString(SharedLibrary)" -- see SharedLibrary,
        -- a shared library
      * "toString(SharedLibrary)" -- see SharedLibrary, --
        a shared library
      * size(ForeignType) -- size of a foreign
        type
      * "describe(ForeignObject)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "expression(double)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "expression(float)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "expression(ForeignObject)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "net(ForeignObject)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "texMath(ForeignObject)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "toExternalString(ForeignObject)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "toString(ForeignObject)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(charstar)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(charstarstar)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(double)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(float)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * value(ForeignObject) -- get the value
        of a foreign object as a Macaulay2 thing
      * "value(int8)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(int16)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(int32)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(int64)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(uint8)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(uint16)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(uint32)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(uint64)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(voidstar)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
      * "value(voidstarstar)" -- see value(ForeignObject),
        -- get the value of a foreign object as a
        Macaulay2 thing
  * Symbols
      * "Variadic" -- see foreignFunction, -- construct
        a foreign function
      * "Atomic" -- see getMemory, -- allocate memory using
        the garbage collector
  * Other things
      * nullPointer -- the null pointer

For the programmer
==================

The object ForeignFunctions, is a package (Macaulay2Doc).

Examples

Types

fast Fourier transform example -- fast Fourier transforms using foreign function calls to the FFTW library
**********************************************************************************************************

In this example, we make foreign function calls using the FFTW (see
https://www.fftw.org/ ) library to compute fast Fourier transforms for
polynomial multiplication.

Once FFTW is installed, there should be a file named libfftw3.so or
libfftw3.dylib available on the system in one of the standard shared library
directories.  We can then open the library using openSharedLibrary.

+----------------------------------------+
|i2 : libfftw = openSharedLibrary "fftw3"|
|                                        |
|o2 = fftw3                              |
|                                        |
|o2 : SharedLibrary                      |
+----------------------------------------+

Next, we create our foreign functions using the constructor method
foreignFunction.  We will need three: one to wrap
fftw_plan_dft_1d, which creates the plan for a fast Fourier transform
computation, one to wrap fftw_execute, which actually does the computation, and
one to wrap fftw_destroy_plan, which deallocates the memory allocated by
fftw_plan_dft_1d.

Let's walk through each of these.

According to the FFTW documentation, fftw_plan_dft_1d has the following
signature: fftw_plan fftw_plan_dft_1d(int n0, fftw_complex *in, fftw_complex
*out, int sign, unsigned flags). Our goal is to compute the discrete Fourier
transform $\mathscr F\{\mathbf a\}$ of a vector $\mathbf a\in\CC^n$.  In this
case, n0 will be $n$, in will be $\mathbf a$ represented as an array of $2n$
See double, objects (alternating between real and imaginary
parts), out will be an array ultimately containing $\mathscr F\{\mathbf a\}$,
sign will be 1 unless we want to compute the inverse discrete Fourier transform
$\mathscr F^{-1}\{\mathbf a\}$, in which case it will be $-1$.  Finally, flags
will contain planning flags for the computation.  When setting up our foreign
function objects, we won't worry about the structures of the fftw_plan or
fftw_complex types and will just use voidstar, to
indicate that they are pointers.

+---------------------------------------------------------------------------+
|i3 : fftwPlanDft1d = foreignFunction(libfftw, "fftw_plan_dft_1d", voidstar,|
|         {int, voidstar, voidstar, int, uint})                             |
|                                                                           |
|o3 = fftw3::fftw_plan_dft_1d                                               |
|                                                                           |
|o3 : ForeignFunction                                                       |
+---------------------------------------------------------------------------+

Next, we define foreign functions for fftw_execute, which has signature void
fftw_execute(const fftw_plan plan), and fftw_destroy_plan, which has signature
void fftw_destroy_plan(fftw_plan plan).

+-----------------------------------------------------------------------------+
|i4 : fftwExecute = foreignFunction(libfftw, "fftw_execute", void, voidstar)  |
|                                                                             |
|o4 = fftw3::fftw_execute                                                     |
|                                                                             |
|o4 : ForeignFunction                                                         |
+-----------------------------------------------------------------------------+
|i5 : fftwDestroyPlan = foreignFunction(libfftw, "fftw_destroy_plan", void,   |
|                                                                             |
|o5 = fftw3::fftw_destroy_plan                                                |
|                                                                             |
|o5 : ForeignFunction                                                         |
|-----------------------------------------------------------------------------|
|voidstar)                                                                    |
+-----------------------------------------------------------------------------+

Now we wrap these functions inside Macaulay2 functions.  Since computing
$\mathscr F\{\mathbf a\}$ and $\mathscr F^{-1}\{\mathbf a\}$ using FFTW
requires only changing the sign parameter of the call to fftw_plan_dft_1d, we
create a helper function that will do most of the work.

This helper function takes a list x representing the vector $\mathbf a$ as well
as the value of sign, allocates the memory required for the in and out lists
using getMemory, and then calls the foreign function
fftwPlanDft1d.  Note that we pass 64 as the value of flags.  This specifies the
FFTW_ESTIMATE planning flag, which uses a simple heuristic to quickly pick a
plan for the computation.  We then call
registerFinalizer(ForeignObject,Function),
to make sure that the
fftw_plan object that was returned is properly deallocated during garbage
collection.  Next, we set up the in array by finding the real and imaginary
parts of the elements of x and assigning them using * voidstar = Thing.
Finally, we call fftw_execute and convert the result
back to a list of complex numbers.

+-----------------------------------------------------------------------------+
|i6 : fftHelper = (x, sign) -> (                                              |
|         n := #x;                                                            |
|         inptr := getMemory(2 * n * size double);                            |
|         outptr := getMemory(2 * n * size double);                           |
|         p := fftwPlanDft1d(n, inptr, outptr, sign, 64);                     |
|         registerFinalizer(p, fftwDestroyPlan);                              |
|         dbls := splice apply(x, y -> (realPart numeric y, imaginaryPart     |
|         apply(2 * n, i -> *(value inptr + i * size double) = double dbls    |
|         fftwExecute p;                                                      |
|         r := ((2 * n) * double) outptr;                                     |
|         apply(n, i -> value r_(2 * i) + ii * value r_(2 * i + 1)));         |
|-----------------------------------------------------------------------------|
|numeric y));                                                                 |
|#i);                                                                         |
+-----------------------------------------------------------------------------+
|i7 : fastFourierTransform = method();                                        |
+-----------------------------------------------------------------------------+
|i8 : fastFourierTransform List := x -> fftHelper(x, -1);                     |
+-----------------------------------------------------------------------------+
|i9 : inverseFastFourierTransform = method();                                 |
+-----------------------------------------------------------------------------+
|i10 : inverseFastFourierTransform List := x -> fftHelper(x, 1);              |
+-----------------------------------------------------------------------------+

One application of fast Fourier transforms is log-linear time multiplication of
polynomials.  Indeed, if $f,g\in\CC[x]$ have degrees $m$ and $n$, respectively,
and if $\mathbf a,\mathbf b\in\CC^{m+n+1}$ are the vectors formed by taking
$a_i$ to be the coefficient of $x^i$ in $f$ and $b_i$ the coefficient of $x_i$
in $g$, then $\frac{1}{m+n+1}\mathscr F^{-1}\left\{\mathscr F\{\mathbf a\}\cdot
\mathscr F\{\mathbf b\}\right\}$, where $\mathscr F\{\mathbf a\}\cdot \mathscr
F\{\mathbf b\}$ is computed using component-wise multiplication, contains the
coefficients of the product $fg$.  In some cases, this process can be faster
than Macaulay2's native polynomial multiplication.

Let's look at a particular example.

+--------------------------------------------------------------+
|i11 : fftMultiply = (f, g) -> (                               |
|          m := first degree f;                                |
|          n := first degree g;                                |
|          a := fastFourierTransform splice append(            |
|              apply(m + 1, i -> coefficient(x^i, f)), n:0);   |
|          b := fastFourierTransform splice append(            |
|              apply(n + 1, i -> coefficient(x^i, g)), m:0);   |
|          c := inverseFastFourierTransform apply(a, b, times);|
|          sum(m + n + 1, i -> c#i * x^i)/(m + n + 1));        |
+--------------------------------------------------------------+
|i12 : R = CC[x];                                              |
+--------------------------------------------------------------+
|i13 : f = x - 1;                                              |
+--------------------------------------------------------------+
|i14 : g = x^2 + x + 1;                                        |
+--------------------------------------------------------------+
|i15 : fftMultiply(f, g)                                       |
|                                                              |
|       3                                                      |
|o15 = x  - 1                                                  |
|                                                              |
|o15 : R                                                       |
+--------------------------------------------------------------+

general linear model example -- constrained least squares using foreign function calls to the LAPACK library
************************************************************************************************************

In this example, we make foreign function calls to LAPACK (see
https://www.netlib.org/lapack/ ) to solve constrained least squares problems.
LAPACK is already used by Macaulay2 for a number of its linear algebra
computations, but some functions aren't available.

One of these is dggglm, which solves constrained least squares problems that
have applications to general Gauss-Markov linear models in statistics.  In
particular, suppose $A$ is an $n\times m$ real matrix, $B$ is an $n\times p$
real matrix, and $\mathbf d$ is a vector in $\RR^n$.  We would like to find the
vectors $\mathbf x\in\RR^m$ and $\mathbf y\in\RR^p$ that minimize $\|\mathbf
y\|$ subject to the constraint $\mathbf d = A\mathbf x + B\mathbf y$.

The dggglm function does exactly this.  Its signature is void dggglm_(int *n,
int *m, int *p, double *A, int *ldA, double *B, int *ldB, double *d, double *x,
double *y, double *work, int *lwork, int *info).  Note the trailing underscore
that was added by the Fortran compiler.  Each of the 13 arguments are pointers,
so we use voidstar, to represent them in our call to
foreignFunction.  Since Macaulay2 is already linked
against LAPACK, we don't need to worry about calling openSharedLibrary.

+-------------------------------------------------------------------+
|i1 : dggglm = foreignFunction("dggglm_", void, toList(13:voidstar))|
|                                                                   |
|o1 = dggglm_                                                       |
|                                                                   |
|o1 : ForeignFunction                                               |
+-------------------------------------------------------------------+

The parameters n, m and p are exactly the numbers $n$, $m$, and $p$ above.  The
parameters A, B, and d are arrays that will store the entries of $A$, $B$, and
$\mathbf d$.  LAPACK expects these to be in column-major order, in contrast to
the row-major order used by Macaulay2.  So we add helper methods to take care
of this conversion.  The local variable T is a ForeignArrayType,
created by ZZ * ForeignType.

+--------------------------------------------------+
|i2 : toLAPACK = method();                         |
+--------------------------------------------------+
|i3 : toLAPACK Matrix := A -> (                    |
|         T := (numRows A * numColumns A) * double;|
|         T flatten entries transpose A);          |
+--------------------------------------------------+
|i4 : toLAPACK Vector := toLAPACK @@ matrix;       |
+--------------------------------------------------+

The parameters ldA and ldB are the "leading dimensions" of the arrays A and B.
We will use $n$ for both.  The arrays x and y will store the solutions.  The
array work has dimension lwork (for which we will use $n + m + p$) that the
procedure will use as a workspace.  Finally, info stores the return value (0 on
success).

The following method prepares matrices $A$ and $B$ and a vector $\mathbf d$ to
be sent to the foreign function we created above, and then converts the
solutions into a sequence two of Macaulay2 vectors.  Note that we use
getMemory, to allocate memory for x, y, and info (which we name i
here to avoid conflicting with info (Macaulay2Doc)) and
address, to get pointers to the other integer arguments.  We also use
ForeignType * voidstar, to dereference i and
determine whether the call was successful.

+-----------------------------------------------------------------------------+
|i5 : generalLinearModel= method();                                           |
+-----------------------------------------------------------------------------+
|i6 : generalLinearModel(Matrix, Matrix, Vector) := (A, B, d) -> (            |
|         if numRows A != numRows B                                           |
|         then error "expected first two arguments to have the same number of |
|         n := numRows A;                                                     |
|         m := numColumns A;                                                  |
|         p := numColumns B;                                                  |
|         x := getMemory(m * size double);                                    |
|         y := getMemory(p * size double);                                    |
|         lwork := n + m + p;                                                 |
|         work := getMemory(lwork * size double);                             |
|         i := getMemory int;                                                 |
|         dggglm(address int n, address int m, address int p, toLAPACK A,     |
|             address int n, toLAPACK B, address int n, toLAPACK d, x, y, work|
|             address int lwork, i);                                          |
|         if value(int * i) != 0 then error("call to dggglm failed");         |
|         (vector value (m * double) x, vector value (p * double) y));        |
|-----------------------------------------------------------------------------|
|rows";                                                                       |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|,                                                                            |
+-----------------------------------------------------------------------------+

Finally, let's call this method and solve a constrained least squares problem.
This example is from Kourouklis, S., & Paige, "A Constrained Least Squares
Approach to the General Gauss-Markov Linear Model" (see
https://doi.org/10.1080/01621459.1981.10477694 ).

+-----------------------------------------------------------------------------+
|i7 : A = matrix {{1, 2, 3}, {4, 1, 2}, {5, 6, 7}, {3, 4, 6}};                |
|                                                                             |
|              4       3                                                      |
|o7 : Matrix ZZ  <-- ZZ                                                       |
+-----------------------------------------------------------------------------+
|i8 : B = matrix {{1, 0, 0, 0}, {2, 3, 0, 0}, {4, 5, 1e-5, 0}, {7, 8, 9, 10}};|
|                                                                             |
|                4         4                                                  |
|o8 : Matrix RR    <-- RR                                                     |
|              53        53                                                   |
+-----------------------------------------------------------------------------+
|i9 : d = vector {1, 2, 3, 4};                                                |
|                                                                             |
|       4                                                                     |
|o9 : ZZ                                                                      |
+-----------------------------------------------------------------------------+
|i10 : generalLinearModel(A, B, d)                                            |
|                                                                             |
|o10 = (|   .3141  |, | .0296627 |)                                           |
|       | -.334417 |  | .0451036 |                                            |
|       |  .441691 |  | .0585128 |                                            |
|                     | .0650142 |                                            |
|                                                                             |
|o10 : Sequence                                                               |
+-----------------------------------------------------------------------------+

just-in-time compilation example -- using foreign function calls for computing Fibonacci numbers using JIT
**********************************************************************************************************

Macaulay2's language is interpreted, which means that in general programs will
run more slowly than programs written in a compiled language like C. If the
speed of a compiled language is desirable, then one option is just-in-time
compilation (see https://en.wikipedia.org/wiki/just-in-time_compilation )
(JIT), where we compile some code at runtime.

As an example, let's suppose that we would like to compute Fibonacci numbers
using the recursive definition, i.e., for all nonnegative $n\in\ZZ$, $F_n = n$
if $n < 2$ and $F_n = F_{n-2} + F_{n-1}$ otherwise. As an algorithm, this is
horribly inefficient and has exponential running time, but it will be useful to
illustrate our point.

We will write two functions.  One will be a straight Macaulay2 implementation:

+-----------------------------------------------------------------------------+
|i2 : fibonacci1 = n -> if n < 2 then n else fibonacci1(n - 1) + fibonacci1(n |
|-----------------------------------------------------------------------------|
|- 2);                                                                        |
+-----------------------------------------------------------------------------+

The next will be a function that creates a C source file, compiles it into a
shared library using GCC (see https://gcc.gnu.org/ ), opens that library using
openSharedLibrary, calls foreignFunction,
to create a foreign function, calls that foreign function, and
then converts the output back into a Macaulay2 integer using
value(ForeignObject).

+----------------------------------------------------------------------------+
|i3 : fibonacci2 = n -> (                                                    |
|         dir := temporaryFileName();                                        |
|         makeDirectory dir;                                                 |
|         dir | "/libfib.c" << ///int fibonacci2(int n)                      |
|     {                                                                      |
|         if (n < 2)                                                         |
|             return n;                                                      |
|         else                                                               |
|             return fibonacci2(n - 1) + fibonacci2(n - 2);                  |
|     }                                                                      |
|     /// << close;                                                          |
|         run("gcc -c -fPIC " | dir | "/libfib.c -o " | dir | "/libfib.o");  |
|         run("gcc -shared " | dir | "/libfib.o -o " | dir | "/libfib.so");  |
|         lib := openSharedLibrary("libfib", FileName => dir | "/libfib.so");|
|         f = foreignFunction(lib, "fibonacci2", int, int);                  |
|         value f n);                                                        |
+----------------------------------------------------------------------------+

Now let's run both functions to compare the results.

+-------------------------------------+
|i4 : peek elapsedTiming fibonacci1 35|
|                                     |
|o4 = Time{10.0202, 9227465}          |
+-------------------------------------+
|i5 : peek elapsedTiming fibonacci2 35|
|                                     |
|o5 = Time{.0958821, 9227465}         |
+-------------------------------------+

As we can see, despite the additional overhead of creating a shared library and
making a foreign function call, the function that used JIT was significantly
faster.

foreignFunction -- construct a foreign function
***********************************************

Synopsis
========

  * Usage:
        foreignFunction(lib, symb, rtype, argtypes)
        foreignFunction(symb, rtype, argtypes)
  * Inputs:
      * lib, a shared library, containing the function;
      * symb, a string (Macaulay2Doc), the symbol of the
        function;
      * rtype, a foreign type, the return type;
      * argtypes, a list (Macaulay2Doc), the types of the
        arguments;
  * Optional inputs (Macaulay2Doc),:
      * Variadic => a Boolean value (Macaulay2Doc), default
        value false, whether the function is variadic;
  * Outputs:
      * a foreign function,

Description
===========

Load a function contained in a shared library using the C function dlsym and
declare its signature. The library may be omitted if it is already loaded,
e.g., for functions in the C standard library or libraries that Macaulay2 is
already linked against.

+---------------------------------------------------+
|i1 : mycos = foreignFunction("cos", double, double)|
|                                                   |
|o1 = cos                                           |
|                                                   |
|o1 : ForeignFunction                               |
+---------------------------------------------------+
|i2 : mycos pi                                      |
|                                                   |
|o2 = -1                                            |
|                                                   |
|o2 : ForeignObject of type double                  |
+---------------------------------------------------+

If a function takes multiple arguments, then provide these argument types using
a list.

+-----------------------------------------------------------------+
|i3 : myatan2 = foreignFunction("atan2", double, {double, double})|
|                                                                 |
|o3 = atan2                                                       |
|                                                                 |
|o3 : ForeignFunction                                             |
+-----------------------------------------------------------------+
|i4 : myatan2(1, sqrt 3)                                          |
|                                                                 |
|o4 = .5235987755982989                                           |
|                                                                 |
|o4 : ForeignObject of type double                                |
+-----------------------------------------------------------------+

For variadic functions, set the Variadic option to true.

+---------------------------------------------------------------------+
|i5 : sprintf = foreignFunction("sprintf", void, {charstar, charstar},|
|         Variadic => true)                                           |
|                                                                     |
|o5 = sprintf                                                         |
|                                                                     |
|o5 : ForeignFunction                                                 |
+---------------------------------------------------------------------+
|i6 : buf = charstar "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  |
|                                                                     |
|o6 = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx                   |
|                                                                     |
|o6 : ForeignObject of type char*                                     |
+---------------------------------------------------------------------+
|i7 : sprintf(buf, "%s %d", "foo", 3)                                 |
+---------------------------------------------------------------------+
|i8 : buf                                                             |
|                                                                     |
|o8 = foo 3                                                           |
|                                                                     |
|o8 : ForeignObject of type char*                                     |
+---------------------------------------------------------------------+

The variadic arguments are processed using foreignObject,
which may lead to unexpected behavior.  It may be useful to cast them to
foreign objects to avoid ambiguity.

+----------------------------------------------+
|i9 : sprintf(buf, "%s %.1f", "foo", 3)        |
+----------------------------------------------+
|i10 : buf                                     |
|                                              |
|o10 = foo 0.0                                 |
|                                              |
|o10 : ForeignObject of type char*             |
+----------------------------------------------+
|i11 : sprintf(buf, "%s %.1f", "foo", double 3)|
+----------------------------------------------+
|i12 : buf                                     |
|                                              |
|o12 = foo 3.0                                 |
|                                              |
|o12 : ForeignObject of type char*             |
+----------------------------------------------+

Note that variadic functions cannot be passed arguments that have a size of
fewer than 4 bytes.

+------------------------------------------+
|i13 : stopIfError = false                 |
|                                          |
|o13 = false                               |
+------------------------------------------+
|i14 : sprintf(buf, "%c", char' 77)        |
|stdio:15:7:(3): error: libffi: bad argtype|
+------------------------------------------+

If the foreign function allocates any memory, then register a finalizer for its
outputs to deallocate the memory during garbage collection using
registerFinalizer(ForeignObject,Function).

+---------------------------------------------------------+
|i15 : malloc = foreignFunction("malloc", voidstar, ulong)|
|                                                         |
|o15 = malloc                                             |
|                                                         |
|o15 : ForeignFunction                                    |
+---------------------------------------------------------+
|i16 : free = foreignFunction("free", void, voidstar)     |
|                                                         |
|o16 = free                                               |
|                                                         |
|o16 : ForeignFunction                                    |
+---------------------------------------------------------+
|i17 : x = malloc 8                                       |
|                                                         |
|o17 = 0x770eb406a280                                     |
|                                                         |
|o17 : ForeignObject of type void*                        |
+---------------------------------------------------------+
|i18 : registerFinalizer(x, free)                         |
+---------------------------------------------------------+

Ways to use foreignFunction:
============================

  * "foreignFunction(Pointer,String,ForeignType,VisibleList)"
  * "foreignFunction(SharedLibrary,String,ForeignType,ForeignType)"
  * "foreignFunction(SharedLibrary,String,ForeignType,VisibleList)"
  * "foreignFunction(String,ForeignType,ForeignType)"
  * "foreignFunction(String,ForeignType,VisibleList)"

For the programmer
==================

The object foreignFunction, is a method function with options (Macaulay2Doc).

SharedLibrary -- a shared library
*********************************

Description
===========

A shared library that could be used to load foreign functions.  Each shared
library object consists of a pointer to a handle for the library and a string
that is used by describe (Macaulay2Doc), expression (Macaulay2Doc),
see net (Macaulay2Doc), texMath (Macaulay2Doc),
see toExternalString (Macaulay2Doc),
and toString (Macaulay2Doc).

+----------------------------------------+
|i1 : mpfr = openSharedLibrary "mpfr"    |
|                                        |
|o1 = mpfr                               |
|                                        |
|o1 : SharedLibrary                      |
+----------------------------------------+
|i2 : peek mpfr                          |
|                                        |
|o2 = SharedLibrary{0x7698a8d6b550, mpfr}|
+----------------------------------------+

Functions and methods returning a shared library:
=================================================

  * openSharedLibrary -- open a shared library

Methods that use a shared library:
==================================

  * "foreignFunction(SharedLibrary,String,ForeignType,ForeignType)" -- see
    foreignFunction, -- construct a foreign function
  * "foreignFunction(SharedLibrary,String,ForeignType,VisibleList)" -- see
    foreignFunction, -- construct a foreign function
  * "foreignSymbol(SharedLibrary,String,ForeignType)" -- see
    foreignSymbol, -- get a foreign symbol
  * "describe(SharedLibrary)"
  * "expression(SharedLibrary)"
  * "net(SharedLibrary)"
  * "texMath(SharedLibrary)"
  * "toExternalString(SharedLibrary)"
  * "toString(SharedLibrary)"

For the programmer
==================

The object SharedLibrary, is a self initializing type (Macaulay2Doc),
with ancestor classes
BasicList (Macaulay2Doc), < Thing (Macaulay2Doc).

openSharedLibrary -- open a shared library
******************************************

Synopsis
========

  * Usage:
        openSharedLibrary name
  * Inputs:
      * name, a string (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * FileName => a string (Macaulay2Doc), default value null,
        the filename of the library to open;
  * Outputs:
      * a shared library,

Description
===========

Open a shared library with the given name.  In particular, this is a wrapper
around the C dlopen function.  A library is searched for with the filename
"lib" | name | ".so" (in Linux) or "lib" | name | ".dylib" (in macOS).
Alternatively, a specific filename can be specified using the FileName option.
A corresponding SharedLibrary, object, which can be later
used by foreignFunction, is returned.

+-----------------------------+
|i1 : openSharedLibrary "mpfr"|
|                             |
|o1 = mpfr                    |
|                             |
|o1 : SharedLibrary           |
+-----------------------------+

Ways to use openSharedLibrary:
==============================

  * "openSharedLibrary(String)"

For the programmer
==================

The object openSharedLibrary, is a method function with options (Macaulay2Doc).

ForeignType -- abstract foreign type
************************************

Description
===========

This is the abstract class from which all other foreign type classes should
inherit.  All ForeignType objects should have, at minimum, two key-value pairs:

  * Name, a string (Macaulay2Doc), a human-readable name of the
    class for display purposes, used by net(ForeignType).
  * Address, a pointer, a pointer to the corresponding ffi_type
    object, used by address(ForeignType).

Types of foreign type:
======================

  * ForeignArrayType -- foreign array type
  * ForeignIntegerType -- foreign integer type
  * ForeignPointerArrayType -- foreign type for
    NULL-terminated arrays of pointers
  * ForeignPointerType -- foreign pointer type
  * ForeignRealType -- foreign real type
  * ForeignStringType -- foreign string type
  * ForeignStructType -- foreign struct type
  * ForeignUnionType -- foreign union type
  * ForeignVoidType -- foreign void type

Methods that use a foreign type:
================================

  * "address(ForeignType)" -- see address, -- pointer to type or
    object
  * "foreignArrayType(ForeignType,ZZ)" -- see foreignArrayType,
    -- construct a foreign array type
  * "foreignArrayType(String,ForeignType,ZZ)" -- see foreignArrayType,
    -- construct a foreign array type
  * "ForeignType * ZZ" -- see foreignArrayType, --
    construct a foreign array type
  * "ZZ * ForeignType" -- see foreignArrayType, --
    construct a foreign array type
  * "foreignFunction(Pointer,String,ForeignType,VisibleList)" -- see
    foreignFunction, -- construct a foreign function
  * "foreignFunction(SharedLibrary,String,ForeignType,ForeignType)" -- see
    foreignFunction, -- construct a foreign function
  * "foreignFunction(SharedLibrary,String,ForeignType,VisibleList)" -- see
    foreignFunction, -- construct a foreign function
  * "foreignFunction(String,ForeignType,ForeignType)" -- see
    foreignFunction, -- construct a foreign function
  * "foreignFunction(String,ForeignType,VisibleList)" -- see
    foreignFunction, -- construct a foreign function
  * "foreignPointerArrayType(ForeignType)" -- see
    foreignPointerArrayType, -- construct a foreign
    pointer array type
  * "foreignPointerArrayType(String,ForeignType)" -- see
    foreignPointerArrayType, -- construct a foreign
    pointer array type
  * "foreignSymbol(SharedLibrary,String,ForeignType)" -- see
    foreignSymbol, -- get a foreign symbol
  * "foreignSymbol(String,ForeignType)" -- see foreignSymbol,
    -- get a foreign symbol
  * "net(ForeignType)"
  * ForeignType * voidstar -- dereference a
    voidstar object
  * ForeignType ForeignObject -- cast a
    foreign object to the given foreign type
  * ForeignType Pointer -- dereference a pointer
  * "getMemory(ForeignType)" -- see getMemory, -- allocate
    memory using the garbage collector
  * new ForeignType (missing documentation)
  * size(ForeignType) -- size of a foreign type

For the programmer
==================

The object ForeignType, is a type (Macaulay2Doc),
with ancestor classes Type (Macaulay2Doc), <
MutableHashTable (Macaulay2Doc) < HashTable (Macaulay2Doc)
< Thing (Macaulay2Doc).

Subtypes

size(ForeignType) -- size of a foreign type
*******************************************

Synopsis
========

  * Function: size (Macaulay2Doc),
  * Usage:
        size T
  * Inputs:
      * T, a foreign type,
  * Outputs:
      * an integer (Macaulay2Doc),

Description
===========

Return the number of bytes needed by the given foreign type, just like the
sizeof operator in C.

+------------------+
|i1 : size char'   |
|                  |
|o1 = 1            |
+------------------+
|i2 : size voidstar|
|                  |
|o2 = 8            |
+------------------+

Ways to use this method:
========================

  * size(ForeignType) -- size of a foreign type

ForeignArrayType -- foreign array type
**************************************

Description
===========

This is the class for array types.  There are no built-in types.  They must be
constructed using foreignArrayType.

+-----------------------------------+
|i1 : x = (3 * int) {3, 5, 7}       |
|                                   |
|o1 = {3, 5, 7}                     |
|                                   |
|o1 : ForeignObject of type int32[3]|
+-----------------------------------+

Foreign arrays may be subscripted using _ (Macaulay2Doc).

+--------------------------------+
|i2 : x_1                        |
|                                |
|o2 = 5                          |
|                                |
|o2 : ForeignObject of type int32|
+--------------------------------+
|i3 : x_(-1)                     |
|                                |
|o3 = 7                          |
|                                |
|o3 : ForeignObject of type int32|
+--------------------------------+

Their lengths may be found using length (Macaulay2Doc).

+-------------+
|i4 : length x|
|             |
|o4 = 3       |
+-------------+

They are also iterable (Macaulay2Doc).

+--------------------------------+
|i5 : i = iterator x;            |
+--------------------------------+
|i6 : next i                     |
|                                |
|o6 = 3                          |
|                                |
|o6 : ForeignObject of type int32|
+--------------------------------+
|i7 : next i                     |
|                                |
|o7 = 5                          |
|                                |
|o7 : ForeignObject of type int32|
+--------------------------------+
|i8 : for y in x list value y + 1|
|                                |
|o8 = {4, 6, 8}                  |
|                                |
|o8 : List                       |
+--------------------------------+

They may also be modified using subscripted assignment.

+------------------------------------+
|i9 : x_0 = 9                        |
|                                    |
|o9 = 9                              |
|                                    |
|o9 : ForeignObject of type int32    |
+------------------------------------+
|i10 : x                             |
|                                    |
|o10 = {9, 5, 7}                     |
|                                    |
|o10 : ForeignObject of type int32[3]|
+------------------------------------+

Functions and methods returning a foreign array type:
=====================================================

  * foreignArrayType -- construct a foreign array type

Methods that use a foreign array type:
======================================

  * ForeignArrayType VisibleList -- cast a
    Macaulay2 list to a foreign array

For the programmer
==================

The object ForeignArrayType, is a type (Macaulay2Doc),
with ancestor classes ForeignType, <
Type (Macaulay2Doc) < MutableHashTable (Macaulay2Doc)
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

foreignArrayType -- construct a foreign array type
**************************************************

Synopsis
========

  * Usage:
        foreignArrayType(name, T, n)
        foreignArrayType(T, n)
        n * T
  * Inputs:
      * name, a string (Macaulay2Doc),
      * T, a foreign type,
      * n, an integer (Macaulay2Doc),
  * Outputs:
      * a foreign array type,

Description
===========

To construct a foreign array type, specify a name, the type of the elements of
each array, and the number of elements in each array.

+--------------------------------------------+
|i1 : foreignArrayType("myArrayType", int, 5)|
|                                            |
|o1 = myArrayType                            |
|                                            |
|o1 : ForeignArrayType                       |
+--------------------------------------------+

If the name is omitted, then a default one is chosen by taking the name of the
type of the elements and appending the number of elements enclosed in brackets.

+-----------------------------+
|i2 : foreignArrayType(int, 5)|
|                             |
|o2 = int32[5]                |
|                             |
|o2 : ForeignArrayType        |
+-----------------------------+

Alternatively, you may "multiply" the number of elements by the type to
accomplish the same.

+---------------------+
|i3 : 5 * int         |
|                     |
|o3 = int32[5]        |
|                     |
|o3 : ForeignArrayType|
+---------------------+

Ways to use foreignArrayType:
=============================

  * "foreignArrayType(ForeignType,ZZ)"
  * "foreignArrayType(String,ForeignType,ZZ)"

For the programmer
==================

The object foreignArrayType, is a method function (Macaulay2Doc).

ForeignArrayType VisibleList -- cast a Macaulay2 list to a foreign array
************************************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        T x
  * Inputs:
      * T, a foreign array type,
      * x, a visible list (Macaulay2Doc),
  * Outputs:
      * a foreign object, of type T;

Description
===========

To cast a Macaulay2 list to a foreign object with array type, give the type
followed by the list.

+-----------------------------------+
|i1 : intarray5 = 5 * int           |
|                                   |
|o1 = int32[5]                      |
|                                   |
|o1 : ForeignArrayType              |
+-----------------------------------+
|i2 : x = intarray5 {2, 4, 6, 8, 10}|
|                                   |
|o2 = {2, 4, 6, 8, 10}              |
|                                   |
|o2 : ForeignObject of type int32[5]|
+-----------------------------------+

Caveat
======

The number of elements of x must match the number of elements that were
specified when T was constructed.

Ways to use this method:
========================

  * ForeignArrayType VisibleList -- cast a
    Macaulay2 list to a foreign array

ForeignIntegerType -- foreign integer type
******************************************

Description
===========

This is the class of the various C integer types.  There are built-in types for
signed and unsigned integers of 8, 16, 32, and 64 bits.  Signed types begin
with int and unsigned types with uint, and the number of bits is indicated by a
numeric suffix.

+-----------------------+
|i1 : int8              |
|                       |
|o1 = int8              |
|                       |
|o1 : ForeignIntegerType|
+-----------------------+
|i2 : uint32            |
|                       |
|o2 = uint32            |
|                       |
|o2 : ForeignIntegerType|
+-----------------------+

There are also a number of aliases to these types without the numeric suffixes.
Note the single quote on char' to avoid conflicting with char (Macaulay2Doc).
Also note that the number of bits for long and ulong is
system-dependent (32 on 32-bit systems and 64 on 64-bit systems).

+------------------------+
|i3 : char'              |
|                        |
|o3 = int8               |
|                        |
|o3 : ForeignIntegerType |
+------------------------+
|i4 : uchar              |
|                        |
|o4 = uint8              |
|                        |
|o4 : ForeignIntegerType |
+------------------------+
|i5 : short              |
|                        |
|o5 = int16              |
|                        |
|o5 : ForeignIntegerType |
+------------------------+
|i6 : ushort             |
|                        |
|o6 = uint16             |
|                        |
|o6 : ForeignIntegerType |
+------------------------+
|i7 : int                |
|                        |
|o7 = int32              |
|                        |
|o7 : ForeignIntegerType |
+------------------------+
|i8 : uint               |
|                        |
|o8 = uint32             |
|                        |
|o8 : ForeignIntegerType |
+------------------------+
|i9 : long               |
|                        |
|o9 = int64              |
|                        |
|o9 : ForeignIntegerType |
+------------------------+
|i10 : ulong             |
|                        |
|o10 = uint64            |
|                        |
|o10 : ForeignIntegerType|
+------------------------+

See also
========

  * mpzT -- GMP arbitrary-precision integer type

Methods that use a foreign integer type:
========================================

  * ForeignIntegerType Number -- cast a
    Macaulay2 number to a foreign integer object

Protected objects of class ForeignIntegerType:
==============================================

  * "int8"
  * "int16"
  * "int32"
  * "int64"
  * "uint8"
  * "uint16"
  * "uint32"
  * "uint64"
  * mpzT -- GMP arbitrary-precision integer type

For the programmer
==================

The object ForeignIntegerType, is a type (Macaulay2Doc),
with ancestor classes ForeignType, <
Type (Macaulay2Doc) < MutableHashTable (Macaulay2Doc)
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

mpzT -- GMP arbitrary-precision integer type
********************************************

Description
===========

Macaulay2's native ZZ (Macaulay2Doc), integer type wraps around mpz_t
from GMP (see https://gmplib.org/ ).  This type (which is an instance of
ForeignIntegerType) allows for conversion between
Macaulay2 integers and GMP integers without loss of precision.

+---------------------------------------------------------------------+
|i1 : mpzT 2^100                                                      |
|                                                                     |
|o1 = 1267650600228229401496703205376                                 |
|                                                                     |
|o1 : ForeignObject of type mpz_t                                     |
+---------------------------------------------------------------------+
|i2 : value oo                                                        |
|                                                                     |
|o2 = 1267650600228229401496703205376                                 |
+---------------------------------------------------------------------+
|i3 : mpzAdd = foreignFunction("__gmpz_add", void, {mpzT, mpzT, mpzT})|
|                                                                     |
|o3 = __gmpz_add                                                      |
|                                                                     |
|o3 : ForeignFunction                                                 |
+---------------------------------------------------------------------+
|i4 : x = mpzT 0                                                      |
|                                                                     |
|o4 = 0                                                               |
|                                                                     |
|o4 : ForeignObject of type mpz_t                                     |
+---------------------------------------------------------------------+
|i5 : mpzAdd(x, 2, 3)                                                 |
+---------------------------------------------------------------------+
|i6 : x                                                               |
|                                                                     |
|o6 = 5                                                               |
|                                                                     |
|o6 : ForeignObject of type mpz_t                                     |
+---------------------------------------------------------------------+

Methods that use an object of class mpzT:
=========================================

  * "new mpzT from ZZ"
  * "value(mpzT)"

For the programmer
==================

The object mpzT, is a foreign integer type,
with ancestor classes ForeignObject,
< HashTable (Macaulay2Doc) < Thing (Macaulay2Doc).

ForeignIntegerType Number -- cast a Macaulay2 number to a foreign integer object
********************************************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        T n
  * Inputs:
      * T, a foreign integer type,
      * n, a number (Macaulay2Doc),
  * Outputs:
      * a foreign object,

Description
===========

To cast a Macaulay2 number to a foreign object with an integer type, give the
type followed by the number.  Non-integers will be truncated.

+---------------------------------+
|i1 : int 12                      |
|                                 |
|o1 = 12                          |
|                                 |
|o1 : ForeignObject of type int32 |
+---------------------------------+
|i2 : ulong pi                    |
|                                 |
|o2 = 3                           |
|                                 |
|o2 : ForeignObject of type uint64|
+---------------------------------+
|i3 : short(-2.71828)             |
|                                 |
|o3 = -2                          |
|                                 |
|o3 : ForeignObject of type int16 |
+---------------------------------+

Ways to use this method:
========================

  * ForeignIntegerType Number -- cast a
    Macaulay2 number to a foreign integer object

ForeignPointerType -- foreign pointer type
******************************************

Description
===========

This is the class for C pointer types.  There is one built-in type, voidstar.

+-----------------------+
|i1 : voidstar          |
|                       |
|o1 = void*             |
|                       |
|o1 : ForeignPointerType|
+-----------------------+

Methods that use a foreign pointer type:
========================================

  * ForeignPointerType Pointer -- cast a
    Macaulay2 pointer to a foreign pointer

Protected objects of class ForeignPointerType:
==============================================

  * "voidstar"

For the programmer
==================

The object ForeignPointerType, is a type (Macaulay2Doc),
with ancestor classes ForeignType, <
Type (Macaulay2Doc) < MutableHashTable (Macaulay2Doc)
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

ForeignPointerType Pointer -- cast a Macaulay2 pointer to a foreign pointer
***************************************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        T x
  * Inputs:
      * T, a foreign pointer type,
      * x, a pointer,
  * Outputs:
      * a foreign object,

Description
===========

To cast a Macaulay2 pointer to a foreign object with a pointer type, give the
type followed by the pointer.

+--------------------------------+
|i1 : ptr = address int 0        |
|                                |
|o1 = 0x7b51b2cdac00             |
|                                |
|o1 : Pointer                    |
+--------------------------------+
|i2 : voidstar ptr               |
|                                |
|o2 = 0x7b51b2cdac00             |
|                                |
|o2 : ForeignObject of type void*|
+--------------------------------+

Ways to use this method:
========================

  * ForeignPointerType Pointer -- cast a
    Macaulay2 pointer to a foreign pointer

* voidstar = Thing -- assign value to object at address
*******************************************************

Synopsis
========

  * Operator: * (Macaulay2Doc),
  * Usage:
        *ptr = val
  * Inputs:
      * ptr, an instance of the type voidstar, or a
        pointer,
      * val, a thing (Macaulay2Doc),

Description
===========

Assign the value val to an object at the address given by ptr.

+--------------------------------+
|i1 : x = int 5                  |
|                                |
|o1 = 5                          |
|                                |
|o1 : ForeignObject of type int32|
+--------------------------------+
|i2 : ptr = address x            |
|                                |
|o2 = 0x794e7ad7a050             |
|                                |
|o2 : Pointer                    |
+--------------------------------+
|i3 : *ptr = int 6               |
|                                |
|o3 = 6                          |
|                                |
|o3 : ForeignObject of type int32|
+--------------------------------+
|i4 : x                          |
|                                |
|o4 = 6                          |
|                                |
|o4 : ForeignObject of type int32|
+--------------------------------+

If val is not a ForeignObject, then foreignObject,
is called first.

+--------------------------------+
|i5 : *ptr = 7                   |
|                                |
|o5 = 7                          |
|                                |
|o5 : ForeignObject of type int32|
+--------------------------------+
|i6 : x                          |
|                                |
|o6 = 7                          |
|                                |
|o6 : ForeignObject of type int32|
+--------------------------------+

Make sure that the memory at which ptr points is properly allocated.
Otherwise, segmentation faults may occur!

Ways to use this method:
========================

  * "* Pointer = Thing"
  * * voidstar = Thing -- assign value to object
    at address

ForeignType * voidstar -- dereference a voidstar object
*******************************************************

Synopsis
========

  * Operator: * (Macaulay2Doc),
  * Usage:
        T * ptr
  * Inputs:
      * T, a foreign type,
      * ptr, an instance of the type voidstar,
  * Outputs:
      * a foreign object, of type T;

Description
===========

This is syntactic sugar for T value ptr (see ForeignType Pointer)
for dereferencing pointers.

+---------------------------------+
|i1 : ptr = voidstar address int 5|
|                                 |
|o1 = 0x75762417a030              |
|                                 |
|o1 : ForeignObject of type void* |
+---------------------------------+
|i2 : int * ptr                   |
|                                 |
|o2 = 5                           |
|                                 |
|o2 : ForeignObject of type int32 |
+---------------------------------+

Ways to use this method:
========================

  * ForeignType * voidstar -- dereference a
    voidstar object

getMemory -- allocate memory using the garbage collector
********************************************************

Synopsis
========

  * Usage:
        getMemory n
        getMemory T
  * Inputs:
      * n, an integer (Macaulay2Doc), must be positive;
      * T, a foreign type,
  * Optional inputs (Macaulay2Doc),:
      * Atomic => ..., default value false
  * Outputs:
      * an instance of the type voidstar,

Description
===========

Allocate n bytes of memory using the GC garbage collector (Macaulay2Doc).

+--------------------------------+
|i1 : ptr = getMemory 8          |
|                                |
|o1 = 0x7917b519b9a0             |
|                                |
|o1 : ForeignObject of type void*|
+--------------------------------+

If the memory will not contain any pointers, then set the Atomic option to
true (Macaulay2Doc).

+---------------------------------------+
|i2 : ptr = getMemory(8, Atomic => true)|
|                                       |
|o2 = 0x7917bd8dab00                    |
|                                       |
|o2 : ForeignObject of type void*       |
+---------------------------------------+

Alternatively, a foreign object type T may be specified.  In this case, the
number of bytes and whether the Atomic option should be set will be determined
automatically.

+--------------------------------+
|i3 : ptr = getMemory int        |
|                                |
|o3 = 0x7917bd8daa00             |
|                                |
|o3 : ForeignObject of type void*|
+--------------------------------+

See also
========

  * registerFinalizer(ForeignObject,Function)
    -- register a finalizer
    for a foreign object

Ways to use getMemory:
======================

  * "getMemory(ForeignType)"
  * "getMemory(ForeignVoidType)"
  * "getMemory(ZZ)"

For the programmer
==================

The object getMemory, is a method function with options (Macaulay2Doc).

ForeignPointerArrayType -- foreign type for NULL-terminated arrays of pointers
******************************************************************************

Description
===========

This is the class for a particular kind of array type, where the entries of
each array are some sort of pointer type and the lengths are arbitrary. There
are two built-in types, charstarstar (for arrays of strings) and voidstarstar
(for arrays of pointers), but more types may be constructed using
foreignPointerArrayType.

+--------------------------------------------------------------------------+
|i1 : charstarstar {"foo", "bar", "baz"}                                   |
|                                                                          |
|o1 = {foo, bar, baz}                                                      |
|                                                                          |
|o1 : ForeignObject of type char**                                         |
+--------------------------------------------------------------------------+
|i2 : charstarstar {"the", "quick", "brown", "fox", "jumps", "over", "the",|
|         "lazy", "dog"}                                                   |
|                                                                          |
|o2 = {the, quick, brown, fox, jumps, over, the, lazy, dog}                |
|                                                                          |
|o2 : ForeignObject of type char**                                         |
+--------------------------------------------------------------------------+
|i3 : voidstarstar {address int 0, address int 1, address int 2}           |
|                                                                          |
|o3 = {0x76382a4fde80, 0x76382a4fde70, 0x76382a4fde50}                     |
|                                                                          |
|o3 : ForeignObject of type void**                                         |
+--------------------------------------------------------------------------+

Foreign pointer arrays may be subscripted using _ (Macaulay2Doc).

+-------------------------------------------+
|i4 : x = charstarstar {"foo", "bar", "baz"}|
|                                           |
|o4 = {foo, bar, baz}                       |
|                                           |
|o4 : ForeignObject of type char**          |
+-------------------------------------------+
|i5 : x_1                                   |
|                                           |
|o5 = bar                                   |
|                                           |
|o5 : ForeignObject of type char*           |
+-------------------------------------------+
|i6 : x_(-1)                                |
|                                           |
|o6 = baz                                   |
|                                           |
|o6 : ForeignObject of type char*           |
+-------------------------------------------+

Their lengths may be found using length (Macaulay2Doc).

+-------------+
|i7 : length x|
|             |
|o7 = 3       |
+-------------+

They are also iterable (Macaulay2Doc).

+---------------------------------+
|i8 : i = iterator x;             |
+---------------------------------+
|i9 : next i                      |
|                                 |
|o9 = foo                         |
|                                 |
|o9 : ForeignObject of type char* |
+---------------------------------+
|i10 : next i                     |
|                                 |
|o10 = bar                        |
|                                 |
|o10 : ForeignObject of type char*|
+---------------------------------+
|i11 : scan(x, print)             |
|foo                              |
|bar                              |
|baz                              |
+---------------------------------+

They may also be modified using subscripted assignment.

+----------------------------------+
|i12 : x_0 = "qux"                 |
|                                  |
|o12 = qux                         |
|                                  |
|o12 : ForeignObject of type char* |
+----------------------------------+
|i13 : x                           |
|                                  |
|o13 = {qux, bar, baz}             |
|                                  |
|o13 : ForeignObject of type char**|
+----------------------------------+

Functions and methods returning a foreign array type:
=====================================================

  * foreignPointerArrayType -- construct a
    foreign pointer array type

Methods that use a foreign array type:
======================================

  * ForeignPointerArrayType VisibleList
    -- cast a Macaulay2 list to a foreign pointer array

Protected objects of class ForeignPointerArrayType:
===================================================

  * "charstarstar"
  * "voidstarstar"

For the programmer
==================

The object ForeignPointerArrayType, is a
type (Macaulay2Doc), with ancestor classes ForeignType,
< Type (Macaulay2Doc) < MutableHashTable (Macaulay2Doc)
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

foreignPointerArrayType -- construct a foreign pointer array type
*****************************************************************

Synopsis
========

  * Usage:
        foreignArrayType(name, T)
        foreignArrayType T
  * Inputs:
      * name, a string (Macaulay2Doc),
      * T, a foreign type,
  * Outputs:
      * a foreign array type,

Description
===========

To construct a foreign array pointer type, specify a name and the type of the
elements of each array.  This type must necessarily be some kind of pointer
type.

+-------------------------------------------------------+
|i1 : foreignPointerArrayType("myPointerArray", 3 * int)|
|                                                       |
|o1 = myPointerArray                                    |
|                                                       |
|o1 : ForeignPointerArrayType                           |
+-------------------------------------------------------+

If the name is omitted, then a default one is chosen by taking the name of the
type of the elements and appending a star.

+-------------------------------------+
|i2 : foreignPointerArrayType(3 * int)|
|                                     |
|o2 = int32[3]*                       |
|                                     |
|o2 : ForeignPointerArrayType         |
+-------------------------------------+

Ways to use foreignPointerArrayType:
====================================

  * "foreignPointerArrayType(ForeignType)"
  * "foreignPointerArrayType(String,ForeignType)"

For the programmer
==================

The object foreignPointerArrayType, is a
method function (Macaulay2Doc).

ForeignPointerArrayType VisibleList -- cast a Macaulay2 list to a foreign pointer array
***************************************************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        T x
  * Inputs:
      * T, a foreign array type,
      * x, a visible list (Macaulay2Doc),
  * Outputs:
      * a foreign object, of type T;

Description
===========

To cast a Macaulay2 list to a foreign pointer array type, give the type
followed by the list.

+---------------------------------------------------------------+
|i1 : charstarstar {"foo", "bar"}                               |
|                                                               |
|o1 = {foo, bar}                                                |
|                                                               |
|o1 : ForeignObject of type char**                              |
+---------------------------------------------------------------+
|i2 : voidstarstar {address int 0, address int 1, address int 2}|
|                                                               |
|o2 = {0x7937c70da990, 0x7937c70da980, 0x7937c70da970}          |
|                                                               |
|o2 : ForeignObject of type void**                              |
+---------------------------------------------------------------+
|i3 : int2star = foreignPointerArrayType(2 * int)               |
|                                                               |
|o3 = int32[2]*                                                 |
|                                                               |
|o3 : ForeignPointerArrayType                                   |
+---------------------------------------------------------------+
|i4 : int2star {{1, 2}, {3, 4}, {5, 6}, {7, 8}, {9, 10}}        |
|                                                               |
|o4 = {{1, 2}, {3, 4}, {5, 6}, {7, 8}, {9, 10}}                 |
|                                                               |
|o4 : ForeignObject of type int32[2]*                           |
+---------------------------------------------------------------+

Ways to use this method:
========================

  * ForeignPointerArrayType VisibleList
    -- cast a Macaulay2 list to a foreign pointer array

ForeignRealType -- foreign real type
************************************

Description
===========

This is the class for C real types.  There are two built-in types, float for
reals using the single-precision floating-point format (see
https://en.wikipedia.org/wiki/single-precision_floating-point_format ) and
double for reals using the double-precision floating-point format (see
https://en.wikipedia.org/wiki/double-precision_floating-point_format ).

+--------------------+
|i1 : float          |
|                    |
|o1 = float          |
|                    |
|o1 : ForeignRealType|
+--------------------+
|i2 : double         |
|                    |
|o2 = double         |
|                    |
|o2 : ForeignRealType|
+--------------------+

Methods that use a foreign real type:
=====================================

  * ForeignRealType Number -- cast a Macaulay2
    number to a foreign real object
  * "ForeignRealType RRi" -- see ForeignRealType Number,
    -- cast a Macaulay2 number to a foreign real object

Protected objects of class ForeignRealType:
===========================================

  * "double"
  * "float"
  * mpfrT -- MPFR multiple-precision floating-point type

For the programmer
==================

The object ForeignRealType, is a type (Macaulay2Doc),
with ancestor classes ForeignType, <
Type (Macaulay2Doc) < MutableHashTable (Macaulay2Doc)
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

mpfrT -- MPFR multiple-precision floating-point type
****************************************************

Description
===========

Macaulay2's native RR (Macaulay2Doc), real number type wraps around
mpfr_t from MPFR (see https://mpfr.org/ ).  This type (which is an instance of
ForeignRealType) allows for conversion between
Macaulay2 reals and MPFR reals without loss of precision.

+-------------------------------------+
|i1 : mpfrT numeric(100, pi)          |
|                                     |
|o1 = 3.141592653589793238462643383279|
|                                     |
|o1 : ForeignObject of type mpfr_t    |
+-------------------------------------+
|i2 : value oo                        |
|                                     |
|o2 = 3.141592653589793238462643383279|
|                                     |
|o2 : RR (of precision 100)           |
+-------------------------------------+

Methods that use an object of class mpfrT:
==========================================

  * expression(mpfrT) (missing documentation)
  * "new mpfrT from RR"
  * "value(mpfrT)"

For the programmer
==================

The object mpfrT, is a foreign real type,
with ancestor classes ForeignObject, < HashTable (Macaulay2Doc)
< Thing (Macaulay2Doc).

ForeignRealType Number -- cast a Macaulay2 number to a foreign real object
**************************************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        T x
  * Inputs:
      * T, a foreign real type,
      * x, a number (Macaulay2Doc),
  * Outputs:
      * a foreign object,

Description
===========

To cast a Macaulay2 number to a foreign object with a real type, give the type
followed by the number.

+---------------------------------+
|i1 : float 3                     |
|                                 |
|o1 = 3                           |
|                                 |
|o1 : ForeignObject of type float |
+---------------------------------+
|i2 : double pi                   |
|                                 |
|o2 = 3.141592653589793           |
|                                 |
|o2 : ForeignObject of type double|
+---------------------------------+

The imaginary parts of complex numbers are discarded.

+---------------------------------+
|i3 : double(2 + 3*ii)            |
|                                 |
|o3 = 2                           |
|                                 |
|o3 : ForeignObject of type double|
+---------------------------------+

Ways to use this method:
========================

  * ForeignRealType Number -- cast a Macaulay2
    number to a foreign real object
  * "ForeignRealType RRi"

ForeignStringType -- foreign string type
****************************************

Description
===========

This is the class for C strings types, i.e., null-terminated character arrays.
There is one built-in type, charstar.

+----------------------+
|i1 : charstar         |
|                      |
|o1 = char*            |
|                      |
|o1 : ForeignStringType|
+----------------------+

Methods that use a foreign string type:
=======================================

  * ForeignStringType String -- cast a
    Macaulay2 string to a foreign string

Protected objects of class ForeignStringType:
=============================================

  * "charstar"

For the programmer
==================

The object ForeignStringType, is a type (Macaulay2Doc),
with ancestor classes ForeignType, <
Type (Macaulay2Doc) < MutableHashTable (Macaulay2Doc)
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

ForeignStringType String -- cast a Macaulay2 string to a foreign string
***********************************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        T x
  * Inputs:
      * T, a foreign string type,
      * x, a string (Macaulay2Doc),
  * Outputs:
      * a foreign object,

Description
===========

To cast a Macaulay2 string to a foreign object with a string type, give the
type followed by the string.

+--------------------------------+
|i1 : charstar "Hello, world!"   |
|                                |
|o1 = Hello, world!              |
|                                |
|o1 : ForeignObject of type char*|
+--------------------------------+

Ways to use this method:
========================

  * ForeignStringType String -- cast a
    Macaulay2 string to a foreign string

ForeignStructType -- foreign struct type
****************************************

Description
===========

This is the class for C struct (see
https://en.wikipedia.org/wiki/Struct_(C_programming_language) ) types.  There
are no built-in types.  They must be constructed using foreignStructType.

Functions and methods returning a foreign struct type:
======================================================

  * foreignStructType -- construct a foreign struct
    type

Methods that use a foreign struct type:
=======================================

  * "ForeignStructType HashTable" -- see ForeignStructType VisibleList,
    -- cast a hash table to a foreign struct
  * ForeignStructType VisibleList -- cast
    a hash table to a foreign struct
  * "ForeignStructType ForeignObject" -- see ForeignType ForeignObject,
    -- cast a foreign object to the given foreign
    type

For the programmer
==================

The object ForeignStructType, is a type (Macaulay2Doc),
with ancestor classes ForeignType, <
Type (Macaulay2Doc) < MutableHashTable (Macaulay2Doc)
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

foreignStructType -- construct a foreign struct type
****************************************************

Synopsis
========

  * Usage:
        foreignStructType(name, x)
  * Inputs:
      * name, a string (Macaulay2Doc),
      * x, a list (Macaulay2Doc), of options;
  * Outputs:
      * a foreign struct type,

Description
===========

To construct a foreign struct type, specify a name and a list of the members.
Each member should be an Option (Macaulay2Doc), of the form
memberName => memberType, where memberName is a String (Macaulay2Doc),
and memberType is a ForeignType.

+-------------------------------------------------------------------+
|i1 : foreignStructType("mystruct", {"foo" => int, "bar" => double})|
|                                                                   |
|o1 = mystruct                                                      |
|                                                                   |
|o1 : ForeignStructType                                             |
+-------------------------------------------------------------------+

Ways to use foreignStructType:
==============================

  * "foreignStructType(String,Option)"
  * "foreignStructType(String,VisibleList)"

For the programmer
==================

The object foreignStructType, is a method function (Macaulay2Doc).

ForeignStructType VisibleList -- cast a hash table to a foreign struct
**********************************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        T x
  * Inputs:
      * T, a foreign struct type,
      * x, a hash table (Macaulay2Doc), or a visible list (Macaulay2Doc),
  * Outputs:
      * a foreign object,

Description
===========

To cast a Macaulay2 hash table to a foreign object with a struct type, give the
type followed by the hash table, or a list that could be passed to
hashTable (Macaulay2Doc), to create one.  The keys should correspond
to the keys of the hash table passed to foreignStructType,
when constructing T.

+-----------------------------------------------------------------------------+
|i1 : mystruct = foreignStructType("mystruct", {"foo" => int, "bar" =>        |
|                                                                             |
|o1 = mystruct                                                                |
|                                                                             |
|o1 : ForeignStructType                                                       |
|-----------------------------------------------------------------------------|
|double})                                                                     |
+-----------------------------------------------------------------------------+
|i2 : x = mystruct {"foo" => 5, "bar" => pi}                                  |
|                                                                             |
|o2 = HashTable{"bar" => 3.14159}                                             |
|               "foo" => 5                                                    |
|                                                                             |
|o2 : ForeignObject of type mystruct                                          |
+-----------------------------------------------------------------------------+

Use _ to return a single member of a foreign struct.

+---------------------------------+
|i3 : x_"foo"                     |
|                                 |
|o3 = 5                           |
|                                 |
|o3 : ForeignObject of type int32 |
+---------------------------------+
|i4 : x_"bar"                     |
|                                 |
|o4 = 3.141592653589793           |
|                                 |
|o4 : ForeignObject of type double|
+---------------------------------+

They may also be modified using subscripted assignment.

+-----------------------------------+
|i5 : x_"foo" = 6                   |
|                                   |
|o5 = 6                             |
|                                   |
|o5 : ForeignObject of type int32   |
+-----------------------------------+
|i6 : x                             |
|                                   |
|o6 = HashTable{"bar" => 3.14159}   |
|               "foo" => 6          |
|                                   |
|o6 : ForeignObject of type mystruct|
+-----------------------------------+

Ways to use this method:
========================

  * "ForeignStructType HashTable"
  * ForeignStructType VisibleList -- cast
    a hash table to a foreign struct

ForeignUnionType -- foreign union type
**************************************

Description
===========

This is the class for C union (see https://en.wikipedia.org/wiki/Union_type )
types.  There are no built-in types.  They must be  constructed using
foreignUnionType.

Functions and methods returning a foreign union type:
=====================================================

  * foreignUnionType -- construct a foreign union type

Methods that use a foreign union type:
======================================

  * ForeignUnionType Thing -- cast a thing to a
    foreign union

For the programmer
==================

The object ForeignUnionType, is a type (Macaulay2Doc),
with ancestor classes ForeignType, <
Type (Macaulay2Doc) < MutableHashTable (Macaulay2Doc)
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

foreignUnionType -- construct a foreign union type
**************************************************

Synopsis
========

  * Usage:
        foreignUnionType(name, x)
  * Inputs:
      * name, a string (Macaulay2Doc),
      * x, a list (Macaulay2Doc), of options;
  * Outputs:
      * a foreign union type,

Description
===========

To construct a foreign union type, specify a name and a list of the members.
Each member should be an Option (Macaulay2Doc), of the form
memberName => memberType, where memberName is a String (Macaulay2Doc),
and memberType is a ForeignType.

+-------------------------------------------------+
|i1 : myunion = foreignUnionType("myunion",       |
|         {"foo" => 4 * char', "bar" => charstar})|
|                                                 |
|o1 = myunion                                     |
|                                                 |
|o1 : ForeignUnionType                            |
+-------------------------------------------------+

Use _ to return a single member of a foreign union.

+---------------------------------------------------+
|i2 : x = myunion (4 * char') append(ascii "hi!", 0)|
|                                                   |
|o2 = HashTable{"bar" => hi!              }         |
|               "foo" => {104, 105, 33, 0}          |
|                                                   |
|o2 : ForeignObject of type myunion                 |
+---------------------------------------------------+
|i3 : x_"foo"                                       |
|                                                   |
|o3 = {104, 105, 33, 0}                             |
|                                                   |
|o3 : ForeignObject of type int8[4]                 |
+---------------------------------------------------+
|i4 : x_"bar"                                       |
|                                                   |
|o4 = hi!                                           |
|                                                   |
|o4 : ForeignObject of type char*                   |
+---------------------------------------------------+

They may also be modified using subscripted assignment.

+------------------------------------------+
|i5 : x_"bar" = "ho!"                      |
|                                          |
|o5 = ho!                                  |
|                                          |
|o5 : ForeignObject of type char*          |
+------------------------------------------+
|i6 : x                                    |
|                                          |
|o6 = HashTable{"bar" => ho!              }|
|               "foo" => {104, 111, 33, 0} |
|                                          |
|o6 : ForeignObject of type myunion        |
+------------------------------------------+

Ways to use foreignUnionType:
=============================

  * "foreignUnionType(String,Option)"
  * "foreignUnionType(String,VisibleList)"

For the programmer
==================

The object foreignUnionType, is a method function (Macaulay2Doc).

ForeignUnionType Thing -- cast a thing to a foreign union
*********************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        T x
  * Inputs:
      * T, a foreign union type,
      * x, a thing (Macaulay2Doc),
  * Outputs:
      * a foreign object,

Description
===========

To cast a Macaulay2 thing to a foreign object with a union type, give the type
followed by the thing.  The appropriate member is determined automatically by
foreignObject.

+---------------------------------------------------------------------------+
|i1 : myunion = foreignUnionType("myunion", {"foo" => int, "bar" => double})|
|                                                                           |
|o1 = myunion                                                               |
|                                                                           |
|o1 : ForeignUnionType                                                      |
+---------------------------------------------------------------------------+
|i2 : myunion 27                                                            |
|                                                                           |
|o2 = HashTable{"bar" => 6.56927e-310}                                      |
|               "foo" => 27                                                 |
|                                                                           |
|o2 : ForeignObject of type myunion                                         |
+---------------------------------------------------------------------------+
|i3 : myunion pi                                                            |
|                                                                           |
|o3 = HashTable{"bar" => 3.14159   }                                        |
|               "foo" => 1413754136                                         |
|                                                                           |
|o3 : ForeignObject of type myunion                                         |
+---------------------------------------------------------------------------+

To avoid ambiguity, it may be helpful to first cast the thing to the
appropriate foreign type.

+----------------------------------+
|i4 : myunion double 5             |
|                                  |
|o4 = HashTable{"bar" => 5}        |
|               "foo" => 0         |
|                                  |
|o4 : ForeignObject of type myunion|
+----------------------------------+

Ways to use this method:
========================

  * ForeignUnionType Thing -- cast a thing to a
    foreign union

ForeignVoidType -- foreign void type
************************************

Description
===========

The void type (see https://en.wikipedia.org/wiki/void_type ).  There is one
built-in type of this class, void.

Note that there are no foreign objects of this type.  It is, however, used as a
return type for foreignFunction.  Such functions will
return null (Macaulay2Doc).  It may also be used by itself as an
argument type to indicate functions that take no arguments.

+--------------------+
|i1 : void           |
|                    |
|o1 = void           |
|                    |
|o1 : ForeignVoidType|
+--------------------+

Methods that use a foreign void type:
=====================================

  * "ForeignVoidType Nothing"
  * "getMemory(ForeignVoidType)" -- see getMemory, -- allocate
    memory using the garbage collector

Protected objects of class ForeignVoidType:
===========================================

  * "void"

For the programmer
==================

The object ForeignVoidType, is a type (Macaulay2Doc),
with ancestor classes ForeignType, <
Type (Macaulay2Doc) < MutableHashTable (Macaulay2Doc)
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

ForeignObject -- foreign object
*******************************

Description
===========

A ForeignObject represents some C object.  It consists of a Pointer,
with its address in memory.

+-------------------------------------+
|i1 : x = int 5                       |
|                                     |
|o1 = 5                               |
|                                     |
|o1 : ForeignObject of type int32     |
+-------------------------------------+
|i2 : peek x                          |
|                                     |
|o2 = int32{Address => 0x742f3ccda830}|
+-------------------------------------+

To get this, use address.

+-------------------+
|i3 : address x     |
|                   |
|o3 = 0x742f3ccda830|
|                   |
|o3 : Pointer       |
+-------------------+

Use class (Macaulay2Doc), to determine the type of the object.

+-----------------------+
|i4 : class x           |
|                       |
|o4 = int32             |
|                       |
|o4 : ForeignIntegerType|
+-----------------------+

Types of foreign object:
========================

  * "int8" -- see ForeignIntegerType, -- foreign
    integer type
  * "int16" -- see ForeignIntegerType, -- foreign
    integer type
  * "int32" -- see ForeignIntegerType, -- foreign
    integer type
  * "int64" -- see ForeignIntegerType, -- foreign
    integer type
  * "uint8" -- see ForeignIntegerType, -- foreign
    integer type
  * "uint16" -- see ForeignIntegerType, -- foreign
    integer type
  * "uint32" -- see ForeignIntegerType, -- foreign
    integer type
  * "uint64" -- see ForeignIntegerType, -- foreign
    integer type
  * "charstarstar" -- see ForeignPointerArrayType,
    -- foreign type for NULL-terminated arrays of
    pointers
  * "voidstarstar" -- see ForeignPointerArrayType,
    -- foreign type for NULL-terminated arrays of
    pointers
  * "voidstar" -- see ForeignPointerType, -- foreign
    pointer type
  * "double" -- see ForeignRealType, -- foreign real
    type
  * "float" -- see ForeignRealType, -- foreign real type
  * "charstar" -- see ForeignStringType, -- foreign
    string type
  * "void" -- see ForeignVoidType, -- foreign void type
  * mpfrT -- MPFR multiple-precision floating-point type
  * mpzT -- GMP arbitrary-precision integer type

Functions and methods returning a foreign object:
=================================================

  * foreignObject -- construct a foreign object
  * foreignSymbol -- get a foreign symbol

Methods that use a foreign object:
==================================

  * "address(ForeignObject)" -- see address, -- pointer to type
    or object
  * "foreignObject(ForeignObject)" -- see foreignObject,
    -- construct a foreign object
  * "ForeignStructType ForeignObject" -- see ForeignType ForeignObject,
    -- cast a foreign object to the given foreign
    type
  * ForeignType ForeignObject -- cast a
    foreign object to the given foreign type
  * registerFinalizer(ForeignObject,Function)
    -- register a finalizer
    for a foreign object
  * "describe(ForeignObject)" -- see value(ForeignObject),
    -- get the value of a foreign object as a
    Macaulay2 thing
  * "expression(ForeignObject)" -- see value(ForeignObject),
    -- get the value of a foreign object as a
    Macaulay2 thing
  * "net(ForeignObject)" -- see value(ForeignObject),
    -- get the value of a foreign object as a
    Macaulay2 thing
  * "texMath(ForeignObject)" -- see value(ForeignObject),
    -- get the value of a foreign object as a
    Macaulay2 thing
  * "toExternalString(ForeignObject)" -- see value(ForeignObject),
    -- get the value of a foreign object as a
    Macaulay2 thing
  * "toString(ForeignObject)" -- see value(ForeignObject),
    -- get the value of a foreign object as a
    Macaulay2 thing
  * value(ForeignObject) -- get the value of a
    foreign object as a Macaulay2 thing

For the programmer
==================

The object ForeignObject, is a self initializing type (Macaulay2Doc),
with ancestor classes
HashTable (Macaulay2Doc), < Thing (Macaulay2Doc).

foreignObject -- construct a foreign object
*******************************************

Synopsis
========

  * Usage:
        foreignObject x
  * Inputs:
      * x, a thing (Macaulay2Doc),
  * Outputs:
      * a foreign object,

Description
===========

This function constructs a ForeignObject.  The type is
determined automatically based on type of the input. Integers are converted to
int32, objects.

+--------------------------------+
|i1 : foreignObject 5            |
|                                |
|o1 = 5                          |
|                                |
|o1 : ForeignObject of type int32|
+--------------------------------+

Non-integers are converted to double, objects.

+---------------------------------+
|i2 : foreignObject pi            |
|                                 |
|o2 = 3.141592653589793           |
|                                 |
|o2 : ForeignObject of type double|
+---------------------------------+

Strings are converted to charstar, objects.

+----------------------------------+
|i3 : foreignObject "Hello, world!"|
|                                  |
|o3 = Hello, world!                |
|                                  |
|o3 : ForeignObject of type char*  |
+----------------------------------+

Pointers are converted to voidstar, objects.

+--------------------------------+
|i4 : foreignObject nullPointer  |
|                                |
|o4 = (nil)                      |
|                                |
|o4 : ForeignObject of type void*|
+--------------------------------+

Lists are converted to foreign objects with the appropriate
ForeignArrayType.

+-----------------------------------+
|i5 : foreignObject {1, 3, 5, 7, 9} |
|                                   |
|o5 = {1, 3, 5, 7, 9}               |
|                                   |
|o5 : ForeignObject of type int32[5]|
+-----------------------------------+

No conversion is done when the input is already a foreign object.

+-----------------------------------+
|i6 : foreignObject oo              |
|                                   |
|o6 = {1, 3, 5, 7, 9}               |
|                                   |
|o6 : ForeignObject of type int32[5]|
+-----------------------------------+

Ways to use foreignObject:
==========================

  * "foreignObject(ForeignObject)"
  * "foreignObject(Number)"
  * "foreignObject(Pointer)"
  * "foreignObject(String)"
  * "foreignObject(VisibleList)"
  * "foreignObject(ZZ)"

For the programmer
==================

The object foreignObject, is a method function (Macaulay2Doc).

foreignSymbol -- get a foreign symbol
*************************************

Synopsis
========

  * Usage:
        foreignSymbol(lib, symb, T)
        foreignSymbol(symb, T)
  * Inputs:
      * lib, a shared library,
      * symb, a string (Macaulay2Doc),
      * T, a foreign type,
  * Outputs:
      * a foreign object,

Description
===========

This function is a wrapper around the C function dlsym.  It loads a symbol from
a shared library using the specified foreign type. If the shared library is
already linked against Macaulay2, then it may be omitted.

+--------------------------------+
|i1 : foreignSymbol("errno", int)|
|                                |
|o1 = 22                         |
|                                |
|o1 : ForeignObject of type int32|
+--------------------------------+

Ways to use foreignSymbol:
==========================

  * "foreignSymbol(SharedLibrary,String,ForeignType)"
  * "foreignSymbol(String,ForeignType)"

For the programmer
==================

The object foreignSymbol, is a method function (Macaulay2Doc).

value(ForeignObject) -- get the value of a foreign object as a Macaulay2 thing
******************************************************************************

Synopsis
========

  * Function: value (Macaulay2Doc),
  * Usage:
        value x
  * Inputs:
      * x, a foreign object,
  * Outputs:
      * a thing (Macaulay2Doc),

Description
===========

Convert the given foreign object to the corresponding Macaulay2 thing. The type
of the output is determined by the type of the foreign object. Foreign integer
objects are converted to ZZ (Macaulay2Doc), objects.

+--------------------------------+
|i1 : x = int 5                  |
|                                |
|o1 = 5                          |
|                                |
|o1 : ForeignObject of type int32|
+--------------------------------+
|i2 : value x                    |
|                                |
|o2 = 5                          |
+--------------------------------+

Foreign real objects are converted to RR (Macaulay2Doc), objects.

+---------------------------------+
|i3 : x = double 5                |
|                                 |
|o3 = 5                           |
|                                 |
|o3 : ForeignObject of type double|
+---------------------------------+
|i4 : value x                     |
|                                 |
|o4 = 5                           |
|                                 |
|o4 : RR (of precision 53)        |
+---------------------------------+

Foreign pointer objects are converted to Pointer, objects.

+--------------------------------+
|i5 : x = voidstar address int 5 |
|                                |
|o5 = 0x7d84774da250             |
|                                |
|o5 : ForeignObject of type void*|
+--------------------------------+
|i6 : value x                    |
|                                |
|o6 = 0x7d84774da250             |
|                                |
|o6 : Pointer                    |
+--------------------------------+

Foreign string objects are converted to strings.

+---------------------------------+
|i7 : x = charstar "Hello, world!"|
|                                 |
|o7 = Hello, world!               |
|                                 |
|o7 : ForeignObject of type char* |
+---------------------------------+
|i8 : value x                     |
|                                 |
|o8 = Hello, world!               |
+---------------------------------+

Foreign array objects are converted to lists.

+-----------------------------------+
|i9 : x = (4 * int) {2, 4, 6, 8}    |
|                                   |
|o9 = {2, 4, 6, 8}                  |
|                                   |
|o9 : ForeignObject of type int32[4]|
+-----------------------------------+
|i10 : value x                      |
|                                   |
|o10 = {2, 4, 6, 8}                 |
|                                   |
|o10 : List                         |
+-----------------------------------+

Foreign struct and union objects are converted to hash tables.

+--------------------------------------------------------------------------+
|i11 : mystruct = foreignStructType("mystruct", {"a" => int, "b" => float})|
|                                                                          |
|o11 = mystruct                                                            |
|                                                                          |
|o11 : ForeignStructType                                                   |
+--------------------------------------------------------------------------+
|i12 : x = mystruct {"a" => 2, "b" => sqrt 2}                              |
|                                                                          |
|o12 = HashTable{"a" => 2      }                                           |
|                "b" => 1.41421                                            |
|                                                                          |
|o12 : ForeignObject of type mystruct                                      |
+--------------------------------------------------------------------------+
|i13 : value x                                                             |
|                                                                          |
|o13 = HashTable{"a" => 2      }                                           |
|                "b" => 1.41421                                            |
|                                                                          |
|o13 : HashTable                                                           |
+--------------------------------------------------------------------------+

Note that this function is also used by describe (Macaulay2Doc),
see expression (Macaulay2Doc),
net (Macaulay2Doc), texMath (Macaulay2Doc),
toExternalString (Macaulay2Doc), and toString (Macaulay2Doc),
for representing foreign objects.

Ways to use this method:
========================

  * "value(charstar)"
  * "value(charstarstar)"
  * "value(double)"
  * "value(float)"
  * value(ForeignObject) -- get the value of a
    foreign object as a Macaulay2 thing
  * "value(int8)"
  * "value(int16)"
  * "value(int32)"
  * "value(int64)"
  * "value(uint8)"
  * "value(uint16)"
  * "value(uint32)"
  * "value(uint64)"
  * "value(voidstar)"
  * "value(voidstarstar)"

ForeignType ForeignObject -- cast a foreign object to the given foreign type
****************************************************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        T x
  * Inputs:
      * T, a foreign type,
      * x, a foreign object,
  * Outputs:
      * a foreign object,

Description
===========

Cast the given foreign object to the given foreign type.  Note that the
addresses will remain the same.

+------------------------------------------+
|i1 : chararray4 = 4 * char'               |
|                                          |
|o1 = int8[4]                              |
|                                          |
|o1 : ForeignArrayType                     |
+------------------------------------------+
|i2 : x = chararray4 append(ascii "foo", 0)|
|                                          |
|o2 = {102, 111, 111, 0}                   |
|                                          |
|o2 : ForeignObject of type int8[4]        |
+------------------------------------------+
|i3 : y = charstar x                       |
|                                          |
|o3 = foo                                  |
|                                          |
|o3 : ForeignObject of type char*          |
+------------------------------------------+
|i4 : address x === address y              |
|                                          |
|o4 = true                                 |
+------------------------------------------+

Ways to use this method:
========================

  * "ForeignStructType ForeignObject"
  * ForeignType ForeignObject -- cast a
    foreign object to the given foreign type

registerFinalizer(ForeignObject,Function) -- register a finalizer for a foreign object
**************************************************************************************

Synopsis
========

  * Function: registerFinalizer (Macaulay2Doc),
  * Usage:
        registerFinalizer(x, f)
  * Inputs:
      * x, a foreign object,
      * f, a function (Macaulay2Doc),

Description
===========

If a foreign pointer object corresponds to memory that was not allocated by the
GC garbage collector (Macaulay2Doc), then a
function to properly deallocate this memory when the Pointer,
object that stores this pointer is garbage collected should be called.  The
function should take a single argument, a foreign object, typically  of type
voidstar, which corresponds to the memory to
deallocate.

+-------------------------------------------------------------------+
|i1 : malloc = foreignFunction("malloc", voidstar, ulong)           |
|                                                                   |
|o1 = malloc                                                        |
|                                                                   |
|o1 : ForeignFunction                                               |
+-------------------------------------------------------------------+
|i2 : free = foreignFunction("free", void, voidstar)                |
|                                                                   |
|o2 = free                                                          |
|                                                                   |
|o2 : ForeignFunction                                               |
+-------------------------------------------------------------------+
|i3 : finalizer = x -> (print("freeing memory at " | net x); free x)|
|                                                                   |
|o3 = finalizer                                                     |
|                                                                   |
|o3 : FunctionClosure                                               |
+-------------------------------------------------------------------+
|i4 : for i to 9 do (x := malloc 8; registerFinalizer(x, finalizer))|
+-------------------------------------------------------------------+
|i5 : collectGarbage()                                              |
|freeing memory at 0x781e30057430                                   |
|freeing memory at 0x781e30063ea0freeing memory at 0x781e300663f0   |
|freeing memory at 0x781e30066410                                   |
|freeing memory at 0x781e3006a280                                   |
|freeing memory at 0x781e300688b0                                   |
|freeing memory at 0x781e300688d0                                   |
|freeing memory at 0x781e30066b10                                   |
|                                                                   |
|freeing memory at 0x781e300634b0                                   |
+-------------------------------------------------------------------+

See also
========

  * getMemory -- allocate memory using the garbage collector

Ways to use this method:
========================

  * registerFinalizer(ForeignObject,Function)
    -- register a finalizer
    for a foreign object

Pointer -- pointer to memory address
************************************

Description
===========

Pointer objects are pointers to memory addresses.  These make up each
ForeignObject.

+-------------------------------------+
|i1 : x = int 20                      |
|                                     |
|o1 = 20                              |
|                                     |
|o1 : ForeignObject of type int32     |
+-------------------------------------+
|i2 : peek x                          |
|                                     |
|o2 = int32{Address => 0x7d569457a010}|
+-------------------------------------+

These pointers can be accessed using address.

+--------------------+
|i3 : ptr = address x|
|                    |
|o3 = 0x7d569457a010 |
|                    |
|o3 : Pointer        |
+--------------------+

Simple arithmetic can be performed on pointers.

+-------------------+
|i4 : ptr + 5       |
|                   |
|o4 = 0x7d569457a015|
|                   |
|o4 : Pointer       |
+-------------------+
|i5 : ptr - 3       |
|                   |
|o5 = 0x7d569457a00d|
|                   |
|o5 : Pointer       |
+-------------------+

Functions and methods returning a pointer:
==========================================

  * address -- pointer to type or object

Methods that use a pointer:
===========================

  * "* Pointer = Thing" -- see * voidstar = Thing,
    -- assign value to object at address
  * "foreignFunction(Pointer,String,ForeignType,VisibleList)" -- see
    foreignFunction, -- construct a foreign function
  * "foreignObject(Pointer)" -- see foreignObject, --
    construct a foreign object
  * ForeignPointerType Pointer -- cast a
    Macaulay2 pointer to a foreign pointer
  * ForeignType Pointer -- dereference a pointer
  * "Pointer + ZZ"
  * "Pointer - ZZ"
  * "ZZ + Pointer"

For the programmer
==================

The object Pointer, is a type (Macaulay2Doc), with
ancestor class Thing (Macaulay2Doc).

nullPointer -- the null pointer
*******************************

Description
===========

This Pointer, object represents the null pointer (see
https://en.wikipedia.org/wiki/null_pointer ), indicating that the pointer does
not refer to a valid object.

+----------------+
|i1 : nullPointer|
|                |
|o1 = (nil)      |
|                |
|o1 : Pointer    |
+----------------+

For the programmer
==================

The object nullPointer, is a pointer.

address -- pointer to type or object
************************************

Synopsis
========

  * Usage:
        address x
  * Inputs:
      * x, a foreign type, or a foreign object,
  * Outputs:
      * a pointer,

Description
===========

If x is a foreign type, then this returns the address to the ffi_type struct
used by libffi to identify the type.

+-------------------+
|i1 : address int   |
|                   |
|o1 = 0x62302f34ec20|
|                   |
|o1 : Pointer       |
+-------------------+

If x is a foreign object, then this returns the address to the object.  It
behaves like the & "address-of" operator in C.

+-------------------+
|i2 : address int 5 |
|                   |
|o2 = 0x75540c97a410|
|                   |
|o2 : Pointer       |
+-------------------+

Ways to use address:
====================

  * "address(ForeignObject)"
  * "address(ForeignType)"
  * address(Nothing) (missing documentation)

For the programmer
==================

The object address, is a method function (Macaulay2Doc).

ForeignType Pointer -- dereference a pointer
********************************************

Synopsis
========

  * Operator: SPACE (Macaulay2Doc),
  * Usage:
        T ptr
  * Inputs:
      * T, a foreign type,
      * ptr, a pointer,
  * Outputs:
      * a foreign object, of type T;

Description
===========

Dereference the given pointer into the corresponding foreign object, much like
the dereference operator (*) in C.

+--------------------------------+
|i1 : x = int 5                  |
|                                |
|o1 = 5                          |
|                                |
|o1 : ForeignObject of type int32|
+--------------------------------+
|i2 : ptr = address x            |
|                                |
|o2 = 0x7a586197a050             |
|                                |
|o2 : Pointer                    |
+--------------------------------+
|i3 : int ptr                    |
|                                |
|o3 = 5                          |
|                                |
|o3 : ForeignObject of type int32|
+--------------------------------+

Ways to use this method:
========================

  * ForeignType Pointer -- dereference a pointer