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 patt gives the form the argument should have, if it is present. The expression def gives the "default value" to use if the argument is absent.
  • The form s_:def is equivalent to Optional[s_,def]. This form is also equivalent to s:_:def. 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 def in Optional[s_h,def] 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 built‐in default values include Plus, Times and Power. »
  • Longest and Shortest have special meaning when combined with Optional. Longest[patt:def] means to first attempt the pattern using patt and only then attempt the pattern using def. Shortest[patt:def] is reversed, first attempting to use def and only then patt.
  • If Optional is used with no explicit Longest or Shortest, it is effectively wrapped in Longest.

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_:d and s:_:d 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_2024_optional, author="Wolfram Research", title="{Optional}", year="2015", howpublished="\url{https://reference.wolfram.com/language/ref/Optional.html}", note=[Accessed: 22-November-2024 ]}

BibLaTeX

@online{reference.wolfram_2024_optional, organization={Wolfram Research}, title={Optional}, year={2015}, url={https://reference.wolfram.com/language/ref/Optional.html}, note=[Accessed: 22-November-2024 ]}