# Documentation

## Convert Data Types

 Note:   Use only in the MuPAD Notebook Interface. This functionality does not run in MATLAB.

When creating new objects in MuPAD®, the best practice is to consider which domain the object must belong to. Choosing the correct data type from the beginning helps you avoid unnecessary conversions. Nevertheless, some computation tasks require data types conversions. For such tasks, MuPAD enables you to convert the elements of some domains to elements of other domains.

To convert an object to a different domain type, use one of the following alternatives. Some of the alternatives do not work for conversions between particular domains.

 Note:   If you implement a new domain, consider implementing the conversion methods for that domain.

### Use the coerce Function

To convert a MuPAD object to an element of a specified domain, use the `coerce` function. For example, convert the following element of the domain `DOM_LIST` to an element of the domain `DOM_SET`:

```L := [1, 2, 3, 4, 5, 6]; S := coerce(L, DOM_SET)```

`domtype(L), domtype(S)`

Results of the conversion can depend on the original domain type. For example, create an array and a matrix with the same number of elements and equal dimensions:

```M := matrix(2, 3, [1, 2, 3, 4, 5, 6]); A := array(1..2, 1..3, [1, 2, 3, 4, 5, 6])```

Verify that matrix `M` belongs to the domain `Dom::Matrix()`, and array `A` belongs to the domain `DOM_ARRAY`:

`domtype(M), domtype(A)`

Use the `coerce` function to convert both objects to elements of the domain `DOM_LIST`. The `coerce` function converts matrix `M` to a nested list, where the inner lists represent the rows of the original matrix. At the same time, `coerce` converts the array `A` to a flat list:

```LM := coerce(M, DOM_LIST); LA := coerce(A, DOM_LIST)```

Both new objects belong to the basic domain of lists `DOM_LIST`:

`domtype(LM), domtype(LA)`

For further computations, delete the identifiers `L`, `S`, `M`, `A`, `LM`, and `LA`:

`delete L, S, M, A, LM, LA`

### Use the expr Function

To convert an element of a library domain to an element of a basic kernel domain, use the `expr` function. This function does not allow you to select the basic domain to which it converts an object. If the conversion to basic domains is not possible, the function returns `FAIL`.

The `expr` function tries to find the simplest basic domain to which it can convert a given object. The function also can convert an element of a more complicated basic domain to the simpler basic domain. For example, it converts the polynomial represented by a single variable `x` to the identifier `x`:

```y := poly(x); expr(y)```

The original object `y` belongs to the domain of polynomials. The result of conversion belongs to the domain of identifiers `DOM_IDENT`:

`domtype(y), domtype(expr(y))`

If you call the `expr` function for a more complicated polynomial, the function converts that polynomial to the expression:

```p := poly(x^2 + x + 2); expr(p)```

Again, the original polynomial belongs to the domain of polynomials. This time, the result of the conversion belongs to the domain of expressions:

`domtype(p), domtype(expr(p))`

MuPAD can apply the `expr` function to an object recursively. If an object contains terms that belong to library domains or complicated basic domains, `expr` also tries to convert those terms elements of simpler basic domains. For example, if the polynomial `p` is an element of a list, applying the `expr` function to the list converts the polynomial `p` to the expression:

```matrix(2, 2, [p, 0, 0, 1]); expr(matrix(2, 2, [p, 0, 0, 1]))```

The `expr` function converts a matrix of the library domain `Dom::Matrix()` to an array of the basic kernel domain `DOM_ARRAY`:

`M := matrix(2, 3, [1, 2, 3, 4, 5, 6])`

`domtype(M), domtype(expr(M))`

The `expr` function converts an element of the series domain to the expression of a basic domain `DOM_EXPR`. Typically, the order of terms in the resulting expression changes:

```s := series(exp(x), x); expr(s)```

`domtype(s), domtype(expr(s))`

For further computations, delete the identifiers `y`, `p`, `M`, and `s`:

`delete y, p, M, s`

### Use Constructors

Instead of calling the conversion functions, you can use the constructor of a domain to which you want to convert an object. This approach works for most conversions, but it can fail in some cases.

Calling the constructor of the required domain is often the simplest way to convert an object to the element of that domain. Suppose you want to convert the following list `L` to a matrix:

`L := [1, 2, 3, 4, 5, 6]`

To convert a list to a matrix, call the matrix constructor `matrix`. Use the arguments of the matrix constructor to specify the dimensions of the required matrix and the list `L` of the elements of a matrix. The resulting object is the 2×3 matrix of the domain `Dom::Matrix()`:

```matrix(2, 3, L); domtype(%)```

Alternatively, you can convert a list to a matrix by using `Dom::Matrix()`:

```Dom::Matrix()(2, 3, L); domtype(%)```

For further computations, delete the identifier `L`:

`delete L`