## `subsex` -- extended substitution

#### Introduction

`subsex(`f, old = new`)` returns a copy of the object `f` in which all expressions matching `old` are replaced by the value `new`. In contrast to the function `subs`, `subsex` also replaces ``incomplete'' subexpressions.

#### Call(s)

`subsex(f, old = new <, Unsimplified>)`
`subsex(f, old1 = new1, old2 = new2... <, Unsimplified>)`
`subsex(f, [old1 = new1, old2 = new2...] <, Unsimplified>)`
`subsex(f, {old1 = new1, old2 = new2...} <, Unsimplified>)`
`subsex(f, table(old1 = new1, old2 = new2...) <, Unsimplified>)`
`subsex(f, s1, s2... <, Unsimplified>)`

#### Parameters

`f` | - | an arbitrary MuPAD object
`old, old1, old2, ...` | - | arbitrary MuPAD objects
`new, new1, new2, ...` | - | arbitrary MuPAD objects
`s1, s2, ...` | - | either equations `old = new`, or lists or sets of such equations, or tables whose entries are interpreted as such equations.

#### Options

`Unsimplified` | - | prevents simplification of the returned object after substitution

#### Returns

a copy of the input object with replaced operands.

### Overloadable:

`f`

#### Related Functions

`extnops`, `extop`, `extsubsop`, `has`, `map`, `match`, `op`, `subs`, `subsop`

#### Details

- `subsex` returns a modified copy of the object, but does not change the object itself.
- `subsex(`f, old = new`)` searches `f` for subexpressions matching `old`. Each such subexpression is replaced by `new`.
- In most cases, `subsex` leads to the same result as `subs`. However, in contrast to `subs`, `subsex` allows to replace ``incomplete'' subexpressions such as `a + b` in a sum `a + b + c`. In general, combinations of the operands of the n-ary ``operators'' `+`, `*`, `and`, `_exprseq`, `intersect`, `or`, `_lazy_and`, `_lazy_or`, and `union` can be replaced. In particular, partial sums and partial products can be replaced. Note that these operations are assumed to be commutative, e.g., `subsex(`a*b*c, a*c = new`)` does replace the partial product `a*c` by `new`. Cf. examples 1 and 2.
- `subsex` is much slower than `subs`! If `subs` can do the substitution, use `subs` rather than `subsex`.
- The call `subsex(`f, old1 = new1, old2 = new2, ...`)` invokes a ``sequential substitution''. See the `subs` help page for details.
- The call `subsex(`f, [old1 = new1, old2 = new2, ...]`)` invokes a ``parallel substitution''. See the `subs` help page for details.
- The call `subsex(`f, s1, s2, ...`)` describes the most general form of substitution which may combine sequential and parallel substitutions. This call is equivalent to `subsex(... subsex(subsex(f, s1), s2), ...)`. Depending on the form of `s1`, `s2`, ..., sequential or parallel substitutions are carried out in each step. An example can be found on the `subs` help page.
- After substitution, the result is not evaluated. Use the function `eval` to enforce evaluation. Cf. example 3.
- Operands of expression sequences can be replaced by `subsex`. Such objects are not flattened. Cf. example 4.
- The call `subsex(`f`)` is allowed; it returns `f` without modifications.
- `subsex` is a function of the system kernel.

#### Option: Unsimplified

- As the last step of a substitution, the modified object is simplified (however, not evaluated). This option suppresses this final simplification. An example can be found on the `subs` help page.

#### Example 1

We demonstrate some simple substitutions; `subsex` finds and replaces partial sums and products:

    >> subsex(a + b + c, a + c = x)

                                       b + x

    >> subsex(a*b*c, a*c = x)

                                        b x

    >> subsex(a * (b + c) + b + c, b + c = a)

                                           2
                                      a + a

    >> subsex(a + b*c*d + b*d, b*d = c);

                                             2
                                    a + c + c

#### Example 2

We replace subexpressions inside an expression sequence and a symbolic union of sets:

    >> subsex((a, b, c, d), (b, d) = w)

                                      a, c, w

    >> subsex(a union b union c, a union b = w)

                                     c union w

The same can be achieved by using the functional equivalent `_union` of the operator `union`:

    >> subsex(_union(a, b, c), _union(a, b) = w)

                                     c union w

#### Example 3

The result of `subsex` is not evaluated. In the following call, the identifier `sin` is not replaced by its value, i.e., by the procedure defining the behavior of the system's sine function. Consequently, `sin(2*PI)` is not simplified to 0 by this procedure:

    >> subsex(sin(2*x*y), x*y = PI)

                                     sin(2 PI)

The function `eval` enforces evaluation:

    >> eval(subsex(sin(2*x*y), x*y = PI))

                                         0

#### Example 4

Operands of expression sequences can be subtituted. Note that sequences need to be enclosed in brackets:

    >> subsex((a, b, a*b*c), a*b = x)

                                     a, b, c x

#### Example 5

The option Unsimplified suppresses simplification:

    >> subsex(2 + a + b, a + b = 0, Unsimplified)

                                       2 + 0

#### Changes

- `subsex` does not longer substitute inside domains. For further information see the `subs` help page.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000