Documentation

Verify Options

MuPAD® notebooks will be removed in a future release. Use MATLAB® live scripts instead.

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.

For many standard MuPAD® procedures, you can use different options. If a MuPAD procedure accepts options, it has an embedded mechanism for collecting and verifying these options. For example, the `solve` function accepts the `Real` option. The option indicates that the solver must return only real solutions and accepts the values `TRUE` and `FALSE`. If an option accepts only `TRUE` and `FALSE` values, you can provide the option name without specifying its value:

`solve(x^4 - 1 = 0, x, Real)`

If you do not specify the `Real` option, the solver uses the default option value `FALSE`, and returns all complex solutions of the equation:

`solve(x^4 - 1 = 0, x)`

You can explicitly specify the option-value pair, for example, ```Real = TRUE``` or `Real = FALSE`:

```solve(x^4 - 1 = 0, x, Real = TRUE); solve(x^4 - 1 = 0, x, Real = FALSE)```

If you provide an unexpected option (for example, if you spell the option name incorrectly), MuPAD issues an error indicating the wrong option. If there are several wrong options, MuPAD indicates the first wrong option:

`solve(x^4 - 1 = 0, x, Rea, Rel)`
```Error: Invalid argument number 3. Evaluating: solvelib::getOptions ```

You can embed the same option checking mechanism in your own procedures. For this task, MuPAD provides the `prog::getOptions` function, which collects and verifies options used during a procedure call. When a user calls your procedure, `prog::getOptions` scans all arguments and returns a table that contains all expected options and their values. It also returns a list of all unexpected options.

When you pass arguments to `prog::getOptions`, always use the following order. The first argument of `prog::getOptions` is the number `n + 1`, where `n` is the number of required (non-optional) arguments of the procedure. Then you must provide the list of all actual arguments followed by the table of all acceptable options and their default values. To access a sequence of all arguments of a procedure call, including required arguments and options, use the `args` function.

The following example demonstrates the procedure that accepts the numeric coefficients `a`, `b`, and `c` and solves the quadratic equation ax2 + bx + c = 0 using these coefficients. The procedure `solveQuadraticEqn` requires the user to provide three numeric values. Therefore, if you embed `prog::getOptions` into this procedure, the first parameter of `prog::getOptions` must be the number 4. The procedure also accepts the optional argument `PositiveOnly`. If the value of `PositiveOnly` is `TRUE`, the procedure returns only positive solutions of the quadratic equation. If the value is `FALSE`, the procedure returns all solutions. The following function call to `prog::getOptions` sets the default option value `PositiveOnly = FALSE`:

```solveQuadraticEqn := proc(a:Type::Numeric, b:Type::Numeric, c:Type::Numeric) local options, S; begin options := prog::getOptions(4, [args()], table(PositiveOnly = FALSE)); S := solve(a*x^2 + b*x + c = 0, x); if options[1][PositiveOnly] = TRUE then S := select(S, testtype, Type::Positive) end_if: return(S) end_proc:```

If you call `solveQuadraticEqn` without the `PositiveOnly` option, the procedure returns all solutions of the quadratic equation:

`solveQuadraticEqn(2, 3, -9)`

If you use the `PositiveOnly` option, the procedure returns only positive solutions:

`solveQuadraticEqn(2, 3, -9, PositiveOnly)`

By default, `prog::getOptions` does not error when it finds an unexpected option (an option that is not listed in the table of accepted options). Instead, it collects all unexpected options and returns them in a separate list. Thus, the procedure `solveQuadraticEqn` does not issue an error when you spell the option name incorrectly:

`solveQuadraticEqn(2, 3, -9, Positive)`

The `prog::getOptions` function can issue an error when it finds an unexpected option. In a function call to `prog::getOptions`, the fourth argument indicates whether `prog::getOptions` must silently collect unexpected options or issue an error. This argument is optional. By default, it is set to `FALSE`. To issue an error instead of listing unexpected arguments, use `TRUE` as the fourth argument of `prog::getOptions`:

```solveQuadraticEqn := proc(a:Type::Numeric, b:Type::Numeric, c:Type::Numeric) local options, S; begin options := prog::getOptions(4, [args()], table(PositiveOnly = FALSE), TRUE); S := solve(a*x^2 + b*x + c = 0, x); if options[1][PositiveOnly] = TRUE then S := select(S, testtype, Type::Positive) end_if: return(S) end_proc:```

Now, the procedure `solveQuadraticEqn` issues an error. The error message indicates the wrong option:

`solveQuadraticEqn(2, 3, -9, Positive)`
```Error: Invalid argument number 4. Evaluating: solveQuadraticEqn ```

Mathematical Modeling with Symbolic Math Toolbox

Get examples and videos