Deploying Standalone Wolfram Language Applications

Presentation by:
	Chris Cooley
	Engine Connectivity Engineering
	ccooley@wolfram.com

Table of Contents

Problems When Creating Applications

How We Want to Fix Creating Applications

Licensing Developer’s Applications

Making the Kernel Linkable

Bundling the Engine

The Overall Workflow

Goals of This Talk

How to Contact Us

Technical Details: Licensing Developer’s Applications

Technical Details: Bundling the Engine

Technical Details: Expression API

Appendix: Breaking Down the Size of the Engine

Appendix: Expression API Listing

Appendix: Shape of the Expression API

Problems When Creating Applications

There is no quick and easy method to process Wolfram Language code into truly distributable applications

End users must have a license and Wolfram Language engine in order to run an application

Current licensing options do not work well for distributing applications

The size of the engine discourages developers from bundling the engine with their application

Problems When Creating Applications   
(Continued)

Awkward communication technologies like WSTP discourage developers, especially if they want to use Wolfram Language as part of a larger system

It is not possible to generate an executable or library from arbitrary Wolfram Language code

How We Want to Fix Creating Applications

Licensing applications themselves

Making the kernel linkable using a simple API for interacting with expressions

Making bundling the engine as easy and lightweight as possible

Offering a quick self-service workflow for developers who wish to license their application

How We Want to Fix Creating Applications
(Continued)

Improving application development generally

Tools for writing paclets (PacletTools)

Tools for inspecting code, formatting code, and instrumenting code (CodeParser)

Licensing Developer’s Applications

Goal: Allow end users to execute approved Wolfram Language applications even if they do not hold a license

An unlicensed engine can only execute approved applications, so pricing will be tailored specifically to your application

In typical cases, you will be able to walk through an automatic process for licensing your application

Licensed applications can be optionally configured so that internet access is not required

Possible free-tier scenarios: academia, open-source, limited number of unique users, etc.

Making the Kernel Linkable

Goal: Allow users to directly link against the engine, and create, evaluate, and interact with the kernel’s expressions on the fly

This will enable the “compilation” of Wolfram Language applications into executables and libraries

The Wolfram Language kernel runs in your process

The specific role of the expression API will become clearer once we demo a specific application

Bundling the Engine

Goal: Making it easy and practical for developers to bundle the engine with their application

Developers will only have to include the components of the engine necessary for their application, reducing its size footprint

We are also exploring the potential for truly standalone executables and libraries that embed the engine’s layout

The Overall Workflow

Start with the Wolfram Language code you wish to process (e.g., a paclet, source file, script)

Use our command-line tool or Wolfram Language function to begin processing your application

Select whether you wish to produce an executable or library

Configure the executable or library

The Overall Workflow
(Continued)

Select whether you wish to bundle the engine with your application

If bundling the engine, our tool will walk you through removing unnecessary layout components

If you are releasing your application, our tool will walk you through the application licensing process

Goals of This Talk

To present our vision of application deployment in the Wolfram Language

To ask for feedback

What our your needs? How do you want to use these technologies?

How do you think application deployment should work? What are your opinions regarding the technical details?

To get you to go to our roundtable at 4 PM later today!

How to Contact Us

Come see us

After the talk

At the standalone applications roundtable at 4 PM

At other conference events

Send an email to ccooley@wolfram.com

Technical Details:
Licensing Developer’s Applications

Wolfram Research will generate signatures for approved applications

An unlicensed engine can only evaluate files from the layout or your application when valid signatures for those files are registered

Wolfram Language files and MX files are examples of items that need to be signed

Our tools will handle signing the necessary components of your application

Technical Details:
Bundling the Engine

The following components take up ~2.2 GB of the 3 GB size of the Wolfram Engine:

Technical Details:
Bundling the Engine

Switch from MKL to OpenBLAS when acceptable

Remove any documentation, data, examples, and SDKs

Remove Front End dependencies

Technical Details:
Bundling the Engine
(Continued)

Remove all components that will not be used by the application bundling the engine

Potentially three types of application-based “pruning”

Static analysis

Dynamic analysis

Manual

Technical Details:
Expression API

In binaries that we produce, the expression API is used to load and interact with your Wolfram Language code

When using the expression API, unlicensed kernels can only evaluate expressions with heads that are signed

If you building a library, we will generate signatures for the application functions you are exporting

Appendix: Breaking Down the Size of the Engine

SystemFiles/Libraries (~900 MB if backend is MKL, ~120 MB if backend is OPENBLAS)

libWolframEngine.dylib (~50MB)

libWolframRTL.dylib (~10MB)

MKL and friends  (~790MB)

OpenBLAS (~10MB)

SystemFiles/Kernel (~120MB)

MX startup files (~110MB)

Text resources (~10MB)

SystemFiles/Links (~770MB)

OpenCascadeLink (~82MB)

Documentation (~20MB)

ExampleData (~10MB)

MathLink/WSTP (~80MB)

OpenCVLink (~60MB)

DICOMTools (~52MB)

FDLLink (~45MB)

...

SystemFiles/Components (~670MB)

AutoCompletionData (~150MB)

SpellingData (~140MB)

LLVMLink (~86MB)

MXNetLink (~80MB)

PresenterTools (~60MB)

Compile (~40MB)

...

SystemFiles/Java (~90MB)

SystemFiles/Converters (~70MB)

Java (~30MB)

Tesseract (~20MB)

Binaries (~10MB)

FindCharacterEncoding (~10MB)

SystemFiles/Data (~40MB)

SoundFonts (~20MB)

SSDdetector (~10MB)

VideoExampleData (~6MB)

SystemFiles/Fonts (~30MB)

TrueType (~30MB)

SVG (~10MB)

SystemFiles/FrontEnd (~120MB)

SystemResources (~90MB)

TextResources (~10MB)

Palettes (~10MB)

StyleSheets (~10MB)

Appendix: Expression API Listing

Macros

api_E(expressionHead, ...) — goes to api_VariadicE

api_List(...) — goes to api_VariadicList

api_Association(...) — goes to api_VariadicAssociation

Typedefs

api_expr — void*

api_exprbag — void*

api_num_t — enum api_number_type

api_expr_t — enum api_expression_type

api_err_t — enum api_error_type

api_output_handler_t — void (*)(char*, mint, void*)

