Skip to content
Symi Docs
Rust

The Rust manual covers the recommended facade. The complete native crate is documented in the native Rust API reference.

On this page

Construction and parsing

Build expressions, matrices, geometry values, and callable functions from exact host values or parsed text. Every value belongs to the context that created it.

Context lifecycle#

new#

context() (Python) / new context() (JS)

Create a fresh context with an empty symbol table and expression store.

reset_context#

api::Session method

pub fn reset_context(&self) -> Result<(), ApiError>

Replace the context's entire symbol table and expression store with fresh empty ones. Warning: existing Expression/Matrix/geometry objects from this context become stale and must not be used afterwards — their symbol identifiers no longer resolve. Deliberately not available at module level: resetting the shared default context would strand every live object, and the weak expression store already keeps memory bounded by live objects (see the default context).

Parsing and building#

parse#

api::Session method

pub fn parse(&self, text: &str) -> Result<Expression, ApiError>

Parse Symi textual syntax into an expression. Accepts ^ and ** for powers; knows the builtin function names (sin, log, sqrt, …) and the constants pi, e. Raises on syntax errors and on meta-command input. Parsing is always explicit: strings are not converted by expression-like parameters.

parse_latex#

api::serialization::Session method

pub fn parse_latex(
    &self,
    latex: &str,
) -> Result<MathematicalObject, ApiError>

Parse a LaTeX string in Symi's canonical input dialect — the inverse of to_latex and the parser the Symi frontend uses. Returns whichever top-level object the input denotes: an ordinary expression, a \begin{matrix}…\end{matrix}, or a geometry figure ((x, y) point, segment, polygon, or circle), wrapped in the matching exported class exactly as parse_serialized_object does. Coverage spans arithmetic, powers, fractions, roots, the elementary and many special functions, comparisons, integrals (including the bare-d differential), Leibniz derivatives (\frac{d}{dx} — differentiated eagerly), limits, summations, products, determinants, and actuarial annuities. The resolution is context-aware in a way parse is not: a bare i is the imaginary unit and a bare e is Euler's number unless the letter is a bound index (a summation / product / limit index shadows the constant), and \mathrm{d} — or a bare d that closes an integral — is the differential operator while a bare d elsewhere is an ordinary variable. Raises on syntax errors.

MathQuill-style one-character scripts may be bare or braced. For example, \int_a^2 xdx, \sum_{i=1}^a i, \prod_{i=1}^a i, \sin^a(x), and \log_a(x) are equivalent to their braced forms. General script expressions remain braced, such as \log_{a+1}(x). Binder variables shadow definitions in their bodies, while free names in bounds remain available for environment expansion.

parse_latex_with_environment#

api::serialization::Session method

pub fn parse_latex_with_environment(
    &self,
    latex: &str,
    serialized_definitions: &[String],
) -> Result<MathematicalObject, ApiError>

Parse LaTeX after building an ordered definition environment. Each serialized definition is a string with four fields separated by ASCII Unit Separator (U+001F): kind, name, parameters, and body_latex. kind is object or function; object parameters are empty, while function parameters are separated by ASCII Record Separator (U+001E). For example, object\x1fa\x1f\x1f5 followed by function\x1ff\x1fx\x1fx^2 makes f(a) parse to 25. Definitions are parsed in list order using the environment accumulated so far. The delimiters are rejected inside fields. Also available as a module-level function.

symbol#

api::Session method

pub fn symbol(&self, name: &str) -> Expression

Intern a symbol and (optionally) attach assumptions used by the assumption engine and the simplifier. Domain flags refine in the order natural →\to integer →\to rational →\to real; positive/negative also set nonzero, and nonzero may be requested independently.

Notes: assumptions are per-context, per-name, and sticky: re-interning the same name keeps previously set assumptions, and a refinement applies retroactively to every existing expression containing the symbol. Refinement is monotonic — strengthening an unknown property is allowed; contradicting an earlier declaration (e.g. positive=True after negative=True, or widening the domain) raises an error naming the clash. Use clear_assumptions to start a symbol over.

integer#

api::Session method

pub fn integer<IntegerType: ExactIntegerInput>(
    &self,
    value: IntegerType,
) -> Expression

Build an arbitrary-precision exact integer. Python bool values are rejected. JavaScript's recommended facade accepts bigint and safe integral number values.

rational#

api::Session method

pub fn rational<NumeratorType: ExactIntegerInput, DenominatorType: ExactIntegerInput>(
    &self,
    numerator: NumeratorType,
    denominator: DenominatorType,
) -> Result<Expression, ApiError>

Constructs an exact reduced rational from arbitrary-size integers. A zero denominator is an argument error. Python also accepts fractions.Fraction wherever an expression-like input is accepted.

integer_from_string#

api::Session method

pub fn integer_from_string(
    &self,
    text: &str,
) -> Result<Expression, ApiError>

Build an arbitrary-precision integer literal from its decimal string.

Named unknown functions are built with undefined_function, whose handle, calls, and structural derivatives are documented together in Undefined functions.

Example#

Build the same expression from a literal, a parse, and exact numeric constructors.

Rust
use symi::api::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let session = Session::new();
    let x = session.symbol("x");

    println!("{}", session.parse("x^2 + 2*x + 1")?);
    println!("{}", session.power(&x, &session.integer(2))?);
    println!("{}", session.rational(2, 3)?);
    Ok(())
}

Additional API#

api::input#

api module

pub mod input;

Binding-neutral input types resolved by the native API.

integer_from_decimal#

api::Session method

pub fn integer_from_decimal(
    &self,
    text: &str,
) -> Result<Expression, ApiError>

Constructs an exact integer expression from a base-ten literal.

rational_from_decimal#

api::Session method

pub fn rational_from_decimal(
    &self,
    text: &str,
) -> Result<Expression, ApiError>

Constructs an exact rational expression from a base-ten integer or fraction literal.

rational_value#

api::Session method

pub fn rational_value(&self, value: exact_rational) -> Expression

Provides the rational_value operation on this native type.

variable_identifiers#

api::Session method

pub fn variable_identifiers<'a, IteratorType, VariableType>(
    &self,
    variables: IteratorType,
) -> Result<Vec<crate::symbol::SymbolIdentifier>, ApiError>
where
    IteratorType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,

Resolve a collection of variable operands to interned symbol identifiers.

SymbolDeclaration#

Type

pub struct SymbolDeclaration

Public native trait named exact_integer_input. The scalar facts a binding may attach to a symbol at interning time.

SymbolDeclaration.finite#

api::SymbolDeclaration field

pub finite:

Declares the symbol finite.

SymbolDeclaration.integer#

api::SymbolDeclaration field

pub integer:

Declares the symbol an integer.

SymbolDeclaration.natural#

api::SymbolDeclaration field

pub natural:

Declares the symbol a natural number.

SymbolDeclaration.negative#

api::SymbolDeclaration field

pub negative:

Declares the symbol negative.

SymbolDeclaration.nonzero#

api::SymbolDeclaration field

pub nonzero:

Declares the symbol nonzero.

SymbolDeclaration.positive#

api::SymbolDeclaration field

pub positive:

Declares the symbol positive.

SymbolDeclaration.rational#

api::SymbolDeclaration field

pub rational:

Declares the symbol rational.

SymbolDeclaration.real#

api::SymbolDeclaration field

pub real:

Declares the symbol real.