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(...)¶
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¶
-
enumerator WLR_MACHINE_INTEGER¶
-
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¶
-
enumerator WLR_NUMBER¶
-
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¶
-
enumerator WLR_SUCCESS¶
-
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¶
-
enumerator WLR_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¶
-
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¶
-
enumerator WLR_CONTAINED¶
-
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.
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_1Remark
If
licenseType
is WLR_SIGNED_CODE_MODE, the runtime will be in signed code mode and a license will not be consumedRemark
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
isNULL
, this function will use the default configuration settings set by wlr_InitializeRuntimeConfiguration. Ifconfiguration
is notNULL
, 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 invalidRemark
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 supportedWLR_RUNTIME_NOT_STARTED – The provided value for
layoutDirectory
was an empty stringWLR_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 typeNULL – 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 ifNULL
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 withcontextData
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 dataRemark
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 withcontextData
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_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 theAbortProtect
is exitedRemark
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. AGeneral::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 symbolwlr_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 expressionRemark
Any output or messages generated during the parse will be suppressed.
$MessageList
is cleared before the file is evaluated. AGeneral::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 approvedwlr_Error(WLR_UNEXPECTED_TYPE) –
inputStringExpression
was not a stringwlr_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 formHold[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. AGeneral::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 symbolwlr_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 likeGet
, and a signing violation occurs.Remark
$MessageList
is cleared before the file is evaluated. AGeneral::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 symbolswlr_Error(WLR_SIGNING_ERROR) – In a signed application,
fileName
is a MX file, but the file is not approvedwlr_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_NumberTypeRemark
This function is similar to the Wolfram Language function
NumberQ
- Parameters:
expression – The expression
- Return values:
TRUE –
expression
is a numberFALSE –
expression
is not a numberFALSE – 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_INTEGER –
numberExpression
is a machine integerWLR_BIG_INTEGER –
numberExpression
is a big integerWLR_MACHINE_REAL –
numberExpression
is a machine realWLR_BIG_REAL –
numberExpression
is a big realWLR_COMPLEX –
numberExpression
is a complex numberWLR_RATIONAL –
numberExpression
is a rationalWLR_OVERFLOW –
numberExpression
is overflowedWLR_UNDERFLOW –
numberExpression
is underflowedWLR_NOT_A_NUMBER –
numberExpression
is not a numberWLR_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 expressionWLR_ERROR_EXPRESSION – The expression
numberExpression
was an error expressionWLR_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 valueIf
numberExpression
is a big integer, the result is its value truncated to a machine integerIf
numberExpression
is a machine real, the result is the value of its integer partIf
numberExpression
is a big real, the result is the value of its integer part truncated to a machine integerIf
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]
, orDirectedInfinity[-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]
orDirectedInfinity[-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 expressionWLR_ERROR_EXPRESSION – The expression
numberExpression
was an error expressionWLR_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 realIf
numberExpression
is a big integer, the result is its value rounded to the nearest machine realIf
numberExpression
is a machine real, the result is its real valueIf
numberExpression
is a big real, the result is its value rounded to the nearest machine realIf
numberExpression
is a rational, the result is its value rounded to the nearest machine realIf
numberExpression
isDirectedInfinity[1]
, the result is the real valueInf
If
numberExpression
isDirectedInfinity[-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 numberwlr_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 numberwlr_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 zerowlr_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 returnrationalExpression
- Parameters:
rationalExpression – The rational expression
- Return values:
wlr_Error(WLR_UNEXPECTED_TYPE) – The expression
rationalExpression
was not a rational or integerwlr_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 return1
- 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_EXPRESSION –
numberExpression
was an error expressionWLR_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")
containingleftHandSide
andrightHandSide
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")
orwlr_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 expressionRemark
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-formedRemark
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 namewlr_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`
contextRemark
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-formedRemark
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 namewlr_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`
contextRemark
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-formedRemark
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 namewlr_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 contextRemark
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-formedRemark
symbolContext
andbaseSymbolName
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 contextwlr_Error(WLR_MISCELLANEOUS_ERROR) –
baseSymbolName
was not a valid base symbol namewlr_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_ERROR –
expressionBag
wasNULL
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:
0 –
expressionBag
wasNULL
-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
wasNULL
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 ofexpressionBag
-
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 charactersRemark
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
wasNULL
wlr_Error(WLR_MISCELLANEOUS_ERROR) –
string
was not encoded in valid UTF8wlr_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 nullsRemark
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
wasNULL
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
wasNULL
wlr_Error(WLR_MISCELLANEOUS_ERROR) –
string
was not encoded in valid UTF8wlr_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
wasNULL
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 dataRemark
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_EXPRESSION –
expression
an error expressionWLR_MISCELLANEOUS_ERROR – The UTF8 data contains an embedded null, but
resultLength
isNULL
(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
iswlr_Symbol("NumericArray")
orwlr_Symbol("ByteArray")
, the result will be a numeric array expression (i.e., not a normal expression)Remark
If
expressionHead
iswlr_Symbol("List")
, the result will be a normal or packed array expressionRemark
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 notwlr_Symbol("NumericArray")
,wlr_Symbol("ByteArray")
, orwlr_Symbol("List")
wlr_Error(WLR_MISCELLANEOUS_ERROR) –
numericArray
is rank zerowlr_Error(WLR_MISCELLANEOUS_ERROR) –
expressionHead
iswlr_Symbol("NumericArray")
orwlr_Symbol("List")
, butnumericArray
does not contain any elementswlr_Error(WLR_MISCELLANEOUS_ERROR) –
expressionHead
iswlr_Symbol("ByteArray")
, but the type ofnumericArray
is notMNumericArray_Type_UBit8
wlr_Error(WLR_MISCELLANEOUS_ERROR) –
expressionHead
iswlr_Symbol("ByteArray"
), butnumericArray
is not rank onewlr_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. Ifexpression
is a byte array expression, the type of the result will beMNumericArray_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_TYPE –
expression
was not a numeric array, byte array, list, or error expressionWLR_UNEXPECTED_TYPE –
expression
was a list but could not be represented as a numeric arrayWLR_UNEXPECTED_TYPE –
expression
was a list but as a numeric array it would contain zero elementsWLR_ERROR_EXPRESSION –
expression
was an error expressionWLR_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_NUMBER –
expression
is a number-type expressionWLR_NORMAL –
expression
is a normal-type expressionWLR_SYMBOL –
expression
is a symbol-type expressionWLR_STRING –
expression
is a string-type expressionWLR_PACKED_ARRAY –
expression
is a packed array-type expressionWLR_NUMERIC_ARRAY –
expression
is a numeric array-type expressionWLR_NUMERIC_ARRAY –
expression
is a byte array-type expressionWLR_BOOLEAN_FUNCTION –
expression
is a boolean function-type expressionWLR_GRAPH –
expression
is a graph-type expressionWLR_ASSOCIATION –
expression
is an association-type expressionWLR_DISPATCH –
expression
is a dispatch table-type expressionWLR_REGION –
expression
is a region-type expressionWLR_ERROR –
expression
is an errorWLR_OTHER –
expression
is a type not listed aboveWLR_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 thanexpression
- 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”), butarrayLength
is zerowlr_Error(WLR_MISCELLANEOUS_ERROR) –
expressionHead
is wlr_Symbol(“ByteArray”), but the integer array contained integers outside the range 0-255wlr_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 zerowlr_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 arrayRemark
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_TYPE –
expression
was not a numeric array, byte array, list, or error expressionWLR_UNEXPECTED_TYPE –
expression
was a numeric array that was not rank oneWLR_UNEXPECTED_TYPE –
expression
was a numeric array but its type was not an integer typeWLR_UNEXPECTED_TYPE –
expression
was a list but did not contain only machine integersWLR_UNEXPECTED_TYPE –
expression
was a list but it contained zero elementsWLR_ERROR_EXPRESSION –
expression
was an error expressionWLR_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_TYPE –
expression
was not a numeric array, list, or error expressionWLR_UNEXPECTED_TYPE –
expression
was a numeric array that was not rank oneWLR_UNEXPECTED_TYPE –
expression
was a numeric array but its type was not a real typeWLR_UNEXPECTED_TYPE –
expression
was a list but did not contain only machine realsWLR_UNEXPECTED_TYPE –
expression
was a list but it contained zero elementsWLR_ERROR_EXPRESSION –
expression
was an error expressionWLR_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 stringRemark
fileName
cannot contain embedded nullsRemark
The function wlr_Deserialize can be used to deserialize the contents of the file
fileName
back into an expressionRemark
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 stringRemark
fileName
cannot contain embedded nullsRemark
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_EXPRESSION –
machineIntegerExpression
was an error expressionWLR_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_EXPRESSION –
machineRealExpression
was an error expressionWLR_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)¶
-
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.