api_message_handler_t — void (*)(api_expr, api_expr, api_expr, void*)

Enumerations

api_number_type

API_MACHINE_INTEGER

API_BIG_INTEGER

API_MACHINE_REAL

API_BIG_REAL

API_COMPLEX

API_RATIONAL

API_OVERFLOW

API_UNDERFLOW

API_NOT_A_NUMBER

api_expression_type

API_NUMBER

API_STRING

API_SYMBOL

API_NORMAL

API_ERROR

API_PACKED_ARRAY

API_NUMERIC_ARRAY

API_OBJECT_INSTANCE

API_BOOLEAN_FUNCTION

API_GRAPH

API_ASSOCIATION

API_DISPATCH

API_REGION

API_STATE_DATA

API_TYPED_EXPRESSION

API_OTHER

api_error_type

API_SUCCESS

API_ALLOCATION_ERROR

API_UNEXPECTED_TYPE_ERROR

API_MISCELLANEOUS_ERROR

API_MALFORMED_ERROR

API_OUT_OF_BOUNDS_ERROR

Functions

api_Abort

Signature

void api_Abort(void)

Description

Attempt to abort evaluations

Remarks

This function attempts to cause any ongoing or future evaluations to be aborted

This function can be called from a signal handler

This function can be called from any thread

Call api_ClearAbort to allow evaluations to proceed

If there is an ongoing evaluation inside an AbortProtect, the abort will be delayed until the AbortProtect is exited

Post-condition

Evaluations will be aborted until api_ClearAbort is called

api_AddExpression

Signature

api_err_t api_AddExpression(api_exprbag expressionBag, api_expr expression)

Description

Add an expression to an expression bag

Parameters

expressionBag — The expression bag

expression — The expression

Returns

Whether the expression was successfully added to the expression bag

Return values

API_SUCCESS — The function succeeded

API_UNEXPECTED_TYPE_ERROR — The expression was an error expression

API_MISCELLANEOUS_ERROR — A miscellaneous error occurred

api_AddMessageHandler

Signature

api_err_t api_AddMessageHandler(api_message_handler_t handlerFunction, void *contextData)

Description

Add a handler function that will be called whenever a message is raised during an evaluation

Parameters

handlerFunction — The handler function

contextData — Context data to be provided to the handler function

Returns

Whether the handler function and context data have been successfully added

Return values

API_SUCCESS — The handler function and context data have been successfully added

API_MISCELLANEOUS_ERROR — The maximum number of message handlers have already been added

API_MISCELLANEOUS_ERROR — A miscellaneous error occurred

Remarks

The handler function will always be called with four arguments: the tag for the message, an expression representing the message in the form Hold[Message[...]], the text of the message had it otherwise been outputted, and the context data

The expression arguments to the handler function will be automatically released when the function returns: use api_Clone to get a copy of an expression argument that you own the memory of

Up to 100 message handlers can be defined at the same time, and each message handler can have a different context data

If handlerFunction is already registered, the existing context data for that handler will be replaced with contextData

Add api_DefaultMessageHandler as a handler function in order to allow messages to produce output

If an output handler function is registered, it will only be called when a message is raised if api_DefaultMessageHandler is registered

Post-condition

By default, no message or output handlers are registered, and output will be suppressed

api_AddOutputHandler

$Output

Signature

api_err_t api_AddOutputHandler(api_output_handler_t handlerFunction, void *contextData)

Description

Add a handler function that will be called whenever the stdout stream is written to during an evaluation

Parameters

handlerFunction — The handler function

contextData — Context data to be provided to the handler function

Returns

Whether the handler function and context data have been successfully added

Return values

API_SUCCESS — The handler function and context data have been successfully added

API_MISCELLANEOUS_ERROR — The maximum number of output handlers have already been added

API_MISCELLANEOUS_ERROR — A miscellaneous error occurred

Remarks

The handler function will always be called with three arguments: a UTF8-encoded output string, the length of the output string, and the context data

Up to 100 output handlers can be defined at the same time, and each output handler can have a different context data

If handlerFunction is already registered, the existing context data for that handler will be replaced with contextData

Add api_DefaultOutputHandler as a handler function in order to allow output to stdout

Post-condition

By default, no output handlers are registered, and output to stdout will be suppressed

api_AssociationQ

Signature

mbool api_AssociationQ(api_expr expression)

Description

Test if an expression is an association

Parameters

expression — The expression

Returns

Whether the expression is an association

Return values

TRUE — The expression is an association

FALSE — The expression is not an association

Remarks

This function will return FALSE for normalized associations

api_ClearAbort

Signature

void api_ClearAbort(void)

Description

Allow evaluations to proceed by cancelling any previous calls to api_Abort

Remarks

This function allows future evaluations to proceed

This function can be called from a signal handler

This function can be called from any thread

If api_Abort has been called, any evaluation started before the call to api_ClearAbort will still be attempted to be aborted

Pre-condition

This function does not require api_Abort to have been previously called

Post-condition

Future evaluations will be able to proceed

api_Clone

Signature

api_expr api_Clone(api_expr expression)

Description

Clone an expression

Parameters

expression — The expression to clone

Returns

The cloned expression

Remarks

This function can be used to get a copy of expression you do not manage the memory of (e.g., the expression arguments to message handlers)

The memory of the cloned expression will be managed like any other expression returned by an API function (e.g, if there is an expression pool, the cloned expression will be associated with it)

In other words, you will always own the memory of the returned expression

api_Complex

Signature

api_expr api_Complex(api_expr realPart, api_expr imaginaryPart)

Description

Create a complex number expression using specific real and imaginary parts

Parameters

realPart — The real part

imaginaryPart — The imaginary part

Returns

A complex number expression

Error return values

api_Error(API_UNEXPECTED_TYPE_ERROR) — An argument was not a number or was a complex number

api_Error(API_ALLOCATION_ERROR) — Failed to create a complex number expression

api_Error(<propogated_from_argument>) — An argument was an error expressions

api_ContextSymbol

Signature

api_expr api_ContextSymbol(char *symbolContext, char *symbolName)

Description

Get a symbol expression in the specified context

Parameters

symbolContext — The context of the symbol

symbolName — The base name of the symbol

Returns

The symbol expression

Error return values

api_Error(API_MISCELLANEOUS_ERROR) — An error occurred

