Struct Expr 

pub struct Expr { /* private fields */ }

Wolfram Language expression.

Example

Construct the expression {1, 2, 3}:

use wolfram_expr::{Expr, Symbol};

let expr = Expr::normal(Symbol::new("System`List"), vec![
    Expr::from(1),
    Expr::from(2),
    Expr::from(3)
]);

Reference counting

Internally, Expr is an atomically reference-counted ExprKind. This makes cloning an expression computationally inexpensive.

Implementations

impl Expr

pub fn try_as_normal(&self) -> Option<&Normal>

If this is a Normal expression, return that. Otherwise return None.

Examples found in repository

examples/wstp.rs (line 179)

fn expr_string_join(link: &mut Link) {
    let expr = link.get_expr().unwrap();

    let list = expr.try_as_normal().unwrap();
    assert!(list.has_head(&Symbol::new("System`List")));

    let mut buffer = String::new();
    for elem in list.elements() {
        match elem.kind() {
            ExprKind::String(str) => buffer.push_str(str),
            _ => panic!("expected String argument, got: {:?}", elem),
        }
    }

    link.put_str(buffer.as_str()).unwrap()
}

pub fn try_as_bool(&self) -> Option<bool>

If this is a True or False symbol, return that. Otherwise return None.

pub fn try_as_str(&self) -> Option<&str>

If this is a ExprKind::String expression, return that. Otherwise return None.

pub fn try_as_symbol(&self) -> Option<&Symbol>

If this is a Symbol expression, return that. Otherwise return None.

pub fn try_as_number(&self) -> Option<Number>

If this is a Number expression, return that. Otherwise return None.

Examples found in repository

examples/wstp.rs (line 206)

fn total(args: Vec<Expr>) -> Expr {
    let mut total = Number::Integer(0);

    for (index, arg) in args.into_iter().enumerate() {
        let number = match arg.try_as_number() {
            Some(number) => number,
            None => panic!(
                "expected argument at position {} to be a number, got {}",
                // Add +1 to display using WL 1-based indexing.
                index + 1,
                arg
            ),
        };

        use Number::{Integer, Real};

        total = match (total, number) {
            // If the sum and new term are integers, use integers.
            (Integer(total), Integer(term)) => Integer(total + term),
            // Otherwise, if the either the total or new term are machine real numbers,
            // use floating point numbers.
            (Integer(int), Real(real)) | (Real(real), Integer(int)) => {
                Number::real(int as f64 + *real)
            },
            (Real(total), Real(term)) => Real(total + term),
        }
    }

    Expr::number(total)
}

pub fn try_normal(&self) -> Option<&Normal>

👎Deprecated: Use Expr::try_as_normal() instead

pub fn try_symbol(&self) -> Option<&Symbol>

👎Deprecated: Use Expr::try_as_symbol() instead

pub fn try_number(&self) -> Option<Number>

👎Deprecated: Use Expr::try_as_number() instead

impl Expr

pub fn new(kind: ExprKind) -> Expr

Construct a new expression from an ExprKind.

pub fn to_kind(self) -> ExprKind

Consume self and return an owned ExprKind.

If the reference count of self is equal to 1 this function will not perform a clone of the stored ExprKind, making this operation very cheap in that case.

pub fn kind(&self) -> &ExprKind

Get the ExprKind representing this expression.

Examples found in repository

examples/wstp.rs (line 184)

fn expr_string_join(link: &mut Link) {
    let expr = link.get_expr().unwrap();

    let list = expr.try_as_normal().unwrap();
    assert!(list.has_head(&Symbol::new("System`List")));

    let mut buffer = String::new();
    for elem in list.elements() {
        match elem.kind() {
            ExprKind::String(str) => buffer.push_str(str),
            _ => panic!("expected String argument, got: {:?}", elem),
        }
    }

    link.put_str(buffer.as_str()).unwrap()
}

examples/exprs/managed.rs (line 55)

