## `coerce` -- type conversion

#### Introduction

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

#### Call(s)

`coerce(object, T)`

#### Parameters

`object` | - | any object
`T` | - | any domain

#### Returns

an object of the domain `T`, or the value `FAIL`.

### Overloadable:

`T`

#### Related Functions

`domtype`, `expr`, `testtype`, `type`

#### Details

- `coerce(`object, T`)` tries to convert `object` to 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"`, but this will be extended in future versions of MuPAD.

- 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.

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

                                   +-         -+
                                   |  1, 2, 3  |
                                   |           |
                                   |  4, 5, 6  |
                                   +-         -+

    >> coerce(a, DOM_LIST)

                                [1, 2, 3, 4, 5, 6]

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

    >> coerce(a, DOM_POLY)

                                       FAIL

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

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

                                   +-         -+
                                   |  1, 2, 3  |
                                   |           |
                                   |  4, 5, 6  |
                                   +-         -+

                                   Dom::Matrix()

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)

                              [[1, 2, 3], [4, 5, 6]]

One can convert lists into sets, and vice versa. An example:

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

                                     {1, 2, 3}

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)

                                 "2*x + sin(x^2)"

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

                                            2
                                     (x + 1)

                                     Factored

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)

                                   [1, x + 1, 2]

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

    >> coerce(f, DOM_LIST)

                                   [1, x + 1, 2]

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

                                    +-      -+
                                    |  1, 2  |
                                    |        |
                                    |  3, 4  |
                                    +-      -+

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)

                                    +-      -+
                                    |  1, 2  |
                                    |        |
                                    |  3, 4  |
                                    +-      -+

                            Dom::Matrix(Dom::Rational)

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`).

#### Changes

- new function

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