extend substitute syntax to more than one pair; add call method conve…

[jverzani]

Extends the substitute syntax to multiple pairs of Pairs

Adds call syntax for symbolic expression when called with Pairs.

Again, I didn't include any tests, but can if you want.

[s-celles]

Maybe we should simply add doctests for all of this.
This is "lighter" than testset from Test.jl and provide both doc and test

Related #3

[s-celles]

Doctest such as
4785235#diff-5223be791c850df6b50e8950a30d18af4e58e429c96f51a52a9a743165a4f91dR21-R23
could probably be used here as it both documents code and test it

[s-celles]

We should ensure that

substitute(expr, x => y, y => x) 

give similar result than

substitute(expr, Dict(x => y, y => x))

See

julia> expr = x + 2*y
GiacExpr: x+2*y

julia> Giac.substitute(expr, Dict(x => y, y => x))
GiacExpr: y+2*x

julia> function substitute(expr, pairs...)
for p in pairs
expr = substitute(expr, p)
end
expr
end
substitute (generic function with 2 methods)

julia> substitute(expr, x => y, y => x)
Warning: detected a stack overflow; program state may be corrupted, so further execution might be unreliable.
ERROR: StackOverflowError:
Stacktrace:
[1] substitute(expr::GiacExpr, pairs::Pair{GiacExpr, GiacExpr})
@ Main ./REPL[2]:1
[2] substitute(expr::GiacExpr, pairs::Pair{GiacExpr, GiacExpr}) (repeats 79983 times)
@ Main ./REPL[2]:3

We should also take care of order as Julia Dict don't preserve insertion order.

on the other side I don't think such method prototype exists in Symbolics.jl...

julia> using Symbolics

julia> methods(Symbolics.substitute)
# 1 method for generic function "substitute" from SymbolicUtils:
[1] substitute(expr, dict; fold, filterer)
@ ~/.julia/packages/SymbolicUtils/uHteK/src/substitute.jl:261

help?> Symbolics.substitute
substitute(expr, dict; fold=Val(false))

substitute any subexpression that matches a key in dict with the corresponding value. If fold=Val(false), expressions which can be evaluated won't be evaluated.

julia> substitute(1+sqrt(y), Dict(y => 2), fold=Val(true))
2.414213562373095
julia> substitute(1+sqrt(y), Dict(y => 2), fold=Val(false))
1 + sqrt(2)

─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

substitute(expr, s; fold=Val(false))

Performs the substitution on expr according to rule(s) s. If fold=Val(true), expressions which can be fully evaluated will be evaluated to a number.

│ Does not penetrate `Differential`
│
│  As of Symbolics.jl v7 (SymbolicUtils.jl v4), substitute does not recurse into the arguments of Differential expressions. For example, substitute(D(x), Dict(x => y)) returns D(x), not D(y). Use
│  substitute_in_deriv or substitute_in_deriv_and_depvar to substitute inside Differential applications.

Examples
≡≡≡≡≡≡≡≡

julia> @variables t x y z(t)
4-element Vector{Num}:
t
x
y
z(t)
julia> ex = x + y + sin(z)
(x + y) + sin(z(t))
julia> substitute(ex, Dict([x => z, sin(z) => z^2]))
(z(t) + y) + (z(t) ^ 2)
julia> substitute(sqrt(2x), Dict([x => 1]))
sqrt(2)
julia> substitute(sqrt(2x), Dict([x => 1]); fold=Val(true))
1.4142135623730951

I even wonder if all this string based version of substitute shouldn't be written using

 Giac.Commands.subst(expr, [x, y], [y, x])

[s-celles]

Closing this PR as I think all features have been implemented in #13
Thanks @jverzani for this idea of call method convention it should simplify usage.

[jverzani]

Great. Thanks