fn set_instance_value(args: Vec<Expr>) {
    assert!(args.len() == 2, "set_instance_value: expected 2 arguments");

    let id: u32 = unwrap_id_arg(&args[0]);
    let value: String = match args[1].kind() {
        ExprKind::String(str) => str.clone(),
        _ => panic!("expected 2nd argument to be a String, got: {}", args[1]),
    };

    let mut instances = INSTANCES.lock().unwrap();

    let instance: &mut MyObject =
        instances.get_mut(&id).expect("instance does not exist");

    instance.value = value;
}

/// Get the fields of the `MyObject` instance for the specified instance ID.
#[wll::export(wstp)]
fn get_instance_data(args: Vec<Expr>) -> Expr {
    assert!(args.len() == 1, "get_instance_data: expected 1 argument");

    let id: u32 = unwrap_id_arg(&args[0]);

    let MyObject { value } = {
        let instances = INSTANCES.lock().unwrap();

        instances
            .get(&id)
            .cloned()
            .expect("instance does not exist")
    };

    Expr::normal(Symbol::new("System`Association"), vec![Expr::normal(
        Symbol::new("System`Rule"),
        vec![Expr::string("Value"), Expr::string(value)],
    )])
}

fn unwrap_id_arg(arg: &Expr) -> u32 {
    match arg.kind() {
        ExprKind::Integer(int) => u32::try_from(*int).expect("id overflows u32"),
        _ => panic!("expected Integer instance ID argument, got: {}", arg),
    }
}

pub fn kind_mut(&mut self) -> &mut ExprKind

Get mutable access to the ExprKind that represents this expression.

If the reference count of the underlying shared pointer is not equal to 1, this will clone the ExprKind to make it unique.

pub fn ref_count(&self) -> usize

Retrieve the reference count of this expression.

pub fn normal<H>(head: H, contents: Vec<Expr>) -> Expr

where H: Into<Expr>,

Construct a new normal expression from the head and elements.

Examples found in repository

examples/docs/convert/using_expr.rs (lines 24-27)

    fn to_expr(&self) -> Expr {
        let Point { x, y } = *self;

        Expr::normal(Symbol::new("System`Point"), vec![Expr::list(vec![
            Expr::real(x),
            Expr::real(y),
        ])])
    }

examples/tests/test_threading.rs (lines 10-13)

fn test_runtime_function_from_main_thread() -> bool {
    let expr = Expr::normal(Symbol::new("System`Plus"), vec![
        Expr::from(2),
        Expr::from(2),
    ]);

    wll::evaluate(&expr) == Expr::from(4)
}

#[wll::export]
fn test_runtime_function_from_non_main_thread() -> String {
    let child = std::thread::spawn(|| {
        panic::set_hook(Box::new(|_| {
            // Do nothing, just to avoid printing panic message to stderr.
        }));

        let result = panic::catch_unwind(|| {
            wll::evaluate(&Expr::normal(Symbol::new("System`Plus"), vec![
                Expr::from(2),
                Expr::from(2),
            ]))
        });

        // Restore the previous (default) hook.
        let _ = panic::take_hook();

        result
    });

    let result = child.join().unwrap();

    match result {
        Ok(_) => "didn't panic".to_owned(),
        // We expect the thread to panic
        Err(panic) => {
            if let Some(str) = panic.downcast_ref::<&str>() {
                format!("PANIC: {}", str)
            } else if let Some(string) = panic.downcast_ref::<String>() {
                format!("PANIC: {}", string)
            } else {
                "PANIC".to_owned()
            }
        },
    }
}

examples/exprs/basic_expressions.rs (line 22)

pub fn echo_arguments(args: Vec<Expr>) -> Expr {
    let arg_count = args.len();

    for arg in args {
        // Echo[<arg>]
        wll::evaluate(&Expr::normal(Symbol::new("System`Echo"), vec![arg]));
    }

    Expr::string(format!("finished echoing {} argument(s)", arg_count))
}

examples/docs/evaluate_wolfram_code_from_rust/generate_message.rs (lines 9-16)

