overload - define procedures with the same name operating on different argument types

Calling Sequence

overload(l)

overload(p, l)

proc(...) option overload; ... end proc

proc(...) option overload(callseq_only); ... end proc

Parameters

l

-

list of procedures with option overload

p

-

procedure returned by a previous call to overload

Description

•

The overload command allows you to split the implementation of a command that operates on different argument types into separate procedures.

•

Option overload denotes a procedure that operates on only the specific argument types described in the parameter declarations. Procedures with this option are intended to be used in conjunction with the overload command, or as part of a package that is loaded using with. Under these conditions, the next available procedure is called when an argument type match fails.

•

The overload command accepts a list of procedures, l = [p1,p2,...,pn], and returns a single procedure, P, that combines all of the sub-procedures. Calling P(x,y); will first attempt to run p1(x,y). Execution will proceed as follows.

If p1 computes a result, that result is returned.

If p1 generates an error that is not prefixed by "invalid input:", then execution stops, and that exception is raised.

If p1 raises an exception prefixed by "invalid input:", and p1 has option overload specified, then execution will proceed with p2(x,y).

If p1 raises an exception during the parameter type-checking phase only (not inside p1), and option overload(callseq_only) has been specified, then execution will proceed to p2(x,y).

If p1 does not have any option overload designation, then execution will always terminate with whatever p1 does. Usually, only the last procedure in the overload list should omit option overload.

The transition is made from p1 to p2 to p3, through to pn as long as the calling sequences do not match, or an invalid input exception is raised, and the sub-procedure has the appropriate overload option. If no procedure call leads to a result, a generic exception is raised.

If overload is called with the first argument p, then the given list, l, is appended to the existing list contained in p. When the returned procedure is called, each argument signature in the embedded procedures is checked. If no type mismatch occurs, the procedure inside l with the matching type signature is called.

•

The with command can be used to load a package containing procedures with option overload. This will override any other commands with the same name that were previously loaded, only insofar as the new procedure's type signature declares. For example, you can define a specialized version of the + function as in some of the examples below. Your function will only be invoked when adding expressions that match the type specified in your option overload procedure. Otherwise the default, built-in implementation will be used. Multiple implementations of + can be loaded simultaneously to act on different package-specific domains.

Element-wise operators can be overloaded by binding the ~ function. The ~ function gets called with the operation in square brackets as an index to the function name. In order to distinguish element-wise operator calls with an expression sequence on either side of the operator, the arguments are separated by a special fence token, ` $` (space-dollar sign). The statement, a +~ b is recast as ~[`+`](a,` $`,b). Uses of tilde following a function name and argument sequence do not have the fence argument.

Extend the above example with a common helper function to do additional argument checking. In this case use option overload(callseq_only) so that invalid-input exceptions from inside the helper function are raised to the top.

An example overloading `?[]`. Note that the select and assignment operations are split into separate procedures called by the main `?[]` procedure for clarity. Proper assignment requires the "var" argument to be ::uneval. Evaluation must be done by calling eval();

When procedures with option overload are called directly, bypassing the with() bindings, or implicitly inside a package module, they behave as if they were ordinary procedures, and do not attempt to call another implementation in light of a type mismatch. Consider the following example.

After loading the package declared above, the 'rhs' function will work in the new way on float types, while calls to 'rhs' with other data continue to work as usual.

>

with&ApplyFunction;FloatTools

alt_decimalpart&comma;decimalpart&comma;rhs

(23)

>

rhs&ApplyFunction;3.14

0.14

(24)

>

rhs&ApplyFunction;x2−1&equals;y2

y2

(25)

The function 'decimalpart' is similar to 'rhs' except it effectively calls FloatTools:-rhs directly, therefore bypassing the overload mechanism. The second call to 'decimalpart below' will raise a type-mismatch error.

To reference the 'rhs' command within the package definition in a way that will do the type matching, use the 'overload' command to define a new function, and use that new function where appropriate. The example above defines 'RHS' to use internally for this reason. The alternate implementation of 'decimalpart', called 'alt_decimalpart', does not raise an exception when given non-float input.