## `subsop` -- replace operands

#### Introduction

`subsop(`object, i = new`)` returns a copy of the object in which the `i`-th operand is replaced by the value `new`.

#### Call(s)

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

#### Parameters

`object` | - | any MuPAD object
`i1, i2...` | - | integers or lists of integers
`new1, new2...` | - | arbitrary MuPAD objects

#### Options

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

#### Returns

the input object with replaced operands or `FAIL`.

### Overloadable:

`object`

#### Related Functions

`extnops`, `extop`, `extsubsop`, `map`, `match`, `op`, `subs`, `subsex`

#### Details

- `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.
- `subsop` 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. Cf. example 3.

#### Example 1

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

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

                                       a + c

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

                                       c + 2

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

    >> subsop(x, 0 = _mult)

                                        a b

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

    >> x

                                       a + b

    >> delete x:

#### Example 2

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

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

                                   [a, b, f(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)

                                         3

The option Unsimplified suppresses the simplification:

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

                                       2 + 1

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)

                                      sin(PI)

Evaluation of `sin` simplifies the result:

    >> eval(%)

                                         0

#### 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)

                                      a, b, c

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

                                      a, c, z

    >> delete x:

#### Background

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

#### Changes

- no changes

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