# subsop

Replace operands

### Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

## Syntax

```subsop(`object`, `i1 = new1, i2 = new2, …`, <Unsimplified>)
```

## Description

`subsop` returns a modified copy of the object, but does not change the object itself.

`subsop(object, i = new)` replaces the operand ```op(object, i)``` by `new`. Operands are specified in the same way as with the function `op`: `i` may be an integer or a list of integers. E.g., `subsop(object, [j, k] = new)` replaces the suboperand `op(op(object, j), k)`. Cf. Example 2. In contrast to `op`, ranges cannot be used in `subsop` to specify more than one operand to replace. Several substitution equations have to be specified instead.

If several operands are to be replaced, the specified substitutions are processed in sequence from left to right. Each substitution is carried out and the result is processed further with the next substitution. The intermediate objects are not simplified.

The result of `subsop` is not evaluated further. It can be evaluated via the function `eval`. Cf. Example 3.

Operands of expression sequences can be replaced by `subsop`. Such objects are not flattened.

Note that the order of the operands may change by replacing operands and evaluating the result. Cf. Example 4.

`FAIL` is returned if an operand cannot be accessed.

Substitution via `subsop` is faster than via `subs` or `subsex`.

The call `subsop(object)` is allowed; it returns the object without modifications.

## Examples

### Example 1

We demonstrate how to replace one or more operands of an expression:

`x := a + b: subsop(x, 2 = c)`

`subsop(x, 1 = 2, 2 = c)`

Also the 0-th operand of an expression (the "operator") can be replaced:

`subsop(x, 0 = _mult)`

The variable `x` itself was not affected by the substitutions:

`x`

`delete x:`

### Example 2

The following call specifies the suboperand `c` by a list of integers:

`subsop([a, b, f(c)], [3, 1] = x)`

### Example 3

This example demonstrates the effect of simplification. The following substitution replaces the first operand `a` by 2. The result simplifies to 3:

`subsop(a + 1, 1 = 2)`

The option `Unsimplified` suppresses the simplification:

`subsop(a + 1, 1 = 2, Unsimplified)`

The next call demonstrates the difference between simplification and evaluation. After substitution of `PI` for `x`, the identifier `sin` is not evaluated, i.e., the body of the system function `sin` is not executed:

`subsop(sin(x), 1 = PI)`

Evaluation of `sin` simplifies the result:

`eval(%)`

### Example 4

The order of operands may change by substitutions. Substituting `z` for the identifier `b` changes the internal order of the terms in `x`:

`x := a + b + c: op(x)`

`x := subsop(x, 2 = z): op(x)`

`delete x:`

## Parameters

 `object` Any MuPAD® object `i1, i2, …` Integers or lists of integers `new1, new2, …` Arbitrary MuPAD objects

## Options

 `Unsimplified` As the last step of a substitution, the modified object is simplified (however, not evaluated). This option suppresses this final simplification. Cf. Example 3.

## Return Values

Input object with replaced operands or `FAIL`.

`object`

## Algorithms

For overloading `subsop`, it is sufficient to handle the cases `subsop(object)` and ```subsop(object, i = new)```.

The case where the position of the operand to be replaced is given by a list is always handled recursively: First, `op` is called with the list bar the last element to find the object to substitute in (using the overloading of `op` if present, storing all the intermediate results), then the substitution is performed on that sub-object (using the overloading of `subsop` of the form `subsop(subobj, i = new)`). The result is substituted into the last-but-one result of the recursive `op` call, again respecting any overloading of `subsop`, and so on up to the front of the list.