fn generate_message(_: Vec<Expr>) {
    // Construct the expression `Message[MySymbol::msg, "..."]`.
    let message = Expr::normal(Symbol::new("System`Message"), vec![
        // MySymbol::msg is MessageName[MySymbol, "msg"]
        Expr::normal(Symbol::new("System`MessageName"), vec![
            Expr::from(Symbol::new("Global`MySymbol")),
            Expr::string("msg"),
        ]),
        Expr::string("a Rust LibraryLink function"),
    ]);

    // Evaluate the message expression.
    let _: Expr = wll::evaluate(&message);
}

examples/exprs/managed.rs (lines 84-87)

fn get_instance_data(args: Vec<Expr>) -> Expr {
    assert!(args.len() == 1, "get_instance_data: expected 1 argument");

    let id: u32 = unwrap_id_arg(&args[0]);

    let MyObject { value } = {
        let instances = INSTANCES.lock().unwrap();

        instances
            .get(&id)
            .cloned()
            .expect("instance does not exist")
    };

    Expr::normal(Symbol::new("System`Association"), vec![Expr::normal(
        Symbol::new("System`Rule"),
        vec![Expr::string("Value"), Expr::string(value)],
    )])
}

examples/raw/raw_wstp_function.rs (lines 103-107)

pub extern "C" fn demo_wstp_function_callback(
    lib: WolframLibraryData,
    mut link: WSLINK,
) -> c_uint {
    // Create a safe Link wrapper around the raw `WSLINK`. This is a borrowed rather than
    // owned Link because the caller (the Kernel) owns the link.
    let link: &mut Link = unsafe { Link::unchecked_ref_cast_mut(&mut link) };

    // Skip reading the argument list packet.
    if link.raw_get_next().and_then(|_| link.new_packet()).is_err() {
        return LIBRARY_FUNCTION_ERROR;
    }

    let callback_link = unsafe { (*lib).getWSLINK.unwrap()(lib) };
    let mut callback_link = callback_link as wstp::sys::WSLINK;

    {
        let safe_callback_link =
            unsafe { Link::unchecked_ref_cast_mut(&mut callback_link) };

        safe_callback_link
            // EvaluatePacket[Print["Hello, World! --- WSTP"]]
            .put_expr(&Expr::normal(Symbol::new("System`EvaluatePacket"), vec![
                Expr::normal(Symbol::new("System`Print"), vec![Expr::string(
                    "Hello, World! --- WSTP",
                )]),
            ]))
            .unwrap();

        unsafe {
            (*lib).processWSLINK.unwrap()(
                safe_callback_link.raw_link() as wll_sys::WSLINK
            );
        }

        // Skip the return value packet. This is necessary, otherwise the link has
        // unread data and the return value of this function cannot be processed properly.
        if safe_callback_link
            .raw_get_next()
            .and_then(|_| safe_callback_link.new_packet())
            .is_err()
        {
            return LIBRARY_FUNCTION_ERROR;
        }
    }

    link.put_expr(&Expr::string("returned normally")).unwrap();

    return LIBRARY_NO_ERROR;
}

/// This example makes use of the [`wstp`][wstp] crate to provide a safe wrapper around
/// around the WSTP link object, which can be used to read the argument expression and
/// write out the return expression.
///
/// ```wolfram
/// function = LibraryFunctionLoad[
///     "raw_wstp_function",
///     "wstp_expr_function",
///     LinkObject,
///     LinkObject
/// ];
/// ```
#[no_mangle]
pub extern "C" fn wstp_expr_function(
    _lib: WolframLibraryData,
    mut unsafe_link: WSLINK,
) -> c_uint {
    let link: &mut Link = unsafe { Link::unchecked_ref_cast_mut(&mut unsafe_link) };

    let expr = match link.get_expr() {
        Ok(expr) => expr,
        Err(err) => {
            // Skip reading the argument list packet.
            if link.raw_get_next().and_then(|_| link.new_packet()).is_err() {
                return LIBRARY_FUNCTION_ERROR;
            }

            let err = Expr::string(err.to_string());
            let err = Expr::normal(Symbol::new("System`Failure"), vec![
                Expr::string("WSTP Error"),
                Expr::normal(Symbol::new("System`Association"), vec![Expr::normal(
                    Symbol::new("System`Rule"),
                    vec![Expr::string("Message"), err],
                )]),
            ]);
            match link.put_expr(&err) {
                Ok(()) => return LIBRARY_NO_ERROR,
                Err(_) => return LIBRARY_FUNCTION_ERROR,
            }
        },
    };

    let expr_string = format!("Input: {}", expr.to_string());

    match link.put_expr(&Expr::string(expr_string)) {
        Ok(()) => LIBRARY_NO_ERROR,
        Err(_) => LIBRARY_FUNCTION_ERROR,
    }
}

