WOLFRAM

Wolfram Language & System Documentation Center

ConfirmMatch[expr,form]

confirms that expr matches the pattern form, otherwise throwing an error to the nearest surrounding Enclose.

ConfirmMatch[expr,form,info]

evaluates info and includes its value in the thrown error if expr is not confirmed.

ConfirmMatch[expr,form,info,tag]

uses the specified tag for any thrown errors.

Details
Details and Options Details and Options
Examples  
Basic Examples  
Scope  
Applications  
Properties & Relations  
Possible Issues  
See Also
Related Guides
History
Cite this Page

ConfirmMatch

ConfirmMatch[expr,form]

confirms that expr matches the pattern form, otherwise throwing an error to the nearest surrounding Enclose.

ConfirmMatch[expr,form,info]

evaluates info and includes its value in the thrown error if expr is not confirmed.

ConfirmMatch[expr,form,info,tag]

uses the specified tag for any thrown errors.

Details

  • ConfirmMatch[expr,…] returns expr if expr is successfully confirmed.
  • ConfirmMatch is dynamically scoped when given a tag. Otherwise, it is lexically scoped. »
  • The default value of info is Null.
  • Failure objects generated by ConfirmMatch include the following fields:
  • "Information"info from ConfirmMatch[expr,form,info,…]
    "Expression"expr from ConfirmMatch[expr,…]
    "Pattern"form from ConfirmMatch[expr,form,…]
  • Values of these fields can be extracted using failure["prop"] or directly through Enclose[expr,"prop"].

Examples

open all close all

Basic Examples  (2)

ConfirmMatch[expr,form] gives expr if expr matches form:

Wolfram Language code: Enclose[f[1, ConfirmMatch[2, _Integer], 3]]

Since "foo" does not match _Integer, ConfirmMatch stops evaluation and throws an error to the surrounding Enclose:

Wolfram Language code: Enclose[f[1, ConfirmMatch["foo", _Integer], 3]]

Create a function that checks its arguments:

Wolfram Language code: world[x_] := Enclose[ConfirmMatch[x, _String] <> ", World!"]
Wolfram Language code: world["Hello"]
Wolfram Language code: world[4]

Scope  (3)

ConfirmMatch stops evaluation and returns to the matching Enclose when it throws an error:

Wolfram Language code: Enclose[Echo[1];ConfirmMatch[{1, 2, 3}, _String];Echo[2]]

info is only evaluated when expr cannot be confirmed:

Wolfram Language code: Enclose[ConfirmMatch[{1, 2, 3}, _List, Echo["info was evaluated"]]]
Wolfram Language code: Enclose[ConfirmMatch["not a list", _List, Echo["info was evaluated"]]]

Create a function that calls ConfirmMatch with a tag so that it can be caught dynamically:

Wolfram Language code: f[x_] := g[StringReverse[ConfirmMatch[x, _String, Null, "fooTag"]]]
Wolfram Language code: h[y_] := Enclose[f[y], Identity, "fooTag"]
Wolfram Language code: h["reverseme"]
Wolfram Language code: h[42]

If no tag is given, ConfirmMatch is lexically scoped:

Wolfram Language code: f2[x_] := g[StringReverse[ConfirmMatch[x, _String]]]
Wolfram Language code: h2[y_] := Enclose[f2[y]]
Wolfram Language code: h2[2]

Applications  (1)

Print a message when a failure is detected:

Wolfram Language code: reverseRoman::nan = "`` is not an integer.";
Wolfram Language code: reverseRoman[n_] := Enclose[ StringReverse[RomanNumeral[ ConfirmMatch[n, _Integer, Message[reverseRoman::nan, n]] ]], $Failed&]
Wolfram Language code: reverseRoman[21]
Wolfram Language code: reverseRoman["veni, vidi, vici"]

Properties & Relations  (1)

ConfirmMatch can be emulated by ConfirmBy and MatchQ:

Wolfram Language code: Enclose[f[ConfirmMatch[{1, 2, 3}, {_Integer, 2, _String}]]]
Wolfram Language code: Enclose[f[ConfirmBy[{1, 2, 3}, MatchQ[{_Integer, 2, _String}]]]]

Possible Issues  (3)

ConfirmMatch must be given a tag or be within a lexical Enclose:

Wolfram Language code: ConfirmMatch[5, _Integer]

Untagged ConfirmMatch works by replacing instances of the symbol ConfirmMatch with a tagged variant:

Wolfram Language code: Enclose[Hold[ConfirmMatch]]

Tagged ConfirmMatch requires an Enclose with a matching tag:

Wolfram Language code: Enclose[ConfirmMatch["hello", _Integer, Null, "foo"], Identity, "bar"]
Wolfram Research (2020), ConfirmMatch, Wolfram Language function, https://reference.wolfram.com/language/ref/ConfirmMatch.html.

Text

Wolfram Research (2020), ConfirmMatch, Wolfram Language function, https://reference.wolfram.com/language/ref/ConfirmMatch.html.

CMS

Wolfram Language. 2020. "ConfirmMatch." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/ConfirmMatch.html.

APA

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

BibTeX

@misc{reference.wolfram_2026_confirmmatch, author="Wolfram Research", title="{ConfirmMatch}", year="2020", howpublished="\url{https://reference.wolfram.com/language/ref/ConfirmMatch.html}", note=[Accessed: 12-June-2026]}

BibLaTeX

@online{reference.wolfram_2026_confirmmatch, organization={Wolfram Research}, title={ConfirmMatch}, year={2020}, url={https://reference.wolfram.com/language/ref/ConfirmMatch.html}, note=[Accessed: 12-June-2026]}