Procedure Parameter Declarations - Maple Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : Programming : Procedures and Functions : Parameters : parameter_classes

Procedure Parameter Declarations

 

Description

Required Positional Parameters

Optional Ordered Parameters

Expected Ordered Parameters

Keyword Parameters

The End of Parameters Marker, $

Default Value Dependencies

Details

Information on Procedure Parameters in Prior Versions of Maple

Description

• 

The parameters of a procedure are written as a comma-separated sequence of individual parameter declarations, enclosed in parentheses, immediately after the proc keyword of the procedure declaration:

  

proc(declaration, declaration, ...)

• 

The Maple programming language includes several classes of parameters: required positional, optional ordered, expected ordered, and keyword:

  

Required Positional Parameters

  

Optional Ordered Parameters

  

Expected Ordered Parameters

  

Keyword Parameters

  

Simple Keyword Parameters

  

Indexed Keyword Parameters

  

Alternate Keyword Spellings

  

The End of Parameters Marker, $

  

Default Value Dependencies

  

Information on Procedure Parameters in Prior Versions of Maple

Required Positional Parameters

• 

A required positional parameter is called a "required" parameter because a corresponding argument must have been passed if the parameter is used during the execution of the procedure. Note that the argument may be omitted if the flow of execution through the procedure is such that the parameter is never referenced.

• 

It is called "positional" because the position of the parameter within the parameterDeclarations corresponds to the position of the argument in the function call. For example, the 3rd argument in the function call is received by the 3rd parameter of the procedure.

• 

The syntax to declare a required positional parameter is:

  

parameterName :: parameterType

  

The parameterName must be a valid identifier, and is used to refer to the parameter within the procedure body (the statementSequence).

• 

The "::parameterType" declaration is optional, and may be omitted. If it is present and the corresponding argument does not match and cannot be coerced into the specified type an exception is raised. For example:

f := proc(a::integer,b) a+b end proc:

f(2,3);

5

(1)

f(2.5,4);

Error, invalid input: f expects its 1st argument, a, to be of type integer, but received 2.5

f(3);

Error, invalid input: f uses a 2nd argument, b, which is missing

• 

Maple has data type coercion which takes expressions passed into procedures as arguments and converts them into expressions matching the procedure parameter's declared parameterType.  For more information on data type coercion, see the coercion help page.

Optional Ordered Parameters

• 

An optional ordered parameter is declared using the following syntax:

  

parameterName :: parameterType := defaultValue

  

The defaultValue is what allows the parameter to be optional, and thus may not be omitted. If the next available argument does not match the declared parameterType, or if there are no more arguments, then the parameter receives the default value. The argument, if there was one, remains available for matching to the next parameter in the procedure's parameter declarations.

• 

As with a required positional parameter, the "::parameterType" declaration may be omitted from an optional ordered parameter. In that case, any argument matches the parameter trivially, so the parameter receives its default value only if all the arguments have been exhausted.

• 

The defaultValue is not restricted by the declared parameterType; any value can be used for the default. It is sometimes useful to choose a default value that does not match the parameter type so that the procedure body can determine whether or not the user passed an argument for the parameter. If the default value is one not matching the type, the only way the parameter can have that value is if the default was used.

  

Note however that a non-type-conforming default value must not evaluate to anything other than what was written. In other words, such a default value cannot depend on other parameters or variables, or otherwise evaluate to something other than itself. It is safest to use literals (for example, numeric values, strings, or NULL) as non-type-conforming default values.

• 

This class of parameter is called "ordered" because the arguments are still examined in the order they were passed. If argument number N is passed to the parameter number P, then argument N+1 can only be passed to parameter Q, where Q > P. Unmatched arguments are not matched against previously unmatched parameters.

• 

All ordered parameters must appear after any required parameters in the parameter declarations.

• 

Examples of the use of optional ordered parameters:

f := proc(a::integer := 10, b::integer := 100.1) a + b end proc:

f();

110.1

(2)

f(3);

103.1

(3)

f(3,4);

7

(4)

f(3,6.6);

