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>

👎Deprecated:

use <&Normal>::try_from(expr) instead

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

Migration

let normal: Option<&Normal> = <&Normal>::try_from(&expr).ok();

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

👎Deprecated:

use bool::try_from(expr) instead

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

Migration

let is_true_or_false: Option<bool> = bool::try_from(&expr).ok();

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

👎Deprecated:

use <&str>::try_from(expr) instead

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

Migration

let s: Option<&str> = <&str>::try_from(&expr).ok();

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

👎Deprecated:

use <&Symbol>::try_from(expr) instead

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

Migration

let sym: Option<&Symbol> = <&Symbol>::try_from(&expr).ok();

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

👎Deprecated:

use i64::try_from(expr) / f64::try_from(expr) instead

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

Migration

let int: Option<i64> = i64::try_from(&expr).ok();
let real: Option<f64> = f64::try_from(&expr).ok();

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

👎Deprecated:

use <&Normal>::try_from(expr) instead

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

👎Deprecated:

use <&Symbol>::try_from(expr) instead

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

👎Deprecated:

use i64::try_from(expr) / f64::try_from(expr) 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/exprs/managed.rs (line 58)

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!({ "Value" -> 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),
    }
}

examples/wstp.rs (line 179)

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

    let ExprKind::Normal(list) = expr.kind() else {
        panic!("expected a List, got: {:?}", expr);
    };
    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()
}

//======================================
// Using `Vec<Expr>` argument list
//======================================

//------------------
// total()
//------------------

#[wll::export(wstp)]
fn total(args: Vec<Expr>) -> Expr {
    let mut total = 0.0f64;
    for (index, arg) in args.into_iter().enumerate() {
        total += match arg.kind() {
            ExprKind::Integer(n) => *n as f64,
            ExprKind::Real(f) => f64::from(*f),
            _ => panic!(
                "expected argument at position {} to be a number, got {}",
                index + 1,
                arg
            ),
        };
    }
    Expr::from(total)
}

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.

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

where S: Into<Symbol>,

Construct a new expression from a Symbol.

pub fn number(num: Number) -> Expr

👎Deprecated since 0.6.0-alpha.3:

use Expr::from(i64) or Expr::from(f64) instead

Construct a new expression from a Number.

Migration

// Expr::number(Number::Integer(42))
let _int = Expr::from(42_i64);

// Expr::number(Number::real(3.14))
let _real = Expr::from(3.14_f64);  // or Expr::real(3.14)

// Expr::number(Number::Real(f))  — when you already have an F64
let f = F64::new(3.14).unwrap();
let _real = Expr::new(ExprKind::Real(f));

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!(System::Echo[arg]));
    }

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

examples/raw/raw_wstp_function.rs (line 125)

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!(
                System::EvaluatePacket[System::Print["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 msg = err.to_string();
            let err = wolfram_library_link::expr::expr!(
                System::Failure["WSTP Error", {"Message" -> msg}]
            );
            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.

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)]);

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

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

Formats the value using the given formatter.

impl Eq for Expr

impl From<&LibraryError> for Expr

fn from(__value: &LibraryError) -> 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<&str> for Expr

fn from(s: &str) -> Expr

Converts to this type from the input type.

impl From<ArrayBuf<NumericArrayEnum>> for Expr

fn from(a: ArrayBuf<NumericArrayEnum>) -> Expr

Converts to this type from the input type.

impl From<ArrayBuf<PackedArrayEnum>> for Expr

fn from(a: ArrayBuf<PackedArrayEnum>) -> Expr

Converts to this type from the input type.

impl From<BigInteger> for Expr

fn from(n: BigInteger) -> Expr

Converts to this type from the input type.

impl From<BigReal> for Expr

fn from(r: BigReal) -> Expr

Converts to this type from the input type.

impl From<LibraryError> for Expr

fn from(__value: LibraryError) -> 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<Vec<Expr>> for Expr

fn from(v: Vec<Expr>) -> Expr

Converts to this type from the input type.

impl From<Vec<RuleEntry>> for Expr

fn from(a: Vec<RuleEntry>) -> Expr

Converts to this type from the input type.

impl From<Vec<u8>> for Expr

fn from(b: Vec<u8>) -> 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<f64> for Expr

fn from(f: f64) -> 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<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<u8> for Expr

fn from(int: u8) -> 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<'de> FromWXF<'de> for Expr

fn from_wxf<R>(r: &mut WxfReader<R>) -> Result<Self, Error>

where R: Reader<'de>,

Read a complete value: its expression token, then its body.

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 Ord for Expr

fn cmp(&self, other: &Expr) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Expr

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

Equality operator ==.

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

Inequality operator !=.

impl PartialEq<Symbol> for Expr

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for Expr

fn partial_cmp(&self, other: &Expr) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralPartialEq for Expr

impl ToWXF for Expr

fn to_wxf<W>(&self, w: &mut WxfWriter<W>) -> Result<(), Error>

where W: Writer,

Write self to w as a complete WXF value (tag + payload).

impl<'e> TryFrom<&'e Expr> for &'e str

fn try_from(expr: &'e Expr) -> Result<&'e str, &'e Expr>

If this is an ExprKind::String expression, return that.

let expr = expr!("hello");
let s = <&str>::try_from(&expr).unwrap();
assert_eq!(s, "hello");

type Error = &'e Expr

The type returned in the event of a conversion error.

impl<'e> TryFrom<&'e Expr> for &'e Symbol

fn try_from(expr: &'e Expr) -> Result<&'e Symbol, &'e Expr>

If this is a Symbol expression, return that.

let expr = expr!(System::Pi);
let sym = <&Symbol>::try_from(&expr).unwrap();
assert_eq!(sym.as_str(), "System`Pi");

type Error = &'e Expr

The type returned in the event of a conversion error.

impl<'e> TryFrom<&'e Expr> for &'e Normal

fn try_from(expr: &'e Expr) -> Result<&'e Normal, &'e Expr>

If this is a Normal expression, return that.

let expr = expr!(System::List[1, 2, 3]);
let normal = <&Normal>::try_from(&expr).unwrap();
assert_eq!(normal.elements().len(), 3);

type Error = &'e Expr

The type returned in the event of a conversion error.

impl WxfStruct for Expr