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) -> ExpressionIntern a symbol and (optionally) attach assumptions used by the assumption
engine and the simplifier. Domain flags refine in the order natural
integer rational 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,
) -> ExpressionBuild 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.
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) -> ExpressionProvides 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 SymbolDeclarationPublic 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.