pub fn symbol<S>(s: S) -> Expr

where S: Into<Symbol>,

Construct a new expression from a Symbol.

pub fn number(num: Number) -> Expr

Construct a new expression from a Number.

Examples found in repository

examples/wstp.rs (line 230)

fn total(args: Vec<Expr>) -> Expr {
    let mut total = Number::Integer(0);

    for (index, arg) in args.into_iter().enumerate() {
        let number = match arg.try_as_number() {
            Some(number) => number,
            None => panic!(
                "expected argument at position {} to be a number, got {}",
                // Add +1 to display using WL 1-based indexing.
                index + 1,
                arg
            ),
        };

        use Number::{Integer, Real};

        total = match (total, number) {
            // If the sum and new term are integers, use integers.
            (Integer(total), Integer(term)) => Integer(total + term),
            // Otherwise, if the either the total or new term are machine real numbers,
            // use floating point numbers.
            (Integer(int), Real(real)) | (Real(real), Integer(int)) => {
                Number::real(int as f64 + *real)
            },
            (Real(total), Real(term)) => Real(total + term),
        }
    }

    Expr::number(total)
}

pub fn string<S>(s: S) -> Expr

where S: Into<String>,

Construct a new expression from a String.

Examples found in repository

examples/exprs/basic_expressions.rs (line 25)

pub fn echo_arguments(args: Vec<Expr>) -> Expr {
    let arg_count = args.len();

    for arg in args {
        // Echo[<arg>]
        wll::evaluate(&Expr::normal(Symbol::new("System`Echo"), vec![arg]));
    }

    Expr::string(format!("finished echoing {} argument(s)", arg_count))
}

examples/docs/evaluate_wolfram_code_from_rust/generate_message.rs (line 13)

fn generate_message(_: Vec<Expr>) {
    // Construct the expression `Message[MySymbol::msg, "..."]`.
    let message = Expr::normal(Symbol::new("System`Message"), vec![
        // MySymbol::msg is MessageName[MySymbol, "msg"]
        Expr::normal(Symbol::new("System`MessageName"), vec![
            Expr::from(Symbol::new("Global`MySymbol")),
            Expr::string("msg"),
        ]),
        Expr::string("a Rust LibraryLink function"),
    ]);

    // Evaluate the message expression.
    let _: Expr = wll::evaluate(&message);
}

examples/exprs/managed.rs (line 86)

fn get_instance_data(args: Vec<Expr>) -> Expr {
    assert!(args.len() == 1, "get_instance_data: expected 1 argument");

    let id: u32 = unwrap_id_arg(&args[0]);

    let MyObject { value } = {
        let instances = INSTANCES.lock().unwrap();

        instances
            .get(&id)
            .cloned()
            .expect("instance does not exist")
    };

    Expr::normal(Symbol::new("System`Association"), vec![Expr::normal(
        Symbol::new("System`Rule"),
        vec![Expr::string("Value"), Expr::string(value)],
    )])
}

examples/raw/raw_wstp_function.rs (lines 104-106)

