Optional
✖
Optional
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 allBasic Examples (1)Summary of the most common use cases
Define a function with a default value for the second argument:
https://wolfram.com/xid/0bn672k-mp0
Use the function with both arguments specified explicitly:
https://wolfram.com/xid/0bn672k-ry7
The second argument is now taken to have its default value:
https://wolfram.com/xid/0bn672k-yal
Scope (5)Survey of the scope of standard use cases
Use Optional in any pattern-matching function including ReplaceAll:
https://wolfram.com/xid/0bn672k-3x6725
https://wolfram.com/xid/0bn672k-f1syuf
And MatchQ:
https://wolfram.com/xid/0bn672k-839o6y
Use Optional with BlankSequence:
https://wolfram.com/xid/0bn672k-b8alkf
https://wolfram.com/xid/0bn672k-t4z3bs
https://wolfram.com/xid/0bn672k-9r3d2x
A sequence of values is bound to x:
https://wolfram.com/xid/0bn672k-pdffyo
The first argument to Optional can be any pattern, not just a form of Blank:
https://wolfram.com/xid/0bn672k-za56x
https://wolfram.com/xid/0bn672k-zr7xn1
Specify a default value for a function:
https://wolfram.com/xid/0bn672k-nemsgr
Define a down value using a default argument:
https://wolfram.com/xid/0bn672k-q7pljn
If the third argument is given, its value is used:
https://wolfram.com/xid/0bn672k-0nhbj2
If the third argument is not present, the value is taken from the function's default:
https://wolfram.com/xid/0bn672k-rrrtoj
The default value need not match the pattern for the optional argument:
https://wolfram.com/xid/0bn672k-zdjs6n
https://wolfram.com/xid/0bn672k-cac3um
The string "xyz" does not match the pattern:
https://wolfram.com/xid/0bn672k-n0c4gt
When no argument is specified, the default value is returned even though it fails to match the pattern:
https://wolfram.com/xid/0bn672k-uzsqb1
Properties & Relations (6)Properties of the function, and connections to other functions
The ternary form sym:pat:def has head Optional:
https://wolfram.com/xid/0bn672k-qtil1y
The forms s_:d and s:_:d are identical:
https://wolfram.com/xid/0bn672k-1n1zc7
If no explicit default is given, the default is inferred from DefaultValues of the head:
https://wolfram.com/xid/0bn672k-xmpihe
The 1 comes from DefaultValues[Times]:
https://wolfram.com/xid/0bn672k-jv7fd
An explicit default can always be provided:
https://wolfram.com/xid/0bn672k-8k60os
The short form x_. is equivalent to Optional[Pattern[x,Blank[]]:
https://wolfram.com/xid/0bn672k-kv9jch
When restricting a default argument, the pattern will entirely fail to match a nonconforming argument:
https://wolfram.com/xid/0bn672k-qkbdtz
Only if the argument is completely missing will the default value be used:
https://wolfram.com/xid/0bn672k-zlrnye
Optional does not prevent the default value from evaluating:
https://wolfram.com/xid/0bn672k-wdqczq
Thus, all calls f use the same default value:
https://wolfram.com/xid/0bn672k-8e2fj7
Use HoldPattern to delay evaluation of the default value until it is used:
https://wolfram.com/xid/0bn672k-24wok
Each call to g uses a unique default value:
https://wolfram.com/xid/0bn672k-i5pzzv
Define a function using BlankSequence and Optional; the function evaluates using a default value:
https://wolfram.com/xid/0bn672k-57b5vq
Define a function using BlankNullSequence; the function evaluates with no value:
https://wolfram.com/xid/0bn672k-pmncks
Since BlankNullSequence matches a zero argument length, the form x___:d will never use d:
https://wolfram.com/xid/0bn672k-b66irn
Possible Issues (3)Common pitfalls and unexpected behavior
The input s:v has head Optional only if s is a special input form for Blank[…] or Pattern[sym,Blank[…]]:
https://wolfram.com/xid/0bn672k-jxqxpx
BlankSequence[…] and BlankNullSequence[…] are also allowed:
https://wolfram.com/xid/0bn672k-pp37p8
If s is a symbol, then s:v represents Pattern[s,v]:
https://wolfram.com/xid/0bn672k-4qoei7
If s is any other expression, the form is not valid input:
https://wolfram.com/xid/0bn672k-cv6in5
Condition and PatternTest cannot be applied to Optional:
https://wolfram.com/xid/0bn672k-3fjf1c
https://wolfram.com/xid/0bn672k-gjljci
Instead, apply the test to the first argument of Optional:
https://wolfram.com/xid/0bn672k-hycfes
https://wolfram.com/xid/0bn672k-zo5jay
The functions f and g behave as expected, whether given zero or one argument:
https://wolfram.com/xid/0bn672k-0jmsfv
Pattern cannot bind to an Optional object:
https://wolfram.com/xid/0bn672k-3xe4gq
Instead, put the pattern inside the first argument to Optional:
https://wolfram.com/xid/0bn672k-vcbzyx
The symbol x is bound to the default value if the pattern does not match:
https://wolfram.com/xid/0bn672k-osl7cr
Note that the Optional object can written more compactly using the ternary form s:p:d:
https://wolfram.com/xid/0bn672k-gp09k2
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).
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.
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
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: 08-January-2025
]}
BibLaTeX
@online{reference.wolfram_2024_optional, organization={Wolfram Research}, title={Optional}, year={2015}, url={https://reference.wolfram.com/language/ref/Optional.html}, note=[Accessed: 08-January-2025
]}