Wolfram Language Runtime

The Wolfram Language Runtime is the component that makes Wolfram functionality available to your application. The runtime is a library that the application will link against. This library is the core component of the Wolfram system, and it is the same core component that is used when you evaluate an expression in a Wolfram notebook. The interface discussed in this document makes it possible to access the runtime directly. Note that there is no interprocess communication cost with this interface (unlike most usages of WSTP). As a result, the SDK offers a highspeed interface to the Wolfram Language.

In order to access the runtime directly, an application will be compiled against a static library called the standalone applications SDK. That is, developers just have to use the SDK instead of having to compile against the runtime dynamic library. The SDK automatically handles loading the runtime dynamic library and its dependencies. The SDK is prepackaged in the Wolfram Language layout under SystemFiles/Components/StandaloneApplicationsSDK.

The SDK (and runtime dynamic library) make available a C function interface that allows developers to have the Wolfram Language kernel running in their applications’ process. These functions enable developers to build, evaluate, and deconstruct Wolfram Language expressions within their applications. For this reason, another name for this interface is the expression API.

Individual documentation for expression API functions are available here. Information regarding general principles of the interface are available here here.

Reference Information

Macros

WLR_START_RUNTIME(licenseType, layoutDirectory, configuration)

This macro is an abbreviated form of wlr_StartRuntime. The header you include contains the version of the expression API you are using, so you don’t have to include that parameter when you use this macro instead of wlr_StartRuntime directly.

RUNTIME_NOT_STARTED

An error code that will be returned by the wlr_MNumericArray_* functions if the runtime has not been started

wlr_E(...)

See wlr_VariadicE

wlr_List(...)

See wlr_VariadicList

wlr_Association(...)

See wlr_VariadicAssociation

Types

enum wlr_num_t

The different types of number expressions in the expression API

Remark

”Number expressions” are those expressions for which wlr_ExpressionType returns WLR_NUMBER

Remark

The function wlr_NumberType returns a value of this type

Values:

enumerator WLR_MACHINE_INTEGER
enumerator WLR_BIG_INTEGER
enumerator WLR_MACHINE_REAL
enumerator WLR_BIG_REAL
enumerator WLR_COMPLEX
enumerator WLR_RATIONAL
enumerator WLR_OVERFLOW
enumerator WLR_UNDERFLOW
enumerator WLR_NOT_A_NUMBER
enum wlr_expr_t

The different types of expressions in the expression API

Remark

The function wlr_ExpressionType returns a value of this type

Values:

enumerator WLR_NUMBER
enumerator WLR_STRING
enumerator WLR_SYMBOL
enumerator WLR_NORMAL
enumerator WLR_ERROR
enumerator WLR_PACKED_ARRAY
enumerator WLR_NUMERIC_ARRAY
enumerator WLR_BOOLEAN_FUNCTION
enumerator WLR_GRAPH
enumerator WLR_ASSOCIATION
enumerator WLR_DISPATCH
enumerator WLR_REGION
enumerator WLR_OTHER
enum wlr_err_t

The different types of errors in the expression API

Remark

Some expression API functions return a value of this type to indicate their status

Remark

There is a sub-type of expression in the expression API called an “error expression.” An error expression is returned when an error occurs during the execution of an expression API function that returns an expression. Every error expression corresponds to a single error type.

Remark

The function wlr_ErrorType returns the error type of an error expression

Values:

enumerator WLR_SUCCESS
enumerator WLR_ALLOCATION_ERROR
enumerator WLR_UNEXPECTED_TYPE
enumerator WLR_ERROR_EXPRESSION
enumerator WLR_MISCELLANEOUS_ERROR
enumerator WLR_OUT_OF_BOUNDS
enumerator WLR_SIGNING_ERROR
enumerator WLR_UNSAFE_EXPRESSION
enumerator WLR_MALFORMED
enumerator WLR_RUNTIME_NOT_STARTED
enum wlr_license_t

Whether the runtime should prefer consuming a license, if possible, to using code signing

Remark

The function wlr_StartRuntime takes an argument of this type. See that function for more information on how this type is used.

Values:

enumerator WLR_SIGNED_CODE_MODE
enumerator WLR_LICENSE_OR_SIGNED_CODE_MODE
enum wlr_version_t

Different expression API versions

Remark

The function wlr_StartRuntime takes an argument of this type. See that function for more information on how this type is used.

Values:

enumerator WLR_VERSION_1
enum wlr_containment_t

Whether the runtime should be started in a “contained” mode or not

Remark

A member of this type is present in the wlr_runtime_conf struct, which is one of the arguments to the function wlr_StartRuntime. See that function for more information on how this type is used.

Values:

enumerator WLR_CONTAINED
enumerator WLR_UNCONTAINED
typedef void *wlr_expr

Type of an expression in the expression API

typedef void *wlr_exprbag

Type of an expression bag in the expression API

Remark

See the function wlr_ExpressionBag for more information

typedef void (*wlr_stdout_handler_t)(char*, mint, void*)

Type of a stdout handler function pointer

Remark

See the function wlr_AddStdoutHandler for more information

typedef void (*wlr_message_handler_t)(wlr_expr, wlr_expr, wlr_expr, void*)

Type of a message handler function pointer

Remark

See the function wlr_AddMessageHandler for more information

struct wlr_runtime_conf
#include <apidefinition.h>

Various aspects of how a runtime can be configured

Remark

The function wlr_StartRuntime takes an argument of this type. See that function for more information on how this type is used.

Public Members

mint argumentCount
char **arguments
wlr_containment_t containmentSetting

Starting and stopping the runtime

void wlr_InitializeRuntimeConfiguration(wlr_runtime_conf *configuration)

Initialize a runtime configuration

Remark

Runtime configurations can be optionally passed to wlr_StartRuntime to specify more details about how the runtime should be started up. Before this can be done, the configuration MUST be initialized using this function.

Remark

The runtime configuration can be used to specify the command line of the runtime kernel. The wlr_runtime_conf::argumentCount member can be set to the number of arguments, and the wlr_runtime_conf::arguments member can be set to the array of arguments.

Remark

The runtime configuration can be used to limit the resources the runtime will access outside of the layout. If the wlr_runtime_conf::containmentSetting member is set to WLR_CONTAINED, the runtime will only use paclets inside the layout (e.g., it will ignore more recent paclets that exist in $UserBaseDirectory). In addition, the runtime will ignore initialization files in $BaseDirectory and $UserBaseDirectory.

Parameters:

configuration – Pointer to the configuration to initialize

Post:

The wlr_runtime_conf::argumentCount member has been set to 0

Post:

The wlr_runtime_conf::arguments member has been set to NULL

Post:

The wlr_runtime_conf::containmentSetting member has been set to WLR_CONTAINED

wlr_err_t wlr_StartRuntime(wlr_version_t version, wlr_license_t licenseType, char *layoutDirectory, wlr_runtime_conf *configuration)

Start the Wolfram Language runtime

Remark

The only currently supported API version for version is WLR_VERSION_1

Remark

If licenseType is WLR_SIGNED_CODE_MODE, the runtime will be in signed code mode and a license will not be consumed

Remark

If licenseType is WLR_LICENSE_OR_SIGNED_CODE_MODE, the runtime can use a license, and if one is found, the runtime will not be in signed code mode (so there will be no code signing restrictions)

Remark

A runtime configuration can be optionally passed to wlr_StartRuntime to specify more details about how the runtime should be started up. If configuration is NULL, this function will use the default configuration settings set by wlr_InitializeRuntimeConfiguration. If configuration is not NULL, the configuration MUST be initialized using wlr_InitializeRuntimeConfiguration before calling this function. After initializing the configuration, its properties can be set as desired.