pub extern "C" fn demo_wstp_function_callback(
    lib: WolframLibraryData,
    mut link: WSLINK,
) -> c_uint {
    // Create a safe Link wrapper around the raw `WSLINK`. This is a borrowed rather than
    // owned Link because the caller (the Kernel) owns the link.
    let link: &mut Link = unsafe { Link::unchecked_ref_cast_mut(&mut link) };

    // Skip reading the argument list packet.
    if link.raw_get_next().and_then(|_| link.new_packet()).is_err() {
        return LIBRARY_FUNCTION_ERROR;
    }

    let callback_link = unsafe { (*lib).getWSLINK.unwrap()(lib) };
    let mut callback_link = callback_link as wstp::sys::WSLINK;

    {
        let safe_callback_link =
            unsafe { Link::unchecked_ref_cast_mut(&mut callback_link) };

        safe_callback_link
            // EvaluatePacket[Print["Hello, World! --- WSTP"]]
            .put_expr(&Expr::normal(Symbol::new("System`EvaluatePacket"), vec![
                Expr::normal(Symbol::new("System`Print"), vec![Expr::string(
                    "Hello, World! --- WSTP",
                )]),
            ]))
            .unwrap();

        unsafe {
            (*lib).processWSLINK.unwrap()(
                safe_callback_link.raw_link() as wll_sys::WSLINK
            );
        }

        // Skip the return value packet. This is necessary, otherwise the link has
        // unread data and the return value of this function cannot be processed properly.
        if safe_callback_link
            .raw_get_next()
            .and_then(|_| safe_callback_link.new_packet())
            .is_err()
        {
            return LIBRARY_FUNCTION_ERROR;
        }
    }

    link.put_expr(&Expr::string("returned normally")).unwrap();

    return LIBRARY_NO_ERROR;
}

/// This example makes use of the [`wstp`][wstp] crate to provide a safe wrapper around
/// around the WSTP link object, which can be used to read the argument expression and
/// write out the return expression.
///
/// ```wolfram
/// function = LibraryFunctionLoad[
///     "raw_wstp_function",
///     "wstp_expr_function",
///     LinkObject,
///     LinkObject
/// ];
/// ```
#[no_mangle]
pub extern "C" fn wstp_expr_function(
    _lib: WolframLibraryData,
    mut unsafe_link: WSLINK,
) -> c_uint {
    let link: &mut Link = unsafe { Link::unchecked_ref_cast_mut(&mut unsafe_link) };

    let expr = match link.get_expr() {
        Ok(expr) => expr,
        Err(err) => {
            // Skip reading the argument list packet.
            if link.raw_get_next().and_then(|_| link.new_packet()).is_err() {
                return LIBRARY_FUNCTION_ERROR;
            }

            let err = Expr::string(err.to_string());
            let err = Expr::normal(Symbol::new("System`Failure"), vec![
                Expr::string("WSTP Error"),
                Expr::normal(Symbol::new("System`Association"), vec![Expr::normal(
                    Symbol::new("System`Rule"),
                    vec![Expr::string("Message"), err],
                )]),
            ]);
            match link.put_expr(&err) {
                Ok(()) => return LIBRARY_NO_ERROR,
                Err(_) => return LIBRARY_FUNCTION_ERROR,
            }
        },
    };

    let expr_string = format!("Input: {}", expr.to_string());

    match link.put_expr(&Expr::string(expr_string)) {
        Ok(()) => LIBRARY_NO_ERROR,
        Err(_) => LIBRARY_FUNCTION_ERROR,
    }
}

pub fn real(real: f64) -> Expr

Construct an expression from a floating-point number.

let expr = Expr::real(3.14159);

Panics

This function will panic if real is NaN.

Examples found in repository

examples/docs/convert/using_expr.rs (line 25)

    fn to_expr(&self) -> Expr {
        let Point { x, y } = *self;

        Expr::normal(Symbol::new("System`Point"), vec![Expr::list(vec![
            Expr::real(x),
            Expr::real(y),
        ])])
    }

pub fn tag(&self) -> Option<Symbol>

Returns the outer-most symbol “tag” used in this expression.

To illustrate:

Expression	Tag
5	None
"hello"	None
foo	foo
f[1, 2, 3]	f
g[x][y]	g