103.1

(5)
• 

In the last call of f above, 6.6 does not match the type of parameter b, so b received its default value of 100.1, leaving 6.6 as an extra argument (accessible via the _rest sequence).

Expected Ordered Parameters

• 

An expected ordered parameter is declared using the following syntax:

  

parameterName :: expects(parameterType) := defaultValue

  

This class of parameter is similar to an optional ordered parameter, except that the corresponding function call argument can be omitted only if all further arguments are also omitted. If there is an argument available, it must match the declared type of the parameter or an exception is raised. The non-matching argument does not remain available for matching to a later parameter.

• 

As with optional ordered parameters, the defaultValue need not match the declared parameterType, and if it does not, it must not evaluate to anything other than itself.

• 

The example below is identical to the one for optional ordered parameters above, except that b is declared as an expected parameter. Notice the difference in the last call of f:

f := proc(a::integer := 10, b::expects(integer) := 100.1) a + b end proc:

f();

110.1

(6)

f(3);

103.1

(7)

f(3,4);

7

(8)

f(3,6.6);

Error, invalid input: f expects its 2nd argument, b, to be of type integer, but received 6.6

Keyword Parameters

• 

Keyword parameters are non-positional and non-ordered. A keyword parameter receives a value when an argument of the form keyword=value appears in a function call. The left hand side of the argument specifies the keyword parameter that is to receive a value, and the right hand side specifies the value it is to receive. (If true is an acceptable value for the parameter, then an argument consisting of just the keyword is interpreted as equivalent to keyword=true. See Argument Processing.)

• 

The declaration of a keyword parameter looks very much like that of an optional ordered parameter, except that all keyword parameter declarations are enclosed in braces, much like a set is:

  

{ ... keyword :: parameterType := defaultValue ... }

  

The "::parameterType" declaration may be omitted, in which case no type checking is done when a keyword argument is passed. If a type is specified, then the value part of the keyword argument must be of that type, or an exception is raised.

• 

Once again, the defaultValue need not match the parameterType, and if it does not, it must not evaluate to anything other than itself.

• 

Multiple keyword parameters can be declared within the same pair of braces, and multiple sets of keyword parameters can be declared. At procedure simplification time (when the procedure is "compiled" into Maple's internal form), all the sets are consolidated. If the procedure is then displayed (using Maple's print command), the keyword parameters all appear in a single set, ordered lexicographically.

Simple Keyword Parameters

• 

A simple keyword parameter is one in which the keyword is a just a Maple symbol (that is, a sequence of letters, digits, and underscores beginning with a letter or underscore, or any sequence of characters enclosed in left single quotes).

f := proc( { simple::integer := 2 } )
    sprintf("simple=%d",simple)
end proc:

f();

simple=2

(9)

f(simple=3);

simple=3

(10)

f(simple=4.5);

Error, invalid input: f expects value for keyword parameter simple to be of type integer, but received 4.5

Indexed Keyword Parameters

• 

If the keyword is of the form `symbol[symbol]` or `symbol[integer]`, the parameter is treated specially at argument processing time. Although such a keyword is still just a symbol (because of the surrounding left quotes), it matches indexed names. For more details, see Argument Processing.

f := proc( { `name[1]`::string := "hello",
             `name[2]`::string := "goodbye" } )
    sprintf("name[1]=\"%s\"   name[2]=\"%s\"",
            `name[1]`,`name[2]`)
end proc:

f(name[1]="hi");

name[1]="hi" name[2]="goodbye"

(11)

f(name[1]="bonjour",name[2]="aurevoir");

name[1]="bonjour" name[2]="aurevoir"

(12)

f(name[1,2]="good day");

name[1]="good day" name[2]="good day"

(13)

f(name[2]=42);

Error, invalid input: f expects value for keyword parameter name[2] to be of type string, but received 42

Alternate Keyword Spellings

• 

As a convenience to the user of a procedure, multiple spellings of the keyword are allowed by specifying a list of the permitted spellings in the declaration:

  

