## `extsubsop` -- substitute operands of a domain element

#### Introduction

`extsubsop``(d, i = new)` returns a copy of the domain element `d` with the `i`-th operand of the internal representation replaced by `new`.

#### Call(s)

`extsubsop(d, i1 = new1, i2 = new2...)`

#### Parameters

`d` | - | an element of a library domain
`i1, i2...` | - | nonnegative integers
`new1, new2...` | - | arbitrary MuPAD objects

#### Returns

the input object with replaced operands.

#### Related Functions

`DOM_DOMAIN`, `extnops`, `extop`, `new`, `nops`, `op`, `subs`, `subsex`, `subsop`

#### Details

- Internally, a domain element may consist of an arbitrary number of objects. `extsubsop` replaces one or more of these objects, without checking whether the substitution is meaningful.

  The operands of elements of domains of the MuPAD library must meet certain (undocumented) conditions; use `extsubsop` only for your own domains. It is good programming style to use `extsubsop` only inside low-level domain methods.

- `extsubsop` returns a modified copy of the object, but does not change the object itself.
- The numbering of operands is the same as the one used by `extop`.
- If the 0-th operand is to be replaced, the corresponding new value must be a domain of type `DOM_DOMAIN`; `extsubsop` then replaces the domain of `d` by this new domain.
- When trying to replace the `i`-th operand with `i` exceeding the actual number of operands, `extsubsop` first increases the number of operands by appending as many `NIL`'s as necessary and then performs the substitution. Cf. example 3.
- When the `i`-th operand is replaced by an expression sequence of `k` elements, each of these elements becomes an individual operand of the result, indexed from `i` to `i+k-1`. The remaining operands of `d` are shifted to the right accordingly. This new numbering is already in effect for the remaining substitutions in the same call to `extsubsop`. Cf. example 4.
- The void object `null()` becomes an operand of the result when it is substituted into an object.
- After performing the substitution, `extsubsop` does not evaluate the result once more. Cf. example 5.
- In contrast to the function `subsop`, `extsubsop` cannot be overloaded.
- Unlike `extop` and `extnops`, `extsubsop` cannot be applied to objects of a kernel domain.
- `extsubsop` is a function of the system kernel.

#### Example 1

We create a domain element and then replace its first operand:

    >> d := newDomain("1st"): e := new(d, 1, 2, 3): extsubsop(e, 1 = 5)

                                 new(1st, 5, 2, 3)

This does not change the value of `e`:

    >> e

                                 new(1st, 1, 2, 3)

    >> delete d, e:

#### Example 2

The domain type of an element can be changed by replacing its 0-th operand:

    >> d := newDomain("some_domain"): e := new(d, 2):
       extsubsop(e, 0 = Dom::IntegerMod(5))

                                      2 mod 5

    >> delete d, e:

#### Example 3

We substitute the sixth operand of a domain element that has less than six operands. In such cases, an appropriate number of `NIL`'s is inserted:

    >> d := newDomain("example"): e := new(d, 1, 2, 3, 4):
       extsubsop(e, 6 = 8)

                         new(example, 1, 2, 3, 4, NIL, 8)

    >> delete d, e:

#### Example 4

We substitute the first operand of a domain element `e` by a sequence with three elements. These become the first three operands of the result; the second operand of `e` becomes the fourth operand of the result, and so on. This new numbering is already in effect when the second substitution is carried out:

    >> d := newDomain("example"): e := new(d, 1, 2, 3, 4):
       extsubsop(e, 1 = (11, 13, 17), 2 = (29, 99))

                       new(example, 11, 29, 99, 17, 2, 3, 4)

    >> delete d, e:

#### Example 5

We define a domain with its own evaluation method. This method prints out its argument such that we can see whether it is called. Then we define an element of our domain.

    >> d := newDomain("anotherExample"):
       d::evaluate := x -> (print("Argument:", x); x):
       e := new(d, 3)

                              new(anotherExample, 3)

We can now watch all evaluations that happen: `extsubsop` evaluates its arguments, performs the desired substitution, but does not evaluate the result of the substitution:

    >> extsubsop(e, 1 = 0)

                        "Argument:", new(anotherExample, 3)

                              new(anotherExample, 0)

    >> delete d, e:

#### Changes

- no changes

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