pub fn normal_head(&self) -> Option<Expr>

If this represents a Normal expression, return its head. Otherwise, return None.

pub fn normal_part(&self, index_0: usize) -> Option<&Expr>

Attempt to get the element at index of a Normal expression.

Return None if this is not a Normal expression, or the given index is out of bounds.

index is 0-based. The 0th index is the first element, not the head.

This function does not panic.

pub fn has_normal_head(&self, sym: &Symbol) -> bool

Returns true if self is a Normal expr with the head sym.

pub fn null() -> Expr

Null _WL.

pub fn rule<LHS>(lhs: LHS, rhs: Expr) -> Expr

where LHS: Into<Expr>,

Construct a new Rule[_, _] expression from the left-hand side and right-hand side.

Example

Construct the expression FontSize -> 16:

use wolfram_expr::{Expr, Symbol};

let option = Expr::rule(Symbol::new("System`FontSize"), Expr::from(16));

pub fn rule_delayed<LHS>(lhs: LHS, rhs: Expr) -> Expr

where LHS: Into<Expr>,

Construct a new RuleDelayed[_, _] expression from the left-hand side and right-hand side.

Example

Construct the expression x :> RandomReal[]:

use wolfram_expr::{Expr, Symbol};

let delayed = Expr::rule_delayed(
    Symbol::new("Global`x"),
    Expr::normal(Symbol::new("System`RandomReal"), vec![])
);

pub fn list(elements: Vec<Expr>) -> Expr

Construct a new List[...]({...}) expression from it’s elements.

Example

Construct the expression {1, 2, 3}:

use wolfram_expr::Expr;

let list = Expr::list(vec![Expr::from(1), Expr::from(2), Expr::from(3)]);

Examples found in repository

examples/docs/convert/using_expr.rs (lines 24-27)

    fn to_expr(&self) -> Expr {
        let Point { x, y } = *self;

        Expr::normal(Symbol::new("System`Point"), vec![Expr::list(vec![
            Expr::real(x),
            Expr::real(y),
        ])])
    }

Trait Implementations

impl Clone for Expr

fn clone(&self) -> Expr

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Expr

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for Expr

By default, this should generate a string which can be unambiguously parsed to reconstruct the Expr being displayed. This means symbols will always include their contexts, special characters in String’s will always be properly escaped, and numeric literals needing precision and accuracy marks will have them.

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<&String> for Expr

fn from(s: &String) -> Expr

Converts to this type from the input type.

impl From<&Symbol> for Expr

fn from(sym: &Symbol) -> Expr

Converts to this type from the input type.

impl From<&str> for Expr

fn from(s: &str) -> Expr

Converts to this type from the input type.

impl From<Normal> for Expr

fn from(normal: Normal) -> Expr

Converts to this type from the input type.

impl From<String> for Expr

fn from(s: String) -> Expr

Converts to this type from the input type.

impl From<Symbol> for Expr

fn from(sym: Symbol) -> Expr

Converts to this type from the input type.

impl From<bool> for Expr

fn from(value: bool) -> Expr

Converts to this type from the input type.

impl From<i16> for Expr

fn from(int: i16) -> Expr

Converts to this type from the input type.

impl From<i32> for Expr

fn from(int: i32) -> Expr

Converts to this type from the input type.

impl From<i64> for Expr

fn from(int: i64) -> Expr

Converts to this type from the input type.

impl From<i8> for Expr

fn from(int: i8) -> Expr

Converts to this type from the input type.

impl From<u16> for Expr

fn from(int: u16) -> Expr

Converts to this type from the input type.

impl From<u32> for Expr

fn from(int: u32) -> Expr

Converts to this type from the input type.

impl From<u8> for Expr

fn from(int: u8) -> Expr

Converts to this type from the input type.

impl Hash for Expr

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq<Symbol> for Expr

fn eq(&self, other: &Symbol) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for Expr

fn eq(&self, other: &Expr) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Expr

impl StructuralPartialEq for Expr