{ ... [ keyword_1, keyword_2, ... ] :: parameterType := defaultValue ... }

• 

Within the procedure body (the statementSequence), the parameter may be referred to by any of the spellings in the list. However, when the procedure is displayed by Maple, only the first spelling (keyword_1) will be used. (In a procedure with a lexically scoped keyword parameter, a spelling other than the first may be used to avoid ambiguity.)

• 

Alternate spellings and indexed keywords can be combined by including the indexed keywords in the list of alternate spellings. For example, the following keyword parameter declaration allows the keyword to be any of axis1, axis_1, or axis[1]:

  

{ ... [ axis1, axis_1, `axis[1]` ] :: string := "x" ... }

f := proc( { [color,colour]::symbol := RED } )
    sprintf("color=%a   colour=%a", color, colour)
end proc;

f:=proccolor,colour::symbol:=REDsprintfcolor=%a colour=%a,color,colorend proc

(14)

f();

color=RED colour=RED

(15)

f(color=BLUE);

color=BLUE colour=BLUE

(16)

f(colour=GREEN);

color=GREEN colour=GREEN

(17)

f(color=ORANGE,colour=PURPLE);

color=PURPLE colour=PURPLE

(18)

f(colour=YELLOW,color=42);

Error, invalid input: f expects value for keyword parameter [color, colour] to be of type symbol, but received 42

The End of Parameters Marker, $

• 

Usually, if there are more arguments in a function call than needed to match the called procedure's parameters, the remaining arguments are passed anyway, and are available via the special variables _rest and _passed. This allows procedures to be written to accept an arbitrary number of arguments of no particular type.

• 

If the parameter declaration sequence ends with the special parameter, $, such extra arguments are not allowed. An exception is raised if any arguments remain after all the parameters have been matched to arguments or default values. For example:

f := proc(a,$) 2*sin(a) end proc:

f(Pi);

0

(19)

f(Pi,2*Pi);

Error, invalid input: too many and/or wrong type of arguments passed to f; first unused argument is 2*Pi

• 

This mechanism should be used in any procedure that expects a fixed maximum number of arguments, as it then raises an exception if the procedure is called incorrectly.

Default Value Dependencies

• 

The defaultValue of a parameter may be expressed in terms of other parameters (as long as the result conforms to the declared value, if any, of the parameter). The parameters on which the defaultValue depends may appear earlier or later in the parameter declarations of the procedure.

• 

For example, here is a list extraction function that takes a list, a starting index, and an ending index. If the ending index is omitted, the length of the list is used:

sublist := proc( s::list, f::integer := 1, t::integer := nops(s) )
   return s[f..t]
end proc:

sublist([a,b,c,d,e],2,3);

b,c

(20)

sublist([a,b,c,d,e],2);

b,c,d,e

(21)
• 

There can be no cyclic dependencies, such as two parameters' default values depending on each other.

no_good := proc( s := sin(c), c := cos(s) )
    return s^2 + c^2
end;

Error, cyclic dependency detected in parameter s := sin(c) in procedure no_good

• 

Usually, Maple evaluates the arguments of a procedure call from left to right. The use of parameter dependencies in default values will alter this order to ensure that the required values are available before they are needed. This is only of any consequence if the evaluation of one or more parameters has side effects.

Details

  

For more information on parameters, see

  

1. Parameter Declarations

  

2. Parameter Modifiers

  

3. Using Parameters in Procedures

  

4. Argument Processing

Information on Procedure Parameters in Prior Versions of Maple

• 

Prior to Maple 10, there was only one class of procedure parameter in the Maple programming language, the positional parameter. When the argument processing features were introduced in Maple 10, and extended in Maple 11, several other classes of parameters were introduced: optional ordered, expected ordered, and keyword.

• 

Optional ordered parameters were initially called "optional positional parameters".

• 

The variable _passed was known as args prior to Maple 10.

See Also

Procedure Parameters

Procedures

 


Download Help Document

Was this information helpful?



Please add your Comment (Optional)
E-mail Address (Optional)
What is ? This question helps us to combat spam