There are various LinearAlgebra routines that expect Matrices for parameters. Before the introduction of data type coercion these routines would raise errors when given Arrays  or  lists. With data type coercion, these routines are now capable of accepting a wider range of inputs.

Various other routines in Maple's library have been updated to make use of coercion. No knowledge of programming is necessary to make use of this new feature. Simply using the same commands will now work on a wider variety of data types.  

$p\left( \mathrm{Array}\left( \left[ \left[ 1\, 2 \right]\, \left[3\, 4\right] \right] \right) \right)\;$

$p\left( \mathrm{Vector}\left[\mathrm{row}\right]\left( \left[ 5\, 6\,7 \right] \right) \right)\;$

$p\left( \left[ \left[ 1\,2\, 3\right]\, \left[ 4\, 5\, 6 \right] \right] \right)\;$

Adding a ~ prefix to the m::~Matrix parameter specification in the example above tells Maple it will accept something similar to a Matrix. You can now pass in a Vector. Behind the scenes an $n$-element column vector will be coerced into a $n$x1 matrix. In this case, there is no conversion or data copying going on; rather, an alias, or different view on the same data, is applied. Hence the term "coercion", the data structure is coerced into the right form.

In this example the 2x2 array passed in had lower bounds of 2 and 6. During the calling of procedure 'p', an alias was created so that B has a new view on the data. Inside the procedure B can be used as an ordinary 1-based array.

$A ≔ \mathrm{Array}\left(2..3\,6..7\right)\:$

$\mathrm{ArrayDims}\left(A\right)\;$

$p\left(A\right)\;$

There are times when you may want something other than a 1-based array. For example, when translating code written in another language, like C, it might be easier if you use 0-based arrays. In the following example, M[0,0] is the first array element inside the procedure, while outside the procedure the caller can continue to use the default for Maple arrays and matrices. The coercion is done in the most efficient way possible, without copying the data. 

$p\left( ⟨1\,2\;3\,4⟩ \right)\;$

The following example shows how to declare a private coercion routine inside a module. The use of "ModuleApply" makes the module work the same way as a procedure, but because it is a module, other methods and data can be associated with it. The method highlighted in red declares the way floats will be converted to rationals. The method highlighted in blue uses the parameter r -- declared as coercible type ~rational. When this procedure is called with a float argument, the procedure body sees only the coerced rational.

$\mathrm{Frac}\left(1.5\right)\;$

$\mathrm{Frac}\left(\frac{3}{2}\right)\;$

Example:

A simple way to allow either a name or string as the first argument of the procedure, but only ever have to deal with the string form.

This procedure accepts a single argument which gets returned unchanged. When this procedure is called given s as a string, it matches the first coercion, which is simply a type match to string. The return value is still a string -- the argument is passed through unchanged.

$p\left(''a\; string''\right)\;$

When the same procedure is given s as a name, the second coercion s->convert(s,string) is applied. This is executed as inline code, and transforms the passed argument into a string. The return value here is also a string -- the parameter is changed before executing any code in the body of the procedure.

$p\left(\mathrm{`a\; name`}\right)\;$

If some other kind of argument is passed, say an integer, then none of the coercion procedures match. Because 's' is an expected parameter, that did not match the expected type, an error will be raised.

$p\left(\mathrm{expect}\+\mathrm{an}\+\mathrm{Error}\right)\;$

For additional information see the following help topics: