Optional

patt:def or Optional[patt,def]

is a pattern object that represents an expression of the form patt, which, if omitted, should be replaced by the default value def.

Details

  • Optional is used to specify "optional arguments" in functions represented by patterns. The pattern object p gives the form the argument should have, if it is present. The expression v gives the "default value" to use if the argument is absent.
  • The form s_:v is equivalent to Optional[s_,v]. This form is also equivalent to s:_:v. There is no syntactic ambiguity since s must be a symbol in this case. »
  • The special form s_. is equivalent to Optional[s_] and can be used to represent function arguments which, if omitted, should be replaced by default values globally specified for the functions in which they occur. »
  • Values for Default[f,] specify default values to be used when _. appears as an argument of f. Any assignments for Default[f,] must be made before _. first appears as an argument of f. »
  • Optional[s_h] represents a function that can be omitted, but that, if present, must have head h. There is no simpler syntactic form for this case. »
  • The value k in Optional[s_h,k] need not have the head h. More generally, the default value need not match any pattern requirements for optional arguments that are actually present. »
  • Functions with builtin default values include Plus, Times and Power. »

Examples

open allclose all

Basic Examples  (1)

Define a function with a default value for the second argument:

Use the function with both arguments specified explicitly:

The second argument is now taken to have its default value:

Scope  (5)

Use Optional in any pattern-matching function including ReplaceAll:

Cases:

And MatchQ:

Use Optional with BlankSequence:

The default is used:

The value given is used:

A sequence of values is bound to x:

The first argument to Optional can be any pattern, not just a form of Blank:

Specify a default value for a function:

Define a down value using a default argument:

If the third argument is given, its value is used:

If the third argument is not present, the value is taken from the function's default:

The default value need not match the pattern for the optional argument:

5 matches the pattern:

The string "xyz" does not match the pattern:

When no argument is specified, the default value is returned even though it fails to match the pattern:

Properties & Relations  (6)

The ternary form sym:pat:def has head Optional:

The forms s_:v and s:_:v are identical:

If no explicit default is given, the default is inferred from DefaultValues of the head:

The 1 comes from DefaultValues[Times]:

An explicit default can always be provided:

The short form x_. is equivalent to Optional[Pattern[x,Blank[]]:

When restricting a default argument, the pattern will entirely fail to match a nonconforming argument:

Only if the argument is completely missing will the default value be used:

Optional does not prevent the default value from evaluating:

Thus, all calls f use the same default value:

Use HoldPattern to delay evaluation of the default value until it is used:

Each call to g uses a unique default value:

Define a function using BlankSequence and Optional; the function evaluates using a default value:

Define a function using BlankNullSequence; the function evaluates with no value:

Since BlankNullSequence matches a zero argument length, the form x___:d will never use d:

Possible Issues  (3)

The input s:v has head Optional only if s is a special input form for Blank[] or Pattern[sym,Blank[]]:

BlankSequence[] and BlankNullSequence[] are also allowed:

If s is a symbol, then s:v represents Pattern[s,v]:

If s is any other expression, the form is not valid input:

Condition and PatternTest cannot be applied to Optional:

Instead, apply the test to the first argument of Optional:

The functions f and g behave as expected, whether given zero or one argument:

Pattern cannot bind to an Optional object:

Instead, put the pattern inside the first argument to Optional:

The symbol x is bound to the default value if the pattern does not match:

Note that the Optional object can written more compactly using the ternary form s:p:d:

Wolfram Research (1988), Optional, Wolfram Language function, https://reference.wolfram.com/language/ref/Optional.html (updated 2015).

Text

Wolfram Research (1988), Optional, Wolfram Language function, https://reference.wolfram.com/language/ref/Optional.html (updated 2015).

CMS

Wolfram Language. 1988. "Optional." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2015. https://reference.wolfram.com/language/ref/Optional.html.

APA

Wolfram Language. (1988). Optional. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/Optional.html

BibTeX

@misc{reference.wolfram_2022_optional, author="Wolfram Research", title="{Optional}", year="2015", howpublished="\url{https://reference.wolfram.com/language/ref/Optional.html}", note=[Accessed: 08-June-2023 ]}

BibLaTeX

@online{reference.wolfram_2022_optional, organization={Wolfram Research}, title={Optional}, year={2015}, url={https://reference.wolfram.com/language/ref/Optional.html}, note=[Accessed: 08-June-2023 ]}