Attribute Macro export 

#[export]

Export the specified functions as native LibraryLink functions.

To be exported by this macro, the specified function(s) must implement NativeFunction.

Functions exported using this macro will automatically:

• Call initialize() to initialize this library.
• Catch any panics that occur.
  • If a panic does occur, the function will return LIBRARY_FUNCTION_ERROR.

Syntax

Export a native function.

#[export]

Export a function using the specified low-level shared library symbol name.

#[export(name = "WL_square")]

Advanced

Don’t include an exported function in the automatic generate_loader! output.

#[export(hidden)]

Examples

Primitive data types

Export a native function with a single integer argument:

#[export]
fn square(x: i64) -> i64 {
    x * x
}

LibraryFunctionLoad["...", "square", {Integer}, Integer]

Export a native function with a single string argument:

#[export]
fn reverse_string(string: String) -> String {
    string.chars().rev().collect()
}

LibraryFunctionLoad["...", "reverse_string", {String}, String]

Export a native function with multiple arguments:

#[export]
fn times(a: f64, b: f64) -> f64 {
    a * b
}

LibraryFunctionLoad["...", "times", {Real, Real}, Real]

Numeric arrays

Export a native function with a NumericArray argument:

#[export]
fn total_i64(list: &NumericArray<i64>) -> i64 {
    list.as_slice().into_iter().sum()
}

LibraryFunctionLoad[
    "...", "total_i64",
    {LibraryDataType[NumericArray, "Integer64"]}
    Integer
]

Customize exported function name

By default, the exported name of a function exported to the Wolfram Langauge using #[export] will be the same as the Rust function name. The exported name can be customed by specifying the name = "..." argument to the #[export] macro:

use wolfram_library_link::export;

#[export(name = "native_square")]
fn square(x: i64) -> i64 {
    x * x
}

LibraryFunctionLoad["<library name>", "native_square", {Integer}, Integer]

Parameter types

When manually writing the Wolfram LibraryFunctionLoad_WL call necessary to load a Rust LibraryLink function, you must declare the type signature of the function using the appropriate types.

The following table describes the relationship between Rust types that can be used as parameter types in a native LibraryLink function (namely: those that implement FromArg) and the compatible Wolfram LibraryLink function parameter type(s).

FromArg::parameter_type() can be used to determine the Wolfram library function parameter type programatically.

If you would prefer to have the Wolfram Language code for loading your library be generated automatically, use the generate_loader! macro.

⚠️ Warning! ⚠️

Calling a LibraryLink function from the Wolfram Language that was loaded using the wrong parameter type may lead to undefined behavior! Ensure that the function parameter type declared in your Wolfram Language code matches the Rust function parameter type.

Rust parameter type	Wolfram library function parameter type
bool	"Boolean"
mint	Integer
mreal	Real
mcomplex	Complex
String	String
CString	String
&NumericArray	a. LibraryDataType[NumericArray] b. {LibraryDataType[NumericArray], "Constant"}1
NumericArray	a. {LibraryDataType[NumericArray], "Manual"}1 b. {LibraryDataType[NumericArray], "Shared"}1
&NumericArray<T>	a. LibraryDataType[NumericArray, "..."]1 b. {LibraryDataType[NumericArray, "..."], "Constant"}1
NumericArray<T>	a. {LibraryDataType[NumericArray, "..."], "Manual"}1 b. {LibraryDataType[NumericArray, "..."], "Shared"}1
DataStore	"DataStore"

Return types

The following table describes the relationship between Rust types that implement IntoArg and the compatible Wolfram LibraryLink function return type.

IntoArg::return_type() can be used to determine the Wolfram library function parameter type programatically.

Rust return type	Wolfram library function return type
()	"Void"
bool	"Boolean"
mint	Integer
mreal	Real
i8, i16, i32	Integer
u8, u16, u32	Integer
f32	Real
mcomplex	Complex
String	String
NumericArray	LibraryDataType[NumericArray]
NumericArray<T>	LibraryDataType[NumericArray, "..."1]
DataStore	"DataStore"

#[export(wstp)]

Export the specified functions as native LibraryLink WSTP functions.

To be exported by this macro, the specified function(s) must implement WstpFunction.

Functions exported using this macro will automatically:

• Call initialize() to initialize this library.
• Catch any panics that occur.
  • If a panic does occur, it will be returned as a Failure[...] expression.

Syntax

Export a LibraryLink WSTP function.

#[export(wstp)]

Export a LibraryLink WSTP function using the specified low-level shared library symbol name.

#[export(wstp, name = "WL_square")]

Examples

WSTP function that squares a single integer argument:

use wolfram_library_link::{export, wstp::Link};

#[export(wstp)]
fn square_wstp(link: &mut Link) {
    // Get the number of elements in the arguments list.
    let arg_count = link.test_head("List").unwrap();

    if arg_count != 1 {
        panic!("square_wstp: expected to get a single argument");
    }

    // Get the argument value.
    let x = link.get_i64().expect("expected Integer argument");

    // Write the return value.
    link.put_i64(x * x).unwrap();
}

LibraryFunctionLoad["...", "square_wstp", LinkObject, LinkObject]

WSTP function that computes the sum of a variable number of arguments:

use wolfram_library_link::{export, wstp::Link};

#[export(wstp)]
fn total_args_i64(link: &mut Link) {
    // Check that we recieved a functions arguments list, and get the number of arguments.
    let arg_count: usize = link.test_head("List").unwrap();

    let mut total: i64 = 0;

    // Get each argument, assuming that they are all integers, and add it to the total.
    for _ in 0..arg_count {
        let term = link.get_i64().expect("expected Integer argument");
        total += term;
    }

    // Write the return value to the link.
    link.put_i64(total).unwrap();
}

LibraryFunctionLoad["...", "total_args_i64", LinkObject, LinkObject]

---

1. The Details and Options section of the Wolfram Language NumericArray reference page lists the available element types. ↩ ^{1 2 3 4 5 6 7 8}