## `builtin` -- representatives of C-functions of the MuPAD kernel

#### Introduction

`builtin` represents a C-function of the system kernel.

#### Call(s)

`builtin(i, j, str, tbl)`
`builtin(i, j1, str1, str)`

#### Parameters

`i` | - | a number corresponding to a C-function of the kernel: a nonnegative integer
`j` | - | a number corresponding to a C-function of the kernel: a nonnegative integer or `NIL`
`str` | - | the name of the created `DOM_EXEC` object: a character string
`tbl` | - | the remember table of the function: a table or `NIL`
`j1` | - | the precedence of an operator: a nonnegative integer
`str1` | - | the operator symbol: a character string or `NIL`

#### Returns

an object of type `DOM_EXEC`.

#### Related Functions

`funcenv`

#### Details

- `builtin` is only intended for internal use! A user is not supposed to call this low-level function.

- The function `builtin` provides an interface between the MuPAD language and the C-functions of the MuPAD kernel. The MuPAD functions returned by `builtin` are elements of the basic type `DOM_EXEC`. They may only be used as first or second entry of `function environments` created by `funcenv`.
- Functions used as the first argument in `funcenv` serve for evaluating function calls of the function environment. A kernel function serving this purpose must be produced by a call `builtin(`i, j, str, tbl`)`. The string `str` is used for the ouput of symbolic calls of the kernel function. The table `tbl` is the remember table. Cf. example 2. If `NIL` is used, no remember table is associated with the function.
- Functions used as the second argument in `funcenv` determine the output of symbolic function calls. A kernel function serving this purpose must be produced by a call `builtin(`i, j1, str1, str`)`. The number `j1` defines the output priority of the function. If symbolic function calls are to be presented in operator notation, the string `str1` is used as the operator symbol. Cf. example 3. `NIL` must be used if the function does not represent an operator. The string `str` is used for the output of the `DOM_EXEC` object itself.
- `builtin` is a function of the system kernel.

#### Example 1

The operands of a function environment such as `_mult` can be viewed by `expose`. The following two kernel functions are in charge of evaluating products and displaying the result on the screen, respectively:

    >> expose(op(_mult, 1)), expose(op(_mult, 2))

          builtin(815, NIL, "_mult", NIL),

             builtin(1100, 15, "*", "_mult")

    >> _mult(a, b) = builtin(815, NIL, "_mult", NIL)(a, b)

                                     a b = a b

#### Example 2

We demonstrate that it is possible to manipulate the remember table of kernel functions. The function environment `isprime` uses a C-function of the kernel to evaluate its argument:

    >> expose(isprime)

                        builtin(1000, 1305, "isprime", NIL)

It does not regard 1 as a prime number:

    >> isprime(1)

                                       FALSE

We unprotect the system function and associate the value `TRUE` with the call `isprime(1)`:

    >> unprotect(isprime): isprime(1) := TRUE:

The value is stored in the remember table. This is the fourth entry of the builtin function evaluating the arguments of `isprime`:

    >> expose(isprime)

                          /                        table(      \
                   builtin| 1000, 1305, "isprime",   1 = TRUE  |
                          \                        )           /

After this modification, `isprime` regards 1 as a prime number:

    >> isprime(1)

                                       TRUE

We restore the original behavior of `isprime` by substituting the original value `NIL` of the remember table:

    >> isprime := subsop(isprime, [1, 4] = NIL): protect(isprime):

    >> isprime(1)

                                       FALSE

#### Example 3

We demonstrate how the output symbol of the kernel function `_power` can be changed. This function is in charge of representing powers:

    >> op(a^b, 0), _power(a, b)

                                             b
                                    _power, a

The second operand of the function environment `_power` is the builtin function that determines the output:

    >> expose(op(_power,2))

                         builtin(1100, 16, "^", "_power")

The third operand of this object is the symbol that is used for representing symbolic powers. We want to replace it by `**`. However, since the system function `_power` is protected, we have to apply `unprotect` before we can modify the function environment:

    >> unprotect(_power): _power := subsop(_power, [2, 3] = "**"):

    >> expose(op(_power,2)), a^b

                      builtin(1100, 16, "**", "_power"), a**b

We restore the original behavior of `_power`:

    >> _power := subsop(_power, [2, 3] = "^"):  protect(_power):

#### Changes

- used to be called `built_in`

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