Remark

The runtime configuration can be used to specify the command line of the runtime kernel. The wlr_runtime_conf::argumentCount member can be set to the number of arguments, and the arguments member can be set to the array of arguments. The kernel will treat these arguments exactly as if they were provided on the actual command line.

Remark

The runtime configuration can be used to limit the resources the runtime will access outside of the layout. If the wlr_runtime_conf::containmentSetting member is set to WLR_CONTAINED, the runtime will only use paclets inside the layout (e.g., it will ignore more recent paclets that exist in $UserBaseDirectory). In addition, the runtime will ignore initialization files in $BaseDirectory and $UserBaseDirectory.

Remark

Note that this function will fail if the runtime is started in signed code mode but layoutDirectory does not exist or is otherwise invalid

Remark

In signed code mode, all layout files are “pre-signed.” You do not have to manually register signatures for them. This also true of “basic symbols.” Basic symbols are a set of System` symbols developers can use without having to sign them.

Remark

In signed code mode, $InstallationDirectory/SystemFiles/Kernel/SystemResources/Signatures/layoutsignatures.txt and any code signature files in the current directory will be loaded

Remark

Other API functions should not be called until the runtime is successfully started using this function

Parameters:
  • version – The version of the API to use

  • licenseType – Whether to consume a license

  • layoutDirectory – The directory of the layout that the runtime should use

  • configuration – The runtime configuration to use

Return values:
  • WLR_SUCCESS – The runtime started up successfully

  • WLR_SUCCESS – The runtime has already started up successfully in a previous call to wlr_StartRuntime

  • WLR_RUNTIME_NOT_STARTED – The provided value for version is not supported

  • WLR_RUNTIME_NOT_STARTED – The provided value for layoutDirectory was an empty string

  • WLR_RUNTIME_NOT_STARTED – The runtime has been closed using wlr_CloseRuntime. It cannot be restarted.

  • WLR_RUNTIME_NOT_STARTED – The expression API is not supported on your platform

Returns:

Whether the runtime started up successfully

Pre:

If configuration is not NULL, it must have been initialized using wlr_InitializeRuntimeConfiguration

void wlr_CloseRuntime(void)

Close the runtime

Post:

The runtime has been closed

Post:

Any future attempts to restart the runtime using wlr_StartRuntime will fail

Handling error expressions

wlr_expr wlr_Error(wlr_err_t errorType)

Create an error expression using a specific error type

Remark

The internal structure of error expressions cannot be accessed using the expression API

Parameters:

errorType – The error type

Return values:
  • wlr_Error(WLR_MALFORMED)errorType was not a valid error type

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

An error expression

mbool wlr_ErrorQ(wlr_expr expression)

Check whether an expression is an error expression

Remark

The internal structure of error expressions cannot be accessed using the expression API

Parameters:

expression – The expression

Return values:
  • TRUE – The expression is an error expression

  • FALSE – The expression is not a well-formed error expression

  • FALSE – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the expression is an error expression

wlr_err_t wlr_ErrorType(wlr_expr errorExpression)

Get the type of an error expression

Remark

The documentation for the expression API function that initially returned the error expression will explain why any given error type was returned

Remark

wlr_Error(WLR_UNSAFE_EXPRESSION) can be returned by API functions if an internal error occurs or if NULL is passed as an expression

Parameters:

errorExpression – The expression

Return values:
  • WLR_ALLOCATION_ERROR – The expression is wlr_Error(WLR_ALLOCATION_ERROR)

  • WLR_UNEXPECTED_TYPE – The expression is wlr_Error(WLR_UNEXPECTED_TYPE)

  • WLR_ERROR_EXPRESSION – The expression is wlr_Error(WLR_ERROR_EXPRESSION)

  • WLR_MISCELLANEOUS_ERROR – The expression is wlr_Error(WLR_MISCELLANEOUS_ERROR)

  • WLR_OUT_OF_BOUNDS – The expression is wlr_Error(WLR_OUT_OF_BOUNDS)

  • WLR_MALFORMED – The expression is wlr_Error(WLR_MALFORMED)

  • WLR_UNSAFE_EXPRESSION – The expression is wlr_Error(WLR_UNSAFE_EXPRESSION)

  • WLR_SUCCESS – The expression is wlr_Error(WLR_SUCCESS)

  • WLR_MALFORMED – The expression is not a well-formed error expression

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

The type of the error expression

Managing memory

void wlr_CreateExpressionPool(void)

Create a new expression pool

Remark

This function will do nothing if the runtime has not been started using wlr_StartRuntime

Remark

This function is useful for grouping new expressions so that they can be released as a block

Remark

Expression pools can be nested. In other words, you can call this function repeatedly without releasing previously created pools.

Post:

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

Post:

The new expression pool will become the current pool

Post:

Old expression pools will only be restored when wlr_ReleaseExpressionPool is called

void wlr_ReleaseExpressionPool(void)

Release the current expression pool and its expressions

Remark

This function will do nothing if the runtime has not been started using wlr_StartRuntime

Pre:

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

Post:

Expressions associated with the current expression pool will be released

Post:

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

void wlr_ReleaseExpression(wlr_expr detachedExpression)

Release a detached expression

Remark

Detached expressions are expressions not associated with an expression pool. Such expressions fall into three categories:

  • Expressions returned by API functions when no expression pools are active

  • Expressions detached from an expression pool using wlr_DetachExpression

  • Expressions returned by API functions when only one expression pool is active that were moved using wlr_MoveExpressionToParentPool

Remark

This function will do nothing if the runtime has not been started using wlr_StartRuntime

Parameters:

detachedExpression – The detached expression to release

Pre:

detachedExpression must not be associated with an expression pool

Post:

detachedExpression has been released

void wlr_MoveExpressionToParentPool(wlr_expr expression)

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

Remark

This function will do nothing if the runtime has not been started using wlr_StartRuntime

Parameters:

expression – The expression to move

Pre:

expression must be an expression associated with the current expression pool

Post:

expression has been moved to its parent expression pool

Post:

expression will become detached if it has no parent expression pool. Detached expressions can only be released using wlr_ReleaseExpression or wlr_ReleaseAll.

void wlr_DetachExpression(wlr_expr expression)

Detach an expression in the current expression pool

Remark

This function will do nothing if the runtime has not been started using wlr_StartRuntime

Parameters:

expression – The expression to detach

Pre:

expression must be an expression associated with the current expression pool

Post:

expression is detached. It can only be released using wlr_ReleaseExpression or wlr_ReleaseAll.

wlr_expr wlr_Clone(wlr_expr expression)

Get a copy of an expression

Remark

This function can be used to get a safe copy of an expression whose memory you do not manage.

For example, message handlers are passed various expressions representing the raised message. However, these expressions will be released after the message is handled. This function can be used to get a copy of one of these expressions that will outlive the message handlers.

Remark

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

Parameters:

expression – The expression to clone

Return values:

NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The cloned expression

void wlr_ReleaseAll(void)

Release all expressions and expression pools

Remark

This function will do nothing if the runtime has not been started using wlr_StartRuntime

Post:

All expressions associated with expression pools are released

Post:

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

Post:

All expression pools are released

void wlr_Release(void *data)

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

Remark

This function should not be used to release MNumericArray structures (e.g., as returned by wlr_NumericArrayData). The correct function to release these is wlr_MNumericArray_free.

Remark

This function will do nothing if the runtime has not been started using wlr_StartRuntime

Parameters:

data – The allocated non-expression data

Pre:

A previous call to wlr_StringData, wlr_IntegerArrayData, wlr_RealArrayData, or wlr_StringFromNumber produced data

Post:

data has been released

Evaluating expressions

wlr_err_t wlr_AddStdoutHandler(wlr_stdout_handler_t handlerFunction, void *contextData)

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

Remark

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. The output string will be released after the output is handled.

Remark

The signature for the handler function is expected to be wlr_stdout_handler_t

Remark

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

Remark

By default, no stdout handlers are registered, and output to stdout will be suppressed. Add wlr_DefaultStdoutHandler as a handler function in order to allow output to stdout.

Parameters:
  • handlerFunction – The handler function

  • contextData – Context data to be passed to the handler function

Return values:
  • WLR_SUCCESS – The handler function and context data have been successfully added

  • WLR_MISCELLANEOUS_ERROR – The maximum number (100) of stdout handlers have already been added

  • WLR_MISCELLANEOUS_ERROR – A miscellaneous error occurred

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the handler function and context data have been successfully added

void wlr_DefaultStdoutHandler(char*, mint, void*)
void wlr_RemoveStdoutHandler(wlr_stdout_handler_t handlerFunction)

Remove a stdout handler that was previously registered using wlr_AddStdoutHandler

Remark

This function will do nothing if the runtime has not been started using wlr_StartRuntime

Parameters:

handlerFunction – The handler function to remove

Post:

The stdout handler has been removed

wlr_err_t wlr_AddMessageHandler(wlr_message_handler_t handlerFunction, void *contextData)

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

Remark

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

Remark

The signature for the handler function is expected to be wlr_message_handler_t

Remark

The expression arguments to the handler function will be automatically released when the function returns. Use wlr_Clone to get a copy of an expression argument (i.e., a copy that will not be released when the function returns).

Remark

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

Remark

By default, no message or stdout handlers are registered, and any output will be suppressed. Add wlr_DefaultMessageHandler as a handler function in order to allow messages to produce output. This will cause stdout handlers to be called when a message is raised. Add wlr_DefaultStdoutHandler using wlr_AddStdoutHandler to allow this output to go to stdout.

Remark

The handler function will not be called on quieted or suppressed messages

Parameters:
  • handlerFunction – The handler function

  • contextData – Context data to be passed to the handler function

Return values:
  • WLR_SUCCESS – The handler function and context data have been successfully added

  • WLR_MISCELLANEOUS_ERROR – The maximum number (100) of message handlers have already been added

  • WLR_MISCELLANEOUS_ERROR – A miscellaneous error occurred

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the handler function and context data have been successfully added

void wlr_DefaultMessageHandler(wlr_expr, wlr_expr, wlr_expr, void*)
void wlr_RemoveMessageHandler(wlr_message_handler_t handlerFunction)

Remove a message handler that was previously registered using wlr_AddMessageHandler

Remark

This function will do nothing if the runtime has not been started using wlr_StartRuntime

Parameters:

handlerFunction – The handler function to remove

Post:

The message handler has been removed

void wlr_Abort(void)

Attempt to abort any ongoing or future evaluation

Remark

Call wlr_ClearAbort to clear the abort state and allow evaluations to proceed

Remark

This function affects the evaluation functions wlr_Eval, wlr_EvalData, wlr_EvalString, and wlr_Get

Remark

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

Remark

This function can be called from a signal handler. It can also be called from any thread.

Remark

This function will do nothing if the runtime has not been started using wlr_StartRuntime

Post:

Evaluations will be aborted until wlr_ClearAbort is called

void wlr_ClearAbort(void)

Allow evaluations to proceed by cancelling any previous calls to wlr_Abort

Remark

This function affects the evaluation functions wlr_Eval, wlr_EvalData, wlr_EvalString, and wlr_Get

Remark

If wlr_Abort has been called, any evaluation started before the call to wlr_ClearAbort may still abort

Remark

This function can be called from a signal handler. It can also be called from any thread.

Remark

This function will do nothing if the runtime has not been started using wlr_StartRuntime

Pre:

This function does not require wlr_Abort to have been previously called

Post:

Future evaluations will be able to proceed

wlr_expr wlr_Eval(wlr_expr expression)

Evaluate an expression

Remark

$MessageList is cleared before the file is evaluated. A General::stop message can occur if a message is generated too many times.

Parameters:

expression – The expression

Return values:
  • wlr_Error(WLR_SIGNING_ERROR) – In a signed application, expression contained an unapproved symbol

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The evaluated form of the expression

wlr_expr wlr_EvalString(wlr_expr inputStringExpression)

Parse and evaluate a string of Wolfram Language formatted in InputForm

Remark

If inputStringExpression represents multiple expressions, this function returns a list containing the evaluated form of each expression

Remark

Any output or messages generated during the parse will be suppressed. $MessageList is cleared before the file is evaluated. A General::stop message can occur if a message is generated too many times.

Parameters:

inputStringExpression – The Wolfram Language string

Return values:
  • wlr_Error(WLR_SIGNING_ERROR) – In a signed application, the parsed form of inputStringExpression (before evaluation) contained a symbol that is not approved

  • wlr_Error(WLR_UNEXPECTED_TYPE)inputStringExpression was not a string

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The evaluated form of the expression represented by inputStringExpression

wlr_expr wlr_EvalData(wlr_expr expression)

Evaluate an expression, and return relevant evaluation data

Remark

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 to the stdout stream 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. Output generated from a message will be present in "MessagesText" and not in "OutputLog".

  • 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.

Remark

Stdout and message handlers will still run during the evaluation. Data regarding evaluations that occur in these handlers will not be included in the result.

Remark

Quieted or suppressed messages will not be collected in the evaluation data. $MessageList is cleared before the file is evaluated. A General::stop message can occur if a message is generated too many times.

Parameters:

expression – The expression

Return values:
  • wlr_Error(WLR_SIGNING_ERROR) – In a signed application, expression contained an unapproved symbol

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • wlr_Error(WLR_ALLOCATION_ERROR) – An allocation error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

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

wlr_expr wlr_Get(char *fileName)

Evaluate a Wolfram Language or MX file

Remark

fileName must be a UTF8-encoded null-terminated string. The string cannot contain embedded nulls.

Remark

This function can return the expression $Failed if the evaluated file literally returns $Failed or if an error occurs (e.g., the file does not exit)

Remark

This function can generate output and messages, including output and messages generated during the parse stage (e.g., a syntax error message)

Remark

This function will not raise a message if wlr_Error(WLR_SIGNING_ERROR) is returned. However, a signing violation message can be raised if the loaded file attempts to load another file using a Wolfram Language function like Get, and a signing violation occurs.

Remark

$MessageList is cleared before the file is evaluated. A General::stop message can occur if a message is generated too many times.

Parameters:

fileName – The path of the file to evaluate

Return values:
  • wlr_Error(WLR_SIGNING_ERROR) – In a signed application, fileName is a Wolfram Language source file, but the file is not approved and contained unapproved symbols

  • wlr_Error(WLR_SIGNING_ERROR) – In a signed application, fileName is a MX file, but the file is not approved

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The evaluated form of the last expression in the file or wlr_Symbol("Null") if the file is an MX file

Creating and interacting with expressions

mbool wlr_NumberQ(wlr_expr expression)

Test whether an expression is a number or not

Remark

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

Remark

This function is similar to the Wolfram Language function NumberQ

Parameters:

expression – The expression

Return values:
  • TRUEexpression is a number

  • FALSEexpression is not a number

  • FALSE – The runtime has not been started using wlr_StartRuntime

wlr_num_t wlr_NumberType(wlr_expr numberExpression)

Get the type of number an expression is

Parameters:

numberExpression – The expression

Return values:
  • WLR_MACHINE_INTEGERnumberExpression is a machine integer

  • WLR_BIG_INTEGERnumberExpression is a big integer

  • WLR_MACHINE_REALnumberExpression is a machine real

  • WLR_BIG_REALnumberExpression is a big real

  • WLR_COMPLEXnumberExpression is a complex number

  • WLR_RATIONALnumberExpression is a rational

  • WLR_OVERFLOWnumberExpression is overflowed

  • WLR_UNDERFLOWnumberExpression is underflowed

  • WLR_NOT_A_NUMBERnumberExpression is not a number

  • WLR_NOT_A_NUMBER – The runtime has not been started using wlr_StartRuntime

Returns:

The type of number the expression is

wlr_expr wlr_Integer(mint value)

Create an integer expression using a specific integer value

Remark

This function will return a machine integer expression

Parameters:

value – The integer value to use

Return values:
  • wlr_Error(WLR_ALLOCATION_ERROR) – Failed to create an integer expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

An integer expression

wlr_err_t wlr_IntegerConvert(wlr_expr numberExpression, mint *result)

Get an integer value from a number-type expression

Remark

If numberExpression is a complex number, we consider its real part

Parameters:
  • numberExpression – The number-type expression

  • result[out] Pointer to write the result to

Return values:
  • WLR_SUCCESS – The function succeeded

  • WLR_UNEXPECTED_TYPE – The expression numberExpression was not a number or error expression

  • WLR_ERROR_EXPRESSION – The expression numberExpression was an error expression

  • WLR_MISCELLANEOUS_ERROR – A miscellaneous error occurred

  • WLR_ALLOCATION_ERROR – An allocation error occurred

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the function succeeded

Post:

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

Post:

The result depends on the type of number numberExpression is:

  • If numberExpression is a machine integer, the result is its integer value

  • If numberExpression is a big integer, the result is its value truncated to a machine integer

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

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

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

wlr_expr wlr_Real(mreal value)

Create a real expression with a specific real value

Remark

This function will return a machine real expression, DirectedInfinity[1], or DirectedInfinity[-1]

Parameters:

value – The real value to use

Return values:
  • DirectedInfinity[1] – The real value was Inf

  • DirectedInfinity[-1] – The real value was -Inf

  • wlr_Error(WLR_ALLOCATION_ERROR) – Failed to create a real expression

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – The real value was NAN

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

A real expression

wlr_err_t wlr_RealConvert(wlr_expr numberExpression, mreal *result)

Get a real value from a number-type expression

Remark

If numberExpression is a complex number, we consider its real part

Parameters:
  • numberExpression – The number-type expression or the expressions DirectedInfinity[1] or DirectedInfinity[-1]

  • result[out] Pointer to write the result to

Return values:
  • WLR_SUCCESS – The function succeeded

  • WLR_UNEXPECTED_TYPE – The expression numberExpression was not a number or error expression

  • WLR_ERROR_EXPRESSION – The expression numberExpression was an error expression

  • WLR_MISCELLANEOUS_ERROR – A miscellaneous error occurred

  • WLR_ALLOCATION_ERROR – An allocation error occurred

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the function succeeded

Post:

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

Post:

The result depends on the type of number numberExpression is:

  • If numberExpression is a machine integer, the result is its integer value cast to a machine real

  • If numberExpression is a big integer, the result is its value rounded to the nearest machine real

  • If numberExpression is a machine real, the result is its real value

  • If numberExpression is a big real, the result is its value rounded to the nearest machine real

  • If numberExpression is a rational, the result is its value rounded to the nearest machine real

  • If numberExpression is DirectedInfinity[1], the result is the real value Inf

  • If numberExpression is DirectedInfinity[-1], the result is the real value -Inf

wlr_expr wlr_Complex(wlr_expr realPart, wlr_expr imaginaryPart)

Create a complex number expression using specific real and imaginary parts

Parameters:
  • realPart – The real part

  • imaginaryPart – The imaginary part

Return values:
  • wlr_Error(WLR_UNEXPECTED_TYPE) – An argument was not a number or was a complex number

  • wlr_Error(WLR_ALLOCATION_ERROR) – Failed to create a complex number expression

  • wlr_Error(<propogated_from_argument>) – An argument was an error expressions

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

A complex number expression

wlr_expr wlr_RealPart(wlr_expr complexExpression)

Get the real part of a complex number expression

Parameters:

complexExpression – The complex number expression

Return values:
  • wlr_Error(WLR_UNEXPECTED_TYPE) – The expression complexExpression was not a complex number

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The real part

wlr_expr wlr_ImaginaryPart(wlr_expr complexExpression)

Get the imaginary part of a complex number expression

Parameters:

complexExpression – The complex number expression

Return values:
  • wlr_Error(WLR_UNEXPECTED_TYPE) – The expression complexExpression was not a complex number

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The imaginary part

wlr_expr wlr_Rational(wlr_expr numerator, wlr_expr denominator)

Create a rational expression using a specific numerator and denominator

Remark

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

Parameters:
  • numerator – The numerator

  • denominator – The denominator

Return values:
  • wlr_Error(WLR_UNEXPECTED_TYPE) – An argument was not a machine or big integer expression

  • wlr_Error(WLR_MISCELLANEOUS_ERROR)denominator was the expression zero

  • wlr_Error(WLR_ALLOCATION_ERROR) – Failed to create a rational expression

  • wlr_Error(<propogated_from_argument>) – An argument was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

A rational or integer expression

wlr_expr wlr_Numerator(wlr_expr rationalExpression)

Get the numerator of a rational expression

Remark

On success, this function can return a machine integer or big integer expression

Remark

If rationalExpression is an integer, this function will return rationalExpression

Parameters:

rationalExpression – The rational expression

Return values:
  • wlr_Error(WLR_UNEXPECTED_TYPE) – The expression rationalExpression was not a rational or integer

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The numerator as an integer expression

wlr_expr wlr_Denominator(wlr_expr rationalExpression)

Get the denominator of a rational expression

Remark

On success, this function can return a machine integer or big integer expression

Remark

If rationalExpression is an integer, this function will return 1

Parameters:

rationalExpression – The rational expression

Return values:
  • wlr_Error(WLR_UNEXPECTED_TYPE) – The expression was not a rational or integer

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The denominator as an integer expression

wlr_expr wlr_NumberFromString(char *numberString)

Create a number-type expression from a string

Remark

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

Remark

numberString must be a UTF8-encoded null-terminated string. The string cannot contain embedded nulls.

Parameters:

numberString – The string in an acceptable input form for numbers

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – The number string is misformatted

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – The number string is not in an acceptable input form for numbers

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

If the string is an integer string, a machine integer or big integer expression

Returns:

If the string is a real string, a machine real or big real expression

wlr_err_t wlr_StringFromNumber(wlr_expr numberExpression, char **result)

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

Remark

If the function is successful, the result will be a UTF8-encoded null-terminated string. It is the responsibility of the user to release the result using wlr_Release.

Remark

If the function is not successful, the result will be NULL

Remark

If numberExpression is a complex number, we take the value of its real part

Parameters:
  • numberExpression – The number-type expression

  • result[out] Pointer to write the result to

Return values:
  • WLR_SUCCESS – The function succeeded

  • WLR_UNEXPECTED_TYPE – The expression was not a number or error expression, was overflowed, or was underflowed

  • WLR_ERROR_EXPRESSIONnumberExpression was an error expression

  • WLR_ALLOCATION_ERROR – An allocation error occurred

  • WLR_MISCELLANEOUS_ERROR – A miscellaneous error occurred

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the function succeeded

wlr_expr wlr_Rule(wlr_expr leftHandSide, wlr_expr rightHandSide)

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

Remark

This function returns a normal expression with head wlr_Symbol("Rule") containing leftHandSide and rightHandSide as its elements

Parameters:
  • leftHandSide – The left-hand side

  • rightHandSide – The right-hand side

Return values:
  • wlr_Error(WLR_ALLOCATION_ERROR) – Failed to create a new rule expression

  • wlr_Error(<propogated_from_argument>) – An argument was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

A rule expression

mbool wlr_RuleQ(wlr_expr expression)

Test if an expression is a rule

Remark

An expression is a rule if it is a normal expression with head wlr_Symbol("Rule") or wlr_Symbol("RuleDelayed") that contains two elements

Parameters:

expression – The expression

Return values:
  • TRUE – The expression is a rule

  • FALSE – The expression is not a rule

  • FALSE – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the expression is a rule

mbool wlr_ListQ(wlr_expr expression)

Test if an expression is a list

Remark

This function will return TRUE for packed arrays as well as normal list expressions

Parameters:

expression – The expression

Return values:
  • TRUE – The expression is a list

  • FALSE – The expression is not a list

  • FALSE – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the expression is a list

mbool wlr_AssociationQ(wlr_expr expression)

Test if an expression is an association

Remark

This function will return FALSE for normalized associations

Parameters:

expression – The expression

Return values:
  • TRUE – The expression is an association

  • FALSE – The expression is not an association

  • FALSE – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the expression is an association

mint wlr_Length(wlr_expr expression)

Get the number of elements in an expression

Remark

This function is similar to the Wolfram Language function Length

Remark

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

Parameters:

expression – The expression

Return values:
  • 0 – The expression was not a normal expression, array-type expression, or association

  • 0 – The expression is an error expression

  • -1 – The runtime has not been started using wlr_StartRuntime

Returns:

The number of elements in an expression

wlr_expr wlr_Part(wlr_expr expression, mint index)

Get a part of an expression

Remark

This function is similar to the Wolfram Language function Part

Remark

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

Remark

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

Parameters:
  • expression – The expression

  • index – The index of the part to get

Return values:
  • wlr_Error(WLR_OUT_OF_BOUNDS) – The expression does not contain a part with the specified index

  • wlr_Error(WLR_OUT_OF_BOUNDS) – The index was greater than zero, and the expression was not a normal expression, array-type expression, or association

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

A part of an expression

wlr_expr wlr_First(wlr_expr expression)

Get the first part of an expression

Remark

This function is similar to the Wolfram Language function First

Remark

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

Parameters:

expression – The expression

Return values:
  • wlr_Error(WLR_OUT_OF_BOUNDS) – The expression does not contain any parts

  • wlr_Error(WLR_OUT_OF_BOUNDS) – The expression is not a normal expression, array-type expression, or association

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The first part of an expression

wlr_expr wlr_Last(wlr_expr expression)

Get the last part of an expression

Remark

This function is similar to the Wolfram Language function Last

Remark

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

Parameters:

expression – The expression

Return values:
  • wlr_Error(WLR_OUT_OF_BOUNDS) – The expression does not contain any parts

  • wlr_Error(WLR_OUT_OF_BOUNDS) – The expression was not a normal expression, array-type expression, or association

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The last part of an expression

wlr_expr wlr_Rest(wlr_expr expression)

Get an expression without its first part

Remark

This function is similar to the Wolfram Language function Rest

Remark

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

Parameters:

expression – The expression

Return values:
  • wlr_Error(WLR_OUT_OF_BOUNDS) – The expression does not contain any parts

  • wlr_Error(WLR_OUT_OF_BOUNDS) – The expression was not a normal expression, array-type expression, or association

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The expression without its first part

wlr_expr wlr_Head(wlr_expr expression)

Get the head of an expression

Remark

This function is similar to the Wolfram Language function Head

Remark

This function can be called on any type of expression

Parameters:

expression – The expression

Return values:
  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The head of the expression

wlr_expr wlr_ReplacePart(wlr_expr expression, mint index, wlr_expr newPart)

Replace part of an expression

Remark

This function is similar to the Wolfram Language function ReplacePart

Remark

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

Remark

This function does not support byte arrays or numeric arrays

Parameters:
  • expression – The expression

  • index – The index of the part to change

  • newPart – The new part

Return values:
  • wlr_Error(WLR_OUT_OF_BOUNDS) – The expression does not contain a part with the specified index

  • wlr_Error(WLR_OUT_OF_BOUNDS) – The expression was not a normal expression, sparse array, symmetrized array, or association

  • wlr_Error(WLR_OUT_OF_BOUNDS) – The index was zero and the expression was not a normal expression

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – An argument was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The changed version of the expression

wlr_expr wlr_Symbol(char *symbolName)

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

Remark

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

Remark

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

Remark

symbolName must be a UTF8-encoded null-terminated string. The string cannot contain embedded nulls.

Parameters:

symbolName – The symbol name

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR)symbolName was not a valid symbol name

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The symbol expression

wlr_expr wlr_GlobalSymbol(char *baseSymbolName)

Get a symbol expression in the Global` context