Remarks

The context and base name can contain long names (e.g., \[[Alpha] and \::03b1 will become α) and non-ASCII Unicode characters as long as the resulting context and base name are well-formed

symbolContext and symbolName must be UTF8-encoded null-terminated strings

api_CreateExpressionPool

Signature

void api_CreateExpressionPool (void)

Description

Create a new expression pool

Remarks

It is not necessary to call api_ReleaseExpressionPool after calling api_CreateExpressionPool in order to call api_CreateExpressionPool again

In other words, expression pools can be nested

Post-condition

Expressions returned by API functions will be associated with the new expression pool until the expression pool is released

The new expression pool will become the current expression pool

Old expression pools will only be restored when api_ReleaseExpressionPool is called

api_Denominator

Signature

api_expr api_Denominator(api_expr rationalExpression)

Description

Get the denominator of a rational expression

Parameters

rationalExpression — The rational expression

Returns

The denominator as an integer expression

Error return values

api_Error(API_UNEXPECTED_TYPE_ERROR) — The expression was not a rational

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

This function can return a machine integer or big integer expression

api_DetachExpression

Signature

void api_DetachExpression(api_expr expression)

Description

Detach an expression in the current expression pool

Parameters

expression — The expression to detach

Pre-condition

There must be a current expression pool created using api_CreateExpressionPool that has not been released

The expression must be associated with the current expression pool, and it cannot have been previously detached

Post-condition

The expression has been detached, and it can only be released using api_ReleaseExpression or api_ReleaseAll

api_Error

Signature

api_expr api_Error(api_err_t errorType)

Description

Create an error expression using a specific error type

Parameters

errorType — The error type

Returns

An error expression

api_ErrorType

Signature

api_err_t api_ErrorType(api_expr errorExpression)

Description

Get the type of an error expression

Parameters

errorExpression — The expression

Returns

The type of the error expression

Return values

API_ALLOCATION_ERROR — The expression is api_Error(API_ALLOCATION_ERROR)

API_UNEXPECTED_TYPE_ERROR — The expression is api_Error(API_UNEXPECTED_TYPE_ERROR)

API_MISCELLANEOUS_ERROR — The expression is api_Error(API_MISCELLANEOUS_ERROR)

API_OUT_OF_BOUNDS_ERROR — The expression is api_Error(API_OUT_OF_BOUNDS_ERROR)

API_MALFORMED_ERROR — The expression is api_Error(API_MALFORMED_ERROR)

API_SUCCESS — The expression is api_Error(API_SUCCESS)

API_MALFORMED_ERROR — The expression is not a well-formed error expression

api_ErrorQ

Signature

mbool api_ErrorQ(api_expr expression)

Description

Check whether an expression is an error expression

Parameters

expression — The expression

Returns

Whether the expression is an error expression

Return values

TRUE — The expression is an error expression

FALSE — The expression is not an error expression

api_Eval

Signature

api_expr api_Eval(api_expr expression)

Description

Evaluate an expression

Parameters

expression — The expression

Returns

The evaluated form of the expression

Error return values

api_Error(API_MISCELLANEOUS_ERROR) — An error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

The only API functions that will evaluate provided expressions are api_Eval and api_EvalData

api_EvalData

Signature

api_expr api_EvalData(api_expr expression)

Description

Evaluate an expression

Parameters

expression — The expression

Returns

An association containing the evaluation result and other evaluation data (e.g., generated output)

Error return values

api_Error(API_MISCELLANEOUS_ERROR) — An error occurred

api_Error(API_ALLOCATION_ERROR) — An allocation error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

The association will contain the keys “Result,” “OutputLog,” “Messages,” “MessagesText,” and “MessagesExpressions”

The value of the “Result” key will be the evaluated form of the expression

The value of the “OutputLog” key will be a list of string expressions corresponding to the output of the evaluation

The value of the “Messages” key will be a list of expressions corresponding to the tags of the messages generated during the evaluation

The value of the “MessagesText” key will be a list of string expressions corresponding to the text of the messages generated during the evaluation

The value of the “MessagesExpressions” key will be a list of expressions in the form Hold[Message[...]] corresponding to the held form of the messages generated during the evaluation

Output and message handlers will still run during the evaluation, but the evaluation data will be determined according to default output and message behavior

Output generated from a message will be present in "MessagesText" and not in "OutputLog"

Information about output and messages generated inside of an evaluation in an output or message handler will not be present in the evaluation data

The only API functions that will evaluate provided expressions are api_Eval and api_EvalData

api_ExpressionBag

Signature

api_exprbag api_ExpressionBag(void)

Description

Create an expression bag

Returns

An expression

Return values

NULL — An error occurred

Remarks

Expression bags can be converted into expressions where the elements are the contents of the expression bag using api_ExpressionBagToExpression

It is the responsibility of the user to release the expression bag using api_ReleaseExpressionBag

Post-condition

If the result is non-NULL, expressions can be added to the result

api_ExpressionFromNumericArray

Signature

api_expr api_ExpressionFromNumericArray(MNumericArray numericArray, api_expr expressionHead)

Description

Get an expression from a numeric array

Parameters

numericArray — The numeric array

expressionHead — The head for the expression to create

Returns

The expression created from a numeric array

Error return values

api_Error(API_MISCELLANEOUS_ERROR) — The head is api_Symbol(“ByteArray”), but the type of the numeric array is not MNumericArray_Type_UBit8

api_Error(API_MISCELLANEOUS_ERROR) — An error occurred

api_Error(<propogated_from_argument>) — The expression head was an error expression

Remarks

If the head is api_Symbol("List"), the expression may be a packed array

If the head is api_Symbol("NumericArray") or api_Symbol(“ByteArray”), the expression will be a numeric array (i.e., not a normal expression)

If the head is none of the above, the expression will be a normal expression with the provided head

api_ExpressionFromRealArray

Signature

api_expr api_ExpressionFromRealArray(mint arrayLength, mreal *array, api_expr expressionHead)

Description

Get an expression from an array of reals

Parameters

arrayLength — The length of the real array

array — The real array

expressionHead — The head for the expression to create

Returns

The expression created from a real array

Error return values

api_Error(API_MISCELLANEOUS_ERROR) — The head is api_Symbol("ByteArray")

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(API_ALLOCATION_ERROR) — An allocation error occurred

api_Error(<propogated_from_argument>) — The expression head was an error expression

Remarks

If the head is api_Symbol(“List”), the expression may be a packed array

If the head is api_Symbol("NumericArray"), the expression will be a numeric array (i.e., not a normal expression)

If the head is none of the above, the expression will be a normal expression with the provided head

api_ExpressionType

Signature

api_expr_t api_ExpressionType(api_expr expression)

Description

Get the type of an expression

Parameters

expression — The expression

Returns

The type of the expression

Return values

API_NUMBER — The expression is a number

API_NORMAL — The expression is a normal

API_SYMBOL — The expression is a symbol

API_STRING — The expression is a string

API_PACKED_ARRAY — The expression is a packed array

API_NUMERIC_ARRAY — The expression is a numeric array

API_OBJECT_INSTANCE — The expression is an object instance

API_BOOLEAN_FUNCTION — The expression is a boolean function

API_GRAPH — The expression is a graph

API_ASSOCIATION — The expression is an association

API_DISPATCH — The expression is a dispatch table

API_REGION — The expression is a region

API_STATE_DATA — The expression is NSolve state data

API_TYPED_EXPRESSION — The expression is a typed expression

API_ERROR — The expression is an error

API_OTHER — The expression is a type not listed above

Remarks

There are API functions for interacting with normals, symbols, strings, packed arrays, numeric arrays, associations, error expressions, sparse arrays, and symmetrized arrays

Sparse arrays and symmetrized arrays are object instances

Some expression types need to be converted to normal expressions using api_Normalize in order for their data to be accessed

api_First

Signature

api_expr api_First(api_expr expression)

Description

Get the first part of an expression

Parameters

expression — The expression

Returns

The first part of an expression

Error return values

api_Error(API_OUT_OF_BOUNDS_ERROR) — The expression does not contain any parts

api_Error(API_OUT_OF_BOUNDS_ERROR) — The expression was not a normal expression, array-type expression, or association

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

This function is similar to the Wolfram Language function First

Array-type expressions are packed arrays, numeric arrays, byte arrays, sparse arrays, and symmetrized arrays

api_GetKeys

Signature

api_expr api_GetKeys(api_expr association)

Description

Get a list of keys in an association

Parameters

association — The association

Returns

The list of keys in the association

Error return values

api_Error(API_UNEXPECTED_TYPE_ERROR) — The expression is not an association

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

This function is similar to the Wolfram Language functions Keys

api_GetValueFromKey

Signature

api_expr api_GetValueFromKey(api_expr association, api_expr key)

Description

Get the value of a key in an association

Parameters

association — The association

key — The key

Returns

The value of the key

Error return values

api_Error(API_UNEXPECTED_TYPE_ERROR) — The first argument is not an association

api_Error(API_MISCELLANEOUS_ERROR) — The key was not present in the association

api_Error(<propogated_from_argument>) — An argument was an error expression

Remarks

This function does not evaluate the value of the key, so it is possible that the result will be unevaluated (e.g., if the key-value pair is RuleDelayed)

api_GetValues

Signature

api_expr api_GetValues(api_expr association)

Description

Get a list of values in an association

Parameters

association — The association

Returns

The list of values in the association

Error return values

api_Error(API_UNEXPECTED_TYPE_ERROR) — The expression is not an association

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

This function is similar to the Wolfram Language functions Values

This function does not evaluate the values of the association, so it is possible that the result will contain unevaluated expressions (e.g., if the association contains RuleDelayed key-value pairs)

api_GlobalSymbol

Signature

api_expr api_GlobalSymbol(char *symbolName)

Description

Get a symbol expression in the Global` context

Parameters

symbolName — The base name of the symbol to get

Returns

A symbol expression in the Global` context

Error return values

api_Error(API_MISCELLANEOUS_ERROR) — An error occurred

Remarks

The base name can contain long names (e.g., \[[Alpha] and \::03b1 will become α) and non-ASCII Unicode characters as long as the resulting base name is well-formed

symbolName must be a UTF8-encoded null-terminated string

api_Head

Signature

api_expr api_Head(api_expr expression)

Description

Get the head of an expression

Parameters

expression — The expression

Returns

The head of the expression

Error return values

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

This function is similar to the Wolfram Language function Head

This function can be called on any type of expression

api_ImaginaryPart

Signature

api_expr api_ImaginaryPart(api_expr complexExpression)

Description

Get the imaginary part of a complex number expression

Parameters

complexExpression — The complex number expression

Returns

The imaginary part as a non-complex, number-type expression

Error return values

api_Error(API_UNEXPECTED_TYPE_ERROR) — The expression was not a complex number

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

It is possible that the result is a different number type than the number type you used to create the imaginary part of the complex number expression

api_Integer

Signature

api_expr api_Integer(mint value)

Description

Create a integer expression using a specific integer value

Parameters

value — The integer value to use

Returns

An integer expression

Error return values

api_Error(API_ALLOCATION_ERROR) — Failed to create an integer expression

Remarks

This function will return a machine integer expression

api_IntegerArrayData

Signature

api_err_t api_IntegerArrayData(api_expr expression, mint *resultLength, mint **resultArray)

Description

Get an array of integers from a numeric array, packed array, or list

Parameters

expression — The expression

[out] resultLength — Pointer to write the length of the array

[out] resultArray — Pointer to write the array

Returns

Whether the function succeeded

Return values

API_SUCCESS — The function succeeded

API_UNEXPECTED_TYPE — The expression was not a numeric array, packed array, or list

API_UNEXPECTED_TYPE — The expression was a numeric array or list but not rank one

API_UNEXPECTED_TYPE — The expression was a numeric array but its type was not an integer type or the integer type was too large

API_UNEXPECTED_TYPE — The expression did not contain only machine integers

API_ALLOCATION_ERROR — An allocation error occurred

API_MISCELLANEOUS_ERROR — A miscellaneous error occurred

Remarks

If the result array is not NULL, it is the responsibility of the user to release the result array using api_Release

Post-condition

If the function is not successful, the result length and array will be -1 and NULL, respectively

The result array will be the expression as an integer array

The result length will be the length of the expression as an integer array

api_IntegerData

Signature

api_err_t api_IntegerData(api_expr  expression, mint *result)

Description

Get an integer value from a number-type expression

Parameters

expression — The number-type expression

[out] result — Pointer to write the result to

Returns

Whether the function succeeded

Return values

API_SUCCESS — The function succeeded

API_UNEXPECTED_TYPE_ERROR — The expression was not a number

API_MISCELLANEOUS_ERROR — A miscellaneous error occurred

API_ALLOCATION_ERROR — An allocation error occurred

Remarks

If the expression is a complex number, we consider its real part

Post-condition

If the function is not successful, the result is -1

If the expression is a machine integer, the result is its integer value

If the expression is a big integer, the result is the integer value of the expression truncated to a machine integer

If the expression is a machine real, the result is the value of its integer part

If the expression is a big real, the result is the value of its integer part truncated to a machine integer

If the expression is a rational, the result is the value of its integer part truncated to a machine integer

api_Last

Signature

api_expr api_Last(api_expr expression)

Description

Get the last part of an expression

Parameters

expression — The expression

Returns

The last part of an expression

Error return values

api_Error(API_OUT_OF_BOUNDS_ERROR) — The expression does not contain any parts

api_Error(API_OUT_OF_BOUNDS_ERROR) — The expression was not a normal expression, array-type expression, or association

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

This function is similar to the Wolfram Language function Last

Array-type expressions are packed arrays, numeric arrays, byte arrays, sparse arrays, and symmetrized arrays

api_Length

Signature

mint api_Length(api_expr expression)

Description

Get the number of elements in an expression

Parameters

expression — The expression

Returns

The number of elements in an expression

Error return values

0 — The expression was not a normal expression, array-type expression, or association

0 — The expression is an error expression

Remarks

This function is similar to the Wolfram Language function Length

Array-type expressions are packed arrays, numeric arrays, byte arrays, sparse arrays, and symmetrized arrays

api_ListQ

Signature

mbool api_ListQ(api_expr expression)

Description

Test if an expression is a list

Parameters

expression — The expression

Returns

Whether the expression is a list

Return values

TRUE — The expression is a list

FALSE — The expression is not a list

Remarks

This function will return TRUE for packed arrays

api_MoveExpressionToParentPool

Signature

void api_MoveExpressionToParentPool(api_expr expression)

Description

Move an expression in the current expression pool to its parent expression pool

Parameters

expression — The expression to move

Pre-condition

There must be a current expression pool created using api_CreateExpressionPool that has not been released

The expression must be associated with the current expression pool, and it cannot have been detached

Post-condition

The expression has been moved to its parent expression pool (i.e., the expression pool that was previously the current expression pool)

If the expression pool has no parent, the expression will become detached, and the expression can only be released using api_ReleaseExpression or api_ReleaseAll

api_Normalize

Signature

api_expr api_Normalize(api_expr expression)

Description

Transform non-normal, non-number, non-string expressions or expression components into normal expressions

Parameters

expression — The expression to transform

Returns

The transformed expression

Return values

api_Error(API_MISCELLANEOUS_ERROR) — An error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

This function is similar to the Wolfram Language function FullForm

api_NumberFromString

Signature

api_expr api_NumberFromString(char *numberString)

Description

Create a number-type expression from a string

Parameters

numberString — The string in an acceptable input form for numbers

Returns

A number-type expression

Return values

api_Error(API_MISCELLANEOUS_ERROR) — The number string is misformatted

api_Error(API_MISCELLANEOUS_ERROR) — The number string is not in an acceptable input form for numbers

api_Error(API_MISCELLANEOUS_ERROR) — An error occurred

Remarks

The type of number the result will be (e.g., big real) depends on the provided number string

Acceptable input forms for numbers are listed at https://reference.wolfram.com/language/tutorial/InputSyntax.html#7977

numberString must be a UTF8-encoded null-terminated string

api_NumberQ

Signature

mbool api_NumberQ(api_expr expression)

Description

Test whether an expression is a number or not

Parameters

expression — The expression

Returns

Whether the expression is a number

Return values

FALSE — The expression is not a number

TRUE — The expression is a number

Remarks

If this function returns TRUE, the expression is one of the possible number types returned by api_NumberType

This function is similar to the Wolfram Language function NumberQ

api_NumberType

Signature

api_num_t api_NumberType(api_expr expression)

Description

Get the type of number an expression is

Parameters

expression — The expression

Returns

The type of number the expression is

Return values

API_MACHINE_INTEGER — The expression is a machine integer

API_BIG_INTEGER — The expression is a big integer

API_MACHINE_REAL — The expression is a machine real

API_BIG_REAL — The expression is a big real

API_COMPLEX — The expression is a complex number

API_RATIONAL — The expression is a rational

API_OVERFLOW	 — The expression is overflowed

API_UNDERFLOW — The expression is underflowed

API_NOT_A_NUMBER — The expression is not a number

api_Numerator

Signature

api_expr api_Numerator(api_expr rationalExpression)

Description

Get the numerator of a rational expression

Parameters

rationalExpression — The rational expression

Returns

The numerator as an integer expression

Error return values

api_Error(API_UNEXPECTED_TYPE_ERROR) — The expression was not a rational

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

This function can return a machine integer or big integer expression

api_NumericArrayData

Signature

api_err_T api_NumericArrayData(api_expr expression, MNumericArray *result)

Description

Get a numeric array from an expression

Parameters

expression — The expression

[out] result — Pointer to write the result to

Returns

Whether the function succeeded

Return values

API_SUCCESS — The function succeeded

API_UNEXPECTED_TYPE — The expression was not a numeric array, packed array, or rank one list

API_UNEXPECTED_TYPE — The expression contained non-number expressions or contained numbers that could not be represented in a numeric array

API_MISCELLANEOUS_ERROR — A miscellaneous error occurred

Remarks

This functions accepts numeric arrays, packed arrays, or rank one lists

If the expression is a NumericArray, the result will preserve its type

If the result is not NULL, it is the responsibility of the user to release the result using api_MNumericArray_free

Post-condition

If the function is not successful, the result is NULL

The result is the expression as a MNumericArray

api_Part

Signature

api_expr api_Part(api_expr expression, mint index)

Description

Get a part of an expression

Parameters

expression — The expression

index — The index of the part to get

Returns

A part of an expression

Error return values

api_Error(API_OUT_OF_BOUNDS_ERROR) — The expression does not contain a part with the specified index

api_Error(API_OUT_OF_BOUNDS_ERROR) — The index was greater than zero, and the expression was not a normal expression, array-type expression, or association

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

Array-type expressions are packed arrays, numeric arrays, byte arrays, sparse arrays, and symmetrized arrays

If the index is zero, this function returns the head of the expression

This function is similar to the Wolfram Language function Part

api_Rational

Signature

api_expr api_Rational(api_expr numerator, api_expr denominator)

Description

Create a rational expression using a specific numerator and denominator

Parameters

numerator — The numerator

denominator — The denominator

Returns

A rational or integer expression

Error return values

api_Error(API_UNEXPECTED_TYPE_ERROR) — An argument was not a machine or big integer

api_Error(API_MISCELLANEOUS_ERROR) — The denominator was zero

api_Error(API_ALLOCATION_ERROR) — Failed to create a rational expression

api_Error(<propogated_from_argument>) — An argument was an error expression

Remarks

This function will return an integer if the numerator is a multiple of the denominator

api_Real

Signature

api_expr api_Real(mreal value)

Description

Create a real expression with a specific real value

Parameters

value — The real value to use

Returns

A real expression

Return values

Infinity — The real value was Inf

-Infinity — The real value was -Inf

api_Error(API_MISCELLANEOUS_ERROR) — The real value was NAN

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(API_ALLOCATION_ERROR) — Failed to create a real expression

Remarks

This function will return a machine real expression, Infinity, or -Infinity

api_RealArrayData

Signature

api_err_t api_RealArrayData(api_expr expression, mint *resultLength, mreal **resultArray)

Description

Get an array of reals from an expression

Parameters

expression — The expression

[out] resultLength — Pointer to write the length of the array

[out] resultArray — Pointer to write the array

Returns

Whether the function succeeded

Return values

API_SUCCESS — The function succeeded

API_UNEXPECTED_TYPE — The expression was not a numeric array, packed array, or list

API_UNEXPECTED_TYPE — The expression was a numeric array or list but not rank one

API_UNEXPECTED_TYPE — The expression was a numeric array but its type was not a real type or the real type was too large

API_UNEXPECTED_TYPE — The expression was a list but did not contain only machine reals

API_ALLOCATION_ERROR — An allocation error occurred

API_MISCELLANEOUS_ERROR — A miscellaneous error occurred

Remarks

If the result array is not NULL, it is the responsibility of the user to release the result array using api_Release

Post-condition

If the function is not successful, the result length and array will be -1 and NULL, respectively

The result array will be the expression as a real array

The result length will be the length of the expression as a real array

api_RealPart

Signature

api_expr api_RealPart(api_expr complexExpression)

Description

Get the real part of a complex number expression

Parameters

complexExpression — The expression

Returns

The real part as a non-complex, number-type expression

Error return values

api_Error(API_UNEXPECTED_TYPE_ERROR) —  The expression was not a complex number

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

It is possible that the result is a different number type than the number type you used to create the real part of the complex number expression

api_Release

Signature

void api_Release(void *data)

Description

Release non-expression data that was allocated by an API function

Parameters

data — The allocated non-expression data

Pre-condition

A previous call to api_StringData, api_IntegerArrayData, api_RealArrayData, or api_StringFromNumber produced data

Post-condition

data has been released

api_ReleaseAll

Signature

void api_ReleaseAll(void)

Description

Release all expressions and expression pools

Post-condition

All expressions associated with expression pools are released

All expressions that are not associated with expression pools (including expressions detached from expression pools) are released

All expression pools are released

api_ReleaseExpression

Signature

void api_ReleaseExpression(api_expr detachedExpression)

Description

Release a detached expression

Parameters

detachedExpression — The detached expression to release

Pre-condition

The expression must not be associated with an expression pool

The expression must have been returned by an API function when an expression pool was not active, or the expression must have been detached from an expression pool

Post-condition

The detached expression has been released

api_ReleaseExpressionBag

Signature

void api_ReleaseExpressionBag(api_exprbag expressionBag)

Description

Release an expression bag

Parameters

expressionBag — The expression bag

Pre-condition

expressionBag is an expression bag previously created using api_ExpressionBag

Post-condition

The expression bag has been released

api_ReleaseExpressionPool

Signature

void api_ReleaseExpressionPool(void)

Description

Release the current expression pool

Pre-condition

There must be a current expression pool created using api_CreateExpressionPool that has not yet been released

Post-condition

Expressions associated with the current expression pool will be released

The current expression pool will revert to its value immediately before the released expression pool was created

api_RemoveMessageHandler

Signature

void api_RemoveMessageHandler(api_message_handler_t handlerFunction)

Description

Remove a message handler that was previously registered using api_AddMessageHandler

Parameters

handlerFunction — The handler function to remove

Post-condition

If the message handler was previously registered using api_AddMessageHandler, it has been removed

The removed handler function will no longer be called whenever a message is raised during an evaluation

The number of defined message handlers counting towards the 100 message handler limit has decreased by one

api_RemoveOutputHandler

Signature

void api_RemoveOutputHandler(api_output_handler_t handlerFunction)

Description

Remove an output handler that was previously registered using api_AddOutputHandler

Parameters

handlerFunction — The handler function to remove

Post-condition

If the output handler was previously registered using api_AddOutputHandler, it has been removed

The removed handler function will no longer be called whenever the stdout stream is written to during an evaluation

The number of defined output handlers counting towards the 100 output handler limit has decreased by one

api_Part

Signature

api_expr api_Part(api_expr expression, mint index)

Description

Get a part of an expression

Parameters

expression — The expression

index — The index of the part to get

Returns

A part of an expression

Error return values

api_Error(API_OUT_OF_BOUNDS_ERROR) — The expression does not contain a part with the specified index

api_Error(API_OUT_OF_BOUNDS_ERROR) — The index was greater than zero, and the expression was not a normal expression, array-type expression, or association

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

Array-type expressions are packed arrays, numeric arrays, byte arrays, sparse arrays, and symmetrized arrays

If the index is zero, this function returns the head of the expression

This function is similar to the Wolfram Language function Part

api_ReplacePart

Signature

api_expr api_ReplacePart(api_expr expression, mint index, api_expr newPart)

Description

Replace part of an expression

Parameters

expression — The expression

index — The index of the part to change

newPart — The new part

Returns

The changed version of the expression

Error return values

api_Error(API_OUT_OF_BOUNDS_ERROR) — The expression does not contain a part with the specified index

api_Error(API_OUT_OF_BOUNDS_ERROR) — The expression was not a normal expression, sparse array, symmetrized array, or association

api_Error(API_OUT_OF_BOUNDS_ERROR) — The index was zero and the expression was not a normal expression

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — An argument was an error expression

Remarks

This function does not support byte arrays or numeric arrays

If the index is zero and the expression is a normal expression, this function changes the head of the expression

This function returns a list when called on a symmetrized array

This function is similar to the Wolfram Language function ReplacePart

api_Rest

Signature

api_expr api_Rest(api_expr expression)

Description

Get an expression without its first part

Parameters

expression — The expression

Returns

The expression without its first part

Error return values

api_Error(API_OUT_OF_BOUNDS_ERROR) — The expression does not contain any parts

api_Error(API_OUT_OF_BOUNDS_ERROR) — The expression was not a normal expression, array-type expression, or association

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

Remarks

Array-type expressions are packed arrays, numeric arrays, byte arrays, sparse arrays, and symmetrized arrays

This function returns a list when called on a symmetrized array

This function is similar to the top-level function Rest

api_Rule

Signature

api_expr api_Rule(api_expr leftHandSide, api_expr rightHandSide)

Description

Construct a rule expression using specific left-hand and right-hand sides

Parameters

leftHandSide — The left-hand side

rightHandSide — The right-hand side

Returns

A rule expression

Error return values

api_Error(API_ALLOCATION_ERROR) — Failed to create a new rule expression

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — An argument was an error expression

api_RuleQ

Signature

mbool api_RuleQ(api_expr expression)

Description

Test if an expression is a rule

Parameters

expression — The expression

Returns

Whether the expression is a rule

Return values

TRUE — The expression is a rule

FALSE — The expression is not a rule

Remarks

An expression is a rule if it is a normal expression with head api_Symbol(“Rule”) or api_Symbol(“RuleDelayed”) that contains two elements

api_SameQ

Signature

mbool api_SameQ(api_expr firstExpression, api_expr secondExpression)

Description

Test if two expressions are the same

Parameters

firstExpression — The first expression

secondExpression — The second expression

Returns

Whether the two expressions are the same

Return values

TRUE — The expressions are the same

FALSE — The expressions are not the same

Remarks

There are some expression types for which api_SameQ(api_Eval(api_Normalize(expression)), api_Eval(api_Normalize(expression))) returns FALSE

This function is similar to the top-level function SameQ

api_StartKernel

Signature

void api_StartKernel(mint argumentCount, char **arguments, char *layoutDirectory)

Description

Start the Wolfram Language kernel

Parameters

argumentCount — The number of arguments for the kernel

arguments — The arguments for the kernel

layoutDirectory — The directory of the layout that the kernel should use

Remarks

The kernel will treat the arguments provided here exactly as if they were provided on the command line

Other API functions cannot be called until the kernel is started using this function

api_String

Signature

api_expr api_String(char *string)

Description

Get a string expression from a string

Parameters

string — The UTF8-encoded null-terminated string to use to create the string expression

Returns

The string expression

Return values

api_Error(API_MISCELLANEOUS_ERROR) — The data was not valid UTF8

api_Error(API_MISCELLANEOUS_ERROR) — An error occurred

Remarks

The null-terminated string can contain long names (e.g., \[[Alpha] and \::03b1 will become α) and non-ASCII Unicode characters

The string cannot contain embedded nulls because it must be null-terminated

Use the long name for a backslash in order to construct a literal long name (e.g., \134[Alpha] will become α)

api_StringFromData

Signature

api_expr api_StringFromData(char *utf8Data, mint utf8DataLength)

Description

Get a string expression from UTF8-encoded data

Parameters

utf8Data — The UTF8-encoded data to use to create the string expression

utf8DataLength — The length in bytes of the UTF8-encoded data

Returns

The string expression

Return values

api_Error(API_MISCELLANEOUS_ERROR) — The data was not valid UTF8

api_Error(API_MISCELLANEOUS_ERROR) — An error occurred

Remarks

The UTF8-encoded data can contain long names (e.g., \[[Alpha] and \::03b1 will become α), non-ASCII Unicode characters, and embedded nulls

Use the long name for a backslash in order to construct a literal long name (e.g., \134[Alpha] will become α)

The UTF8-encoded data does not have to be null-terminated

api_StringData

Signature

api_err_t api_StringData(api_expr expression, char **resultData, mint *resultLength)

Description

Get UTF8-encoded data from a string expression

Parameters

expression — The string expression

[out] resultData — Pointer to write the UTF8-encoded data to

[out] resultLength — Pointer to write the length in bytes of the UTF8-encoded data to

Returns

Whether the function succeeded

Return values

API_SUCCESS — The function succeeded

API_UNEXPECTED_TYPE_ERROR — The expression was not a string

API_MISCELLANEOUS_ERROR — The UTF8-encoded data contains an embedded null, but resultLength is NULL

API_ALLOCATION_ERROR — An allocation error occurred

Remarks

The result data can contain non-ASCII Unicode characters and embedded nulls

The result data will be null-terminated, even if it contains embedded nulls

Characters like \[[Rule] will become private use area code points in the result data

If the result data is not NULL, it is the responsibility of the user to release the result data using api_Release

Post-condition

If the function is not successful, the result string is NULL, and the result length is -1

The result data will be the expression as UTF-encoded data

The result length will be the length in bytes of the UTF8-encoded data

api_StringFromNumber

Signature

api_err_t api_StringFromNumber(api_expr expression, char **result)

Description

Get a string in decimal form from a number-type expression

Parameters

expression — The expression

[out] result — Pointer to write the result to

Returns

Whether the function succeeded

Return values

API_SUCCESS — The function succeeded

API_UNEXPECTED_TYPE_ERROR — The expression was not a number, was overflowed, or was underflowed

API_ALLOCATION_ERROR — An allocation error occurred

API_MISCELLANEOUS_ERROR — A miscellaneous error occurred

Remarks

If the expression is a complex number, we consider its real part

The result will be a UTF8-encoded null-terminated string

If the result is not NULL, it is the responsibility of the user to release the result using the system call api_Release

Post-condition

If the function is not successful, the result is NULL

The result is the expression's value formatted as a string in decimal form

api_Symbol

Signature

api_expr api_Symbol(char *symbolName)

Description

Get a symbol expression using a fully- or relatively- qualified symbol name

Parameters

symbolName — The symbol name

Returns

The symbol expression

Error return values

api_Error(API_MISCELLANEOUS_ERROR) — An error occurred

Remarks

This function uses the current context when getting a relatively-qualified symbol name

The symbol name can contain long names (e.g., \[[Alpha] and \::03b1 will become α) and non-ASCII Unicode characters as long as the resulting symbol name is well-formed

symbolName must be a UTF8-encoded null-terminated string

api_SymbolContext

Signature

api_expr api_SymbolContext(api_expr symbol)

Description

Get the context of a symbol expression

Parameters

symbol — The symbol expression

Returns

The context as a string expression

Error return values

api_Error(API_UNEXPECTED_TYPE_ERROR) — The expression was not a symbol

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

api_SymbolName

Signature

api_expr api_SymbolName(api_expr symbol)

Description

Get the base name of a symbol expression

Parameters

symbol — The symbol expression

Returns

The base name as a string expression

Error return values

api_Error(API_UNEXPECTED_TYPE_ERROR) — The expression was not a symbol

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — The expression was an error expression

api_SystemSymbol

Signature

api_expr api_SystemSymbol(char *symbolName)

Description

Get a symbol expression in the System` context

Parameters

symbolName — The base name of the symbol to get

Returns

A symbol expression in the System` context

Error return values

api_Error(API_MISCELLANEOUS_ERROR) — An error occurred

Remarks

The base name can contain long names (e.g., \[[Alpha] and \::03b1 will become α) and non-ASCII Unicode characters as long as the resulting base name is well-formed

symbolName must be a UTF8-encoded null-terminated string

api_TrueQ

Signature

mbool api_TrueQ(api_expr expression)

Description

Test if an expression is the symbol True

Parameters

expression — The expression

Returns

Whether the expression is the symbol True

Return values

TRUE — The expression is the symbol True

FALSE — The expression is not the symbol True

api_VariadicE

api_expr api_VariadicE(api_expr expressionHead, mint childElementNumber, ...)

Description

Construct an expression with a specific head and specific child elements

Parameters

expressionHead — The head for the new expression

childElementNumber — The number of child elements for the new expression

... — The child elements for the new expression

Returns

The new expression

Error return values

api_Error(API_ALLOCATION_ERROR) — Failed to create a new expression

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — An argument was an error expression

Remarks

The new expression will be a normal expression

This function does not evaluate the new expression

Use the api_E macro in order to avoid having to manually specify the number of child elements

api_VariadicList

api_expr api_VariadicList(mint childElementNumber, ...)

Description

Construct a list expression with specific child elements

Parameters

childElementNumber — The number of child elements for the new list expression

... — The child elements for the new list expression

Returns

The new list expression

Error return values

api_Error(API_ALLOCATION_ERROR) — Failed to create a new list expression

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — An argument was an error expression

Remarks

The new list expression will be a normal expression with head api_Symbol(“List”)

This function does not evaluate the new list expression

Use the api_List macro in order to avoid having to manually specify the number of child elements

api_VariadicAssociation

Signature

api_expr api_VariadicAssociation(mint keyValuePairnumber, ...)

Description

Construct an association expression with specific key-value pairs

Parameters

keyValuePairNumber — The number of key-value pairs for the new association expression

... — The key-value pairs for the new association expression as rule expressions

Returns

The new association expression

Error return values

api_Error(API_UNEXPECTED_TYPE_ERROR) — An argument was not a rule expression

api_Error(API_ALLOCATION_ERROR) — Failed to create a new association expression

api_Error(API_MISCELLANEOUS_ERROR) — A miscellaneous error occurred

api_Error(<propogated_from_argument>) — An argument was an error expression

Remarks

Keys and values will be not be automatically evaluated for the result

Rule expressions must be normal expressions with head api_Symbol(“Rule”) or api_Symbol(“RuleDelayed”) that contain two elements (i.e., each rule expression should satisfy RuleQ)

On success, this function returns an expression of type API_ASSOCIATION when tested using api_ExpressionType

Use the api_Association macro in order to avoid having to manually specify the number of key-value pairs

Appendix: Shape of the Expression API

Starting the kernel

api_StartKernel

Errors

api_Error

api_ErrorQ

api_ErrorType

Expressions

api_ExpressionType

api_Length

api_Part

api_First

api_Last

api_Rest

api_Head

api_ReplacePart

api_TrueQ

api_SameQ

Evaluation

api_Eval

api_EvalData

api_AddOutputHandler

api_AddMessageHandler

api_RemoveOutputHandler

api_RemoveMessageHandler

api_Abort

api_ClearAbort

Numbers

api_NumberQ

api_NumberType

Machine integers

api_Integer

api_IntegerData

Machine reals

api_Real

api_RealData

Complex numbers

api_Complex

api_RealPart

api_ImaginaryPart

Rationals

api_Rational

api_Numerator

api_Denominator

Big numbers

api_NumberFromString

api_StringFromNumber

Normal expressions

api_Normalize

api_E

api_List

api_ListQ

api_Rule

api_RuleQ

Expression bags

api_ExpressionBag

api_AddExpression

api_ExpressionBagLength

api_ExpressionBagToExpression

api_ReleaseExpressionBag

Symbols

api_Symbol

api_GlobalSymbol

api_SystemSymbol

api_ContextSymbol

api_SymbolName

api_SymbolContext

Strings

api_String

api_StringFromData

api_StringData

Associations

api_Association

api_AssociationQ

api_GetValueFromKey

api_GetKeys

api_GetValues

Arrays

api_ExpressionFromNumericArray

api_ExpressionFromIntegerArray

api_ExpressionFromRealArray

api_NumericArrayData

api_IntegerArrayData

api_RealArrayData

Memory management

api_CreateExpressionPool

api_ReleaseExpressionPool

api_ReleaseExpression

api_MoveExpressionToParentPool

api_DetachExpression

api_ReleaseAll

api_Clone

api_Release