# `coerce`

Type conversion

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.

## Syntax

```coerce(`object`, `T`)
```

## Description

`coerce(object, T)` tries to convert `object` into an element of the domain `T`.

If this is not possible or not implemented, then `FAIL` is returned.

Domains usually implement the two methods `"convert"` and `"convert_to"` for conversion tasks.

`coerce` uses these methods in the following way: It first calls `T::convert(object)` to perform the conversion. If this call yields `FAIL`, then the result of the call `object::dom::convert_to(object, T)` is returned, which again may be the value `FAIL`.

To find out the possible conversions for the `object` or which conversions are provided by the domain `T`, please read the description of the method `"coerce"` or `"convert"`, respectively, that can be found on the help page of the domain `T`, and the description of the method `"convert_to"` on the help page of the domain of `object`.

Only few basic domains currently implement the methods `"convert"` and `"convert_to"`.

Use the function `expr` to convert an object into an element of a basic domain.

Note that often a conversion can also be achieved by a call of the constructor of the domain `T`. See Example 3.

## Examples

### Example 1

We start with the conversion of an array into a list of domain type `DOM_LIST`:

`a := array(1..2, 1..3, [[1, 2, 3], [4, 5, 6]])`

`coerce(a, DOM_LIST)`

We convert the array into an `hfarray` of type `DOM_HFARRAY`:

`coerce(a, DOM_HFARRAY)`

The conversion of an array into a polynomial is not implemented, and thus `coerce` returns `FAIL`:

`coerce(a, DOM_POLY)`

One can convert a one- or two-dimensional array into a matrix, and vice versa. An example:

`A := coerce(a, matrix); domtype(A)`

The conversion of a matrix into a list is also possible. The result is then a list of inner lists, where the inner lists represent the rows of the matrix:

`coerce(A, DOM_LIST)`

`coerce([1, 2, 3, 2], DOM_SET)`

Any MuPAD® object can be converted into a string, such as the arithmetical expression ```2*x + sin(x^2)```:

`coerce(2*x + sin(x^2), DOM_STRING)`

### Example 2

The function `factor` computes a factorization of a polynomial expression and returns an object of the library domain `Factored`:

```f := factor(x^2 + 2*x + 1); domtype(f)```

This domain implements the conversion routine `"convert_to"`, which we can call directly to convert the factorization into a list (see `factor` for details):

`Factored::convert_to(f, DOM_LIST)`

However, it is more convenient to use `coerce`, which internally calls the slot routine `Factored::convert_to`:

`coerce(f, DOM_LIST)`

### Example 3

Note that often a conversion can also be achieved by a call of the constructor of a domain `T`. For example, the following call converts an array into a matrix of the domain type `Dom::Matrix`(`Dom::Rational`):

```a := array(1..2, 1..2, [[1, 2], [3, 4]]): MatQ := Dom::Matrix(Dom::Rational):```
`MatQ(a)`

The call `MatQ(a)` implies the call of the method `"new"` of the domain `MatQ`, which in fact calls the method `"convert"` of the domain `MatQ` to convert the array into a matrix.

Here, the same can be achieved with the use of `coerce`:

```A := coerce(a, MatQ); domtype(A)```

Note that the constructor of a domain `T` is supposed to create objects, not to convert objects of other domains into the domain type `T`. The constructor often allows more than one argument which allows to implement various user-friendly ways to create the objects (e.g., see the several possibilities for creating matrices offered by `matrix`).

## Parameters

 `object` Any object `T` Any domain

## Return Values

Object of the domain `T`, or the value `FAIL`.

`T`

## See Also

### MuPAD Functions

#### Mathematical Modeling with Symbolic Math Toolbox

Get examples and videos