Remark

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

Remark

baseSymbolName must be a UTF8-encoded null-terminated string. The string cannot contain embedded nulls.

Parameters:

baseSymbolName – The base name of the symbol

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR)baseSymbolName was not a valid base symbol name

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The symbol expression

wlr_expr wlr_SystemSymbol(char *baseSymbolName)

Get a symbol expression in the System` context

Remark

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

Remark

baseSymbolName must be a UTF8-encoded null-terminated string. The string cannot contain embedded nulls.

Parameters:

baseSymbolName – The base name of the symbol to get

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR)baseSymbolName was not a valid base symbol name

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The symbol expression

wlr_expr wlr_ContextSymbol(char *symbolContext, char *baseSymbolName)

Get a symbol expression in the specified context

Remark

symbolContext cannot be a relative context

Remark

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

Remark

symbolContext and baseSymbolName must be UTF8-encoded null-terminated strings. They cannot contain embedded nulls.

Parameters:
  • symbolContext – The context of the symbol to get

  • baseSymbolName – The base name of the symbol to get

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR)symbolContext was not a valid non-relative symbol context

  • wlr_Error(WLR_MISCELLANEOUS_ERROR)baseSymbolName was not a valid base symbol name

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

A symbol expression

wlr_expr wlr_SymbolName(wlr_expr symbol)

Get the base name of a symbol expression

Parameters:

symbol – The symbol expression

Return values:
  • wlr_Error(WLR_UNEXPECTED_TYPE) – The expression was not a symbol

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The base name as a string expression

wlr_expr wlr_SymbolContext(wlr_expr symbol)

Get the context of a symbol expression

Parameters:

symbol – The symbol expression

Return values:
  • wlr_Error(WLR_UNEXPECTED_TYPE) – The expression was not a symbol

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The context as a string expression

wlr_exprbag wlr_ExpressionBag(void)

Create an expression bag

Remark

Expression bags can be converted into expressions using wlr_ExpressionBagToExpression

Remark

If the function is successful, is the responsibility of the user to release the expression bag using wlr_ReleaseExpressionBag

Return values:
  • NULL – An error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

An expression bag

Post:

If the function is successful, expressions can safely be added to the expression bag

wlr_err_t wlr_AddExpression(wlr_exprbag expressionBag, wlr_expr expression)

Add an expression to an expression bag

Parameters:
  • expressionBag – The expression bag

  • expression – The expression

Return values:
  • WLR_SUCCESS – The function succeeded

  • WLR_ERROR_EXPRESSION – The expression was an error expression

  • WLR_MISCELLANEOUS_ERRORexpressionBag was NULL

  • WLR_MISCELLANEOUS_ERROR – A miscellaneous error occurred

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the expression was successfully added to the expression bag

mint wlr_ExpressionBagLength(wlr_exprbag expressionBag)

Get the number of expressions in an expression bag

Parameters:

expressionBag – The expression bag

Return values:
  • 0expressionBag was NULL

  • -1 – The runtime has not been started using wlr_StartRuntime

Returns:

The number of expressions in the expression bag

wlr_expr wlr_ExpressionBagToExpression(wlr_exprbag expressionBag, wlr_expr expressionHead)

Create an expression with the elements of an expression bag

Remark

The new expression will be a normal expression with the provided head

Parameters:
  • expressionBag – The expression bag

  • expressionHead – The head for the new expression

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR)expressionBag was NULL

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • wlr_Error(<propogated_from_argument>) – The expression head was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

A normal expression with the head expressionHead containing the elements of expressionBag

void wlr_ReleaseExpressionBag(wlr_exprbag expressionBag)

Release an expression bag

Parameters:

expressionBag – The expression bag

Pre:

This function will do nothing if the runtime has not been started using wlr_StartRuntime

Pre:

expressionBag is an expression bag previously successfully created using wlr_ExpressionBag

Post:

expressionBag has been released

wlr_expr wlr_String(char *string)

Get a string expression

Remark

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

Remark

string cannot contain embedded nulls because it must be null-terminated. However, it can contain code points in the surrogate pair range.

Remark

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

Parameters:

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

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR)string was NULL

  • wlr_Error(WLR_MISCELLANEOUS_ERROR)string was not encoded in valid UTF8

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The string expression

wlr_expr wlr_StringFromData(char *utf8Data, mint utf8DataLength)

Get a string expression from UTF8 data

Remark

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

Remark

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

Remark

utf8Data does not have to be null-terminated. The data can contain embedded nulls. It can also contain code points in the surrogate pair range.

Parameters:
  • utf8Data – The UTF8 data to use to create the string expression

  • utf8DataLength – The length in bytes of the UTF8 data

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR)utf8Data was NULL

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – The data was not valid UTF8

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The string expression

wlr_expr wlr_RawString(char *string)

Get a string expression

Remark

string cannot contain embedded nulls because it must be null-terminated. However, it can contain code points in the surrogate pair range.

Remark

This function will not transform the contents of string in any way

Parameters:

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

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR)string was NULL

  • wlr_Error(WLR_MISCELLANEOUS_ERROR)string was not encoded in valid UTF8

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The string expression

wlr_expr wlr_RawStringFromData(char *utf8Data, mint utf8DataLength)

Get a string expression from UTF8 data

Remark

utf8Data does not have to be null-terminated. The data can contain embedded nulls. It can also contain code points in the surrogate pair range.

Remark

This function will not transform the contents of utf8Data in any way

Parameters:
  • utf8Data – The UTF8 data to use to create the string expression

  • utf8DataLength – The length in bytes of the UTF8 data

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR)utf8Data was NULL

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – The data was not valid UTF8

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The string expression

wlr_err_t wlr_StringData(wlr_expr expression, char **resultData, mint *resultLength)

Get UTF8 data representing a string expression

Remark

The result data can contain code points in the surrogate pair range. Strict UTF8 decoders may not accept data that contains these code points.

Remark

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

Remark

Wolfram Language-specific characters like \[Rule] will become private use area code points in the result data

Remark

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

Parameters:
  • expression – The string expression to get the data from

  • resultData[out] Pointer to write the UTF8 data to

  • resultLength[out] Pointer to write the length in bytes of the UTF8 data to

Return values:
  • WLR_SUCCESS – The function succeeded

  • WLR_UNEXPECTED_TYPE – The expression was not a string or error expression

  • WLR_ERROR_EXPRESSIONexpression an error expression

  • WLR_MISCELLANEOUS_ERROR – The UTF8 data contains an embedded null, but resultLength is NULL (which is a problem because we cannot provide the length of the result to the caller)

  • WLR_ALLOCATION_ERROR – An allocation error occurred

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the function succeeded

Post:

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

Post:

The result data will be the expression as UTF8 data

Post:

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

wlr_expr wlr_ExpressionFromNumericArray(MNumericArray numericArray, wlr_expr expressionHead)

Get an expression from a numeric array

Remark

If expressionHead is wlr_Symbol("NumericArray") or wlr_Symbol("ByteArray"), the result will be a numeric array expression (i.e., not a normal expression)

Remark

If expressionHead is wlr_Symbol("List"), the result will be a normal or packed array expression

Remark

Byte array expressions are implemented as numeric array expressions under the hood. Accordingly, wlr_ExpressionType of a byte array expression is WLR_NUMERIC_ARRAY.

Parameters:
  • numericArray – The numeric array

  • expressionHead – The head for the expression to create

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR)expressionHead is not wlr_Symbol("NumericArray"), wlr_Symbol("ByteArray"), or wlr_Symbol("List")

  • wlr_Error(WLR_MISCELLANEOUS_ERROR)numericArray is rank zero

  • wlr_Error(WLR_MISCELLANEOUS_ERROR)expressionHead is wlr_Symbol("NumericArray") or wlr_Symbol("List"), but numericArray does not contain any elements

  • wlr_Error(WLR_MISCELLANEOUS_ERROR)expressionHead is wlr_Symbol("ByteArray"), but the type of numericArray is not MNumericArray_Type_UBit8

  • wlr_Error(WLR_MISCELLANEOUS_ERROR)expressionHead is wlr_Symbol("ByteArray"), but numericArray is not rank one

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • wlr_Error(<propogated_from_argument>) – The expression head was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

A numeric array expression, byte array expression, or list expression created from numericArray

wlr_err_t wlr_NumericArrayData(wlr_expr expression, MNumericArray *result)

Get a numeric array from an expression

Remark

This function accepts numeric arrays, byte arrays, and lists (including packed arrays). If expression is a numeric array expression, the result will preserve its type. If expression is a byte array expression, the type of the result will be MNumericArray_Type_UBit8.

Remark

This function has the same behavior as the Wolfram Language function NumericArray with respect to converting list expressions into numeric arrays (e.g., how the type of the resulting numeric array is determined based on the list data)

Remark

If the function is successful, it is the responsibility of the user to release the result using wlr_MNumericArray_free

Parameters:
  • expression – The expression

  • result[out] Pointer to write the result to

Return values:
  • WLR_SUCCESS – The function succeeded

  • WLR_UNEXPECTED_TYPEexpression was not a numeric array, byte array, list, or error expression

  • WLR_UNEXPECTED_TYPEexpression was a list but could not be represented as a numeric array

  • WLR_UNEXPECTED_TYPEexpression was a list but as a numeric array it would contain zero elements

  • WLR_ERROR_EXPRESSIONexpression was an error expression

  • WLR_MISCELLANEOUS_ERROR – A miscellaneous error occurred

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the function succeeded

Post:

The result is the expression as a MNumericArray

Post:

If the function is not successful, the result is NULL

wlr_expr_t wlr_ExpressionType(wlr_expr expression)

Get the type of an expression

Remark

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

Remark

Sparse arrays and symmetrized arrays are object instance-type expressions

Remark

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

Parameters:

expression – The expression

Return values:
  • WLR_NUMBERexpression is a number-type expression

  • WLR_NORMALexpression is a normal-type expression

  • WLR_SYMBOLexpression is a symbol-type expression

  • WLR_STRINGexpression is a string-type expression

  • WLR_PACKED_ARRAYexpression is a packed array-type expression

  • WLR_NUMERIC_ARRAYexpression is a numeric array-type expression

  • WLR_NUMERIC_ARRAYexpression is a byte array-type expression

  • WLR_BOOLEAN_FUNCTIONexpression is a boolean function-type expression

  • WLR_GRAPHexpression is a graph-type expression

  • WLR_ASSOCIATIONexpression is an association-type expression

  • WLR_DISPATCHexpression is a dispatch table-type expression

  • WLR_REGIONexpression is a region-type expression

  • WLR_ERRORexpression is an error

  • WLR_OTHERexpression is a type not listed above

  • WLR_OTHER – The runtime has not been started using wlr_StartRuntime

Returns:

The type of the expression

wlr_expr wlr_Normalize(wlr_expr expression)

Transform the non-normal, non-number, non-string components of an expression into normal expressions

Remark

This function is similar to the Wolfram Language function FullForm

Remark

There are some expression types for which evaluating the normalized form of expression will yield a different expression than expression

Parameters:

expression – The expression to transform

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The transformed expression

wlr_expr wlr_ExpressionFromIntegerArray(mint arrayLength, mint *array, wlr_expr expressionHead)

Get an expression from an integer array

Remark

If the head is wlr_Symbol(“List”), the resulting expression will be a normal list expression or packed array

Remark

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

Parameters:
  • arrayLength – The length of the integer array

  • array – The integer array

  • expressionHead – The head for the expression to create

Return values:
  • wlr_Error(WLR_ALLOCATION_ERROR) – An allocation error occurred

  • wlr_Error(WLR_MISCELLANEOUS_ERROR)expressionHead is not wlr_Symbol(“NumericArray”), wlr_Symbol(“ByteArray”), or wlr_Symbol(“List”)

  • wlr_Error(WLR_MISCELLANEOUS_ERROR)expressionHead is wlr_Symbol(“NumericArray”) or wlr_Symbol(“List”), but arrayLength is zero

  • wlr_Error(WLR_MISCELLANEOUS_ERROR)expressionHead is wlr_Symbol(“ByteArray”), but the integer array contained integers outside the range 0-255

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression head was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The expression created from an integer array

wlr_expr wlr_ExpressionFromRealArray(mint arrayLength, mreal *array, wlr_expr expressionHead)

Get an expression from a real array

Todo:

Maybe refactor the implementation of this function with wlr_ExpressionFromIntegerArray

Remark

If the head is wlr_Symbol(“List”), the resulting expression will be a normal list expression or packed array

Remark

If the head is wlr_Symbol(“NumericArray”), the resulting expression will be a numeric array expression (i.e., not a normal expression)

Parameters:
  • arrayLength – The length of the real array

  • array – The real array

  • expressionHead – The head for the expression to create

Return values:
  • wlr_Error(WLR_MISCELLANEOUS_ERROR)expressionHead is not wlr_Symbol(“NumericArray”) or wlr_Symbol(“List”)

  • wlr_Error(WLR_MISCELLANEOUS_ERROR)arrayLength is zero

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(WLR_ALLOCATION_ERROR) – An allocation error occurred

  • wlr_Error(<propogated_from_argument>) – The expression head was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The expression created from a real array

wlr_err_t wlr_IntegerArrayData(wlr_expr expression, mint *resultLength, mint **resultArray)

Get an array of integers from an expression

Remark

This function accepts numeric arrays, byte arrays, and lists

Remark

This function accepts packed array lists @Remarks The result array can be NULL and the result length zero if expression is a zero-length byte array

Remark

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

Parameters:
  • expression – The expression

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

  • resultArray[out] Pointer to write the array

Return values:
  • WLR_SUCCESS – The function succeeded

  • WLR_UNEXPECTED_TYPEexpression was not a numeric array, byte array, list, or error expression

  • WLR_UNEXPECTED_TYPEexpression was a numeric array that was not rank one

  • WLR_UNEXPECTED_TYPEexpression was a numeric array but its type was not an integer type

  • WLR_UNEXPECTED_TYPEexpression was a list but did not contain only machine integers

  • WLR_UNEXPECTED_TYPEexpression was a list but it contained zero elements

  • WLR_ERROR_EXPRESSIONexpression was an error expression

  • WLR_ALLOCATION_ERROR – An allocation error occurred

  • WLR_MISCELLANEOUS_ERROR – A miscellaneous error occurred

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the function succeeded

Post:

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

Post:

The result array will be the expression as an integer array

Post:

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

wlr_err_t wlr_RealArrayData(wlr_expr expression, mint *resultLength, mreal **resultArray)

Get a real array from an expression

Todo:

Maybe refactor the implementation of this function with wlr_IntegerArrayData

Remark

This function accepts numeric arrays and lists

Remark

This function accepts packed array lists

Remark

If the function is successful, it is the responsibility of the user to release the result array using wlr_Release

Parameters:
  • expression – The expression

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

  • resultArray[out] Pointer to write the array

Return values:
  • WLR_SUCCESS – The function succeeded

  • WLR_UNEXPECTED_TYPEexpression was not a numeric array, list, or error expression

  • WLR_UNEXPECTED_TYPEexpression was a numeric array that was not rank one

  • WLR_UNEXPECTED_TYPEexpression was a numeric array but its type was not a real type

  • WLR_UNEXPECTED_TYPEexpression was a list but did not contain only machine reals

  • WLR_UNEXPECTED_TYPEexpression was a list but it contained zero elements

  • WLR_ERROR_EXPRESSIONexpression was an error expression

  • WLR_ALLOCATION_ERROR – An allocation error occurred

  • WLR_MISCELLANEOUS_ERROR – A miscellaneous error occurred

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the function succeeded

Post:

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

Post:

The result array will be the expression as a real array

Post:

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

mbool wlr_TrueQ(wlr_expr expression)

Test if an expression is the symbol True

Parameters:

expression – The expression

Return values:
  • TRUE – The expression is the symbol True

  • FALSE – The expression is not the symbol True

  • FALSE – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the expression is the symbol True

mbool wlr_SameQ(wlr_expr firstExpression, wlr_expr secondExpression)

Test if two expressions are the same

Remark

This function is similar to the Wolfram Language function SameQ

Parameters:
  • firstExpression – The first expression

  • secondExpression – The second expression

Return values:
  • TRUE – The expressions are the same

  • FALSE – The expressions are not the same

  • FALSE – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the two expressions are the same

wlr_expr wlr_GetValueFromKey(wlr_expr association, wlr_expr key)

Get the value of a key in an association

Remark

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)

Parameters:
  • association – The association

  • key – The key

Return values:
  • wlr_Error(WLR_UNEXPECTED_TYPE) – The first argument is not an association

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – The key was not present in the association

  • wlr_Error(<propogated_from_argument>) – An argument was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The value of the key

wlr_expr wlr_GetKeys(wlr_expr association)

Get a list of keys in an association

Remark

This function is similar to the Wolfram Language functions Keys

Parameters:

association – The association

Return values:
  • wlr_Error(WLR_UNEXPECTED_TYPE) – The expression is not an association

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

A list of keys

wlr_expr wlr_GetValues(wlr_expr association)

Get a list of values in an association

Remark

This function is similar to the Wolfram Language functions Values

Remark

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)

Parameters:

expression – The association

Return values:
  • wlr_Error(WLR_UNEXPECTED_TYPE) – The expression is not an association

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The list of values in the association

wlr_expr wlr_ParseExpression(wlr_expr inputStringExpression)

Parse a string of Wolfram Language formatted in InputForm into an expression

Remark

If the Wolfram Language string represents multiple expressions, this function returns a list containing each expression (without evaluating them)

Remark

This function takes a string expression

Remark

The reason this function takes an expression is so that complicated string functionality like special characters and embedded nulls are dealt with in fewer places (e.g., wlr_StringFromData)

Remark

Any output or messages generated during the parse will be suppressed

Parameters:

inputStringExpression – The Wolfram Language string as an expression

Return values:
  • wlr_Error(WLR_UNEXPECTED_TYPE) – The expression argument was not a string

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – An error occurred

  • wlr_Error(<propogated_from_argument>) – The expression was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The unevaluated expression represented by the Wolfram Language string

wlr_err_t wlr_Serialize(char *fileName, wlr_expr expression)

Serialize an expression into a file

Remark

fileName must be a UTF8-encoded null-terminated string

Remark

fileName cannot contain embedded nulls

Remark

The function wlr_Deserialize can be used to deserialize the contents of the file fileName back into an expression

Remark

WXF files can also be serialized to or deserialized from using Wolfram Language functions

Parameters:
  • fileName – The path of the file to serialize into

  • expression – The expression to serialize

Return values:
  • WLR_SUCCESS – The function succeeded

  • WLR_ERROR_EXPRESSION – The expression was an error expression

  • WLR_MISCELLANEOUS_ERROR – A miscellaneous error occurred

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the function succeeded

Post:

If the function is successful, the WXF serialization of the expression has been written to the file fileName

wlr_expr wlr_Deserialize(char *fileName)

Deserialize a file into an expression

Remark

fileName must be a UTF8-encoded null-terminated string

Remark

fileName cannot contain embedded nulls

Remark

This function can be used to deserialize files that have been successfully previously written to using wlr_Serialize

Remark

WXF files can also be serialized to or deserialized from using Wolfram Language functions

Parameters:

fileName – The path of the file to deserialize

Return values:
  • wlr_Error(WLR_SIGNING_ERROR) – In a signed application, the normalized form of the deserialized expression contains unapproved symbols

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The deserialized expression

Pre:

The file fileName contains a valid WXF serialization of an expression

wlr_err_t wlr_IntegerData(wlr_expr machineIntegerExpression, mint *result)

Get an integer value from a machine integer expression

Parameters:
  • machineIntegerExpression – The machine integer expression

  • result[out] Pointer to write the result to

Return values:
  • WLR_SUCCESS – The function succeeded

  • WLR_UNEXPECTED_TYPE – The expression was not a machine integer or error expression

  • WLR_ERROR_EXPRESSIONmachineIntegerExpression was an error expression

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the function succeeded

Post:

If the function is successful, the result is the integer value of machineIntegerExpression

Post:

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

wlr_err_t wlr_RealData(wlr_expr machineRealExpression, mreal *result)

Get a real value from a machine real expression

Remark

This function will fail if a big real, Overflow[], or Underflow[] is passed

Parameters:
  • machineRealExpression – The machine real expression or the expressions DirectedInfinity[1] or DirectedInfinity[-1]

  • result[out] Pointer to write the result to

Return values:
  • WLR_SUCCESS – The function succeeded

  • WLR_UNEXPECTED_TYPE – The expression was not a machine real, DirectedInfinity[1], DirectedInfinity[-1], or an error expression

  • WLR_ERROR_EXPRESSIONmachineRealExpression was an error expression

  • WLR_RUNTIME_NOT_STARTED – The runtime has not been started using wlr_StartRuntime

Returns:

Whether the function succeeded

Post:

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

Post:

If the expression is DirectedInfinity[1], the result is the real value Inf

Post:

If the expression is DirectedInfinity[-1], the result is the real value -Inf

Post:

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

mbool wlr_SignedCodeMode(void)

Check whether the runtime is in signed code mode

Return values:
  • TRUE – The runtime is in signed code mode

  • FALSE – The runtime is not in signed code mode

  • FALSE – The runtime has not been started using wlr_StartRuntime

wlr_expr wlr_VariadicE(wlr_expr expressionHead, mint childElementNumber, ...)

Construct an expression with a specific head and specific child elements

Remark

Use the wlr_E macro in order to avoid having to manually specify the number of child elements. This means childElementNumber can be omitted.

Remark

The new expression will be a normal expression

Remark

This function does not evaluate the new expression

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

Return values:
  • wlr_Error(WLR_ALLOCATION_ERROR) – Failed to create a new expression

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – An argument was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The new expression

wlr_expr wlr_VariadicList(mint childElementNumber, ...)

Construct a list expression with specific child elements

Remark

Use the wlr_List macro in order to avoid having to manually specify the number of child elements. This means childElementNumber can be omitted.

Remark

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

Remark

The result will never be a packed array

Remark

This function does not evaluate the new list expression

Parameters:
  • childElementNumber – The number of child elements for the new list expression

  • ... – The child elements for the new list expression

Return values:
  • wlr_Error(WLR_ALLOCATION_ERROR) – Failed to create a new list expression

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – An argument was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The new list expression

wlr_expr wlr_VariadicAssociation(mint keyValuePairNumber, ...)

Construct an association expression with specific key-value pairs

Remark

Use the wlr_Association macro in order to avoid having to manually specify the number of key-value pairs. This means keyValuePairNumber can be omitted.

Remark

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

Remark

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

Remark

On success, this function returns an expression of type WLR_ASSOCIATION when tested using wlr_ExpressionType

Remark

In the context of a signed application, an error will occur if a key or value contains a symbol that is not approved

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

Return values:
  • wlr_Error(WLR_SIGNING_ERROR) – In a signed application, a key or value contains an unapproved symbol

  • wlr_Error(WLR_UNEXPECTED_TYPE) – An argument was not a rule expression

  • wlr_Error(WLR_ALLOCATION_ERROR) – Failed to create a new association expression

  • wlr_Error(WLR_MISCELLANEOUS_ERROR) – A miscellaneous error occurred

  • wlr_Error(<propogated_from_argument>) – An argument was an error expression

  • NULL – The runtime has not been started using wlr_StartRuntime

Returns:

The new association expression

Interacting with the MNumericArray type

errcode_t wlr_MNumericArray_new(const numericarray_data_t type, const mint rank, const mint *dims, MNumericArray *res)
errcode_t wlr_MNumericArray_clone(const MNumericArray from, MNumericArray *to)
void wlr_MNumericArray_free(MNumericArray narray)
void wlr_MNumericArray_disown(MNumericArray narray)
void wlr_MNumericArray_disownAll(MNumericArray narray)
mint wlr_MNumericArray_shareCount(const MNumericArray narray)
numericarray_data_t wlr_MNumericArray_getType(const MNumericArray narray)
mint wlr_MNumericArray_getRank(const MNumericArray narray)
mint wlr_MNumericArray_getFlattenedLength(const MNumericArray narray)
errcode_t wlr_MNumericArray_convertType(MNumericArray *outP, const MNumericArray narray, const numericarray_data_t result_type, const numericarray_convert_method_t method, const mreal tolerance)
mint *wlr_MNumericArray_getDimensions(const MNumericArray narray)
void *wlr_MNumericArray_getData(const MNumericArray narray)

Topics

Thread Safety

The expression API is not thread safe. Developers must use synchronization techniques to ensure that only one thread is calling the expression API at a time.

License Signatures

Support for license signatures in the expression API is discussed throughout the reference information above, and in this document.

Error Expressions

Error expressions are a category of wlr_expr expressions that are treated differently by the expression API. Any expression API function that returns an expression can return an error expression, if the function fails. The error expression contains information about why the function failed.

Additionally, expression API functions that return expressions and take expression arguments “propagate” error expressions that were passed in. That is, if I pass an error expression to such a function, it will stop and return that expression. This allows developers to stack calls to expression API functions without individually error checking each call.