({{, (RefLink[FirstCase, paclet:ref/FirstCase])[{(Subscript[e, 1]),(Subscript[e, 2]),…},pattern] 
gives the first (Subscript[e, i]) to match pattern, or (RefLink[Missing, paclet:ref/Missing])["NotFound"] if none matching pattern is found. }, {, (RefLink[FirstCase, paclet:ref/FirstCase])[{(Subscript[e, 1]),…},pattern->rhs]
gives the value of rhs corresponding to the first (Subscript[e, i]) to match pattern.}, {, (RefLink[FirstCase, paclet:ref/FirstCase])[expr,pattern,default]
gives default if no element matching pattern is found. }, {, (RefLink[FirstCase, paclet:ref/FirstCase])[expr,pattern,default,levelspec]
finds only objects that appear on levels specified by levelspec. }, {, (RefLink[FirstCase, paclet:ref/FirstCase])[pattern]
represents an operator form of (RefLink[FirstCase, paclet:ref/FirstCase]) that can be applied to an expression.}})

OpenersNotesSection(Spacer1)Details and Options

The first argument to (RefLink[FirstCase, paclet:ref/FirstCase]) need not have head (RefLink[List, paclet:ref/List]) and can be an association.

(RefLink[FirstCase, paclet:ref/FirstCase])[expr,pattern:>rhs] evaluates rhs only when the pattern is found.

In (RefLink[FirstCase, paclet:ref/FirstCase])[{(Subscript[e, 1]),(Subscript[e, 2]),…},pattern,default], default is only evaluated if none of the (Subscript[e, i]) match.

(RefLink[FirstCase, paclet:ref/FirstCase])[pattern][expr] is equivalent to (RefLink[FirstCase, paclet:ref/FirstCase])[expr,pattern].

(RefLink[FirstCase, paclet:ref/FirstCase]) uses standard level specifications:

The default value for levelspec in (RefLink[FirstCase, paclet:ref/FirstCase]) is {1}.

A positive level n consists of all parts of expr specified by n indices.

A negative level -n consists of all parts of expr with depth n.

Level -1 consists of numbers, symbols, and other objects that do not have subparts.

Level 0 corresponds to the whole expression.

With the option setting (RefLink[Heads, paclet:ref/Heads])->(RefLink[True, paclet:ref/True]), (RefLink[FirstCase, paclet:ref/FirstCase]) looks at heads of expressions and their parts.

(RefLink[FirstCase, paclet:ref/FirstCase]) traverses the parts of expr in a depth-first order, with leaves visited before roots.

OpenersPrimaryExamplesSection(Spacer1)Examples  (16)

OpenersExampleSection0(Spacer1)Basic Examples  (3)

Find the first element in a list matching an integer:

FirstCase[{a,b,c,5,6,7},_Integer]

Find the first non-integer:

FirstCase[{1,1,f[a],2,3,y,f[8],9,f[10]},Except[_Integer]]

Return the x from inside the first f[x_] matched:

FirstCase[{1,1,f[a],2,3,y,f[8],9,f[10]},f[x_]:>x]

Pick an element from an (RefLink[Association, paclet:ref/Association]):

FirstCase[<|1->"a",2->"b",3->c,4->d|>,_Symbol]

OpenersExampleSection1(Spacer1)Scope  (7)

Use the operator form of (RefLink[Cases, paclet:ref/Cases]):

FirstCase[_Integer]@{f[a],2,3,a}

Find the first order pair:

FirstCase[{{1,2},{2},{3,4,1},{5,4},{3,3}},{_,_}]

Find its sum:

FirstCase[{{1,2},{2},{3,4,1},{5,4},{3,3}},{a_,b_}->a+b]

Pick out the first nonzero element:

FirstCase[{1,0,2,0,3,5,6,7,0,0,0},Except[0]]

Use :> to evaluate only after explicit elements have been found:

FirstCase[{f[{}],f[{a}],g[{a,b}],f[{a,b,c}]},g[x_]:>Length[x]]

Specify a custom default value:

FirstCase[{1,2,3},_?StringQ,"NoStrings"]

Examine the elements of a matrix using a level specification:

FirstCase[{{1,4,a,0},{b,3,2,2},{c,c,5,5}},_Symbol,Missing[],{2}]

Pick elements from nested associations:

FirstCase[<|1->5,2-><|3->1, a->b|>|>,_Symbol,Missing[],Infinity]

OpenersExampleSection2(Spacer1)Options  (1)

OpenersExampleSubsection0(Spacer1)Heads  (1)

Find a symbol among the elements of an expression:

FirstCase[{5,a,π},_Symbol]

Also include the head of the expression in the search:

FirstCase[{a,5,π},_Symbol,Heads->True]

OpenersExampleSection3(Spacer1)Properties & Relations  (4)

The default value is only evaluated if needed:

FirstCase[{None, "A","B"},_String,Abort[]]

FirstCase[{None,None,None},_String,Abort[]]

(RefLink[FirstCase, paclet:ref/FirstCase]) returns only the first match:

FirstCase[{None, "A","B"},"A"|"B"]

(RefLink[Cases, paclet:ref/Cases]) returns all matches:

Cases[{None, "A","B"},"A"|"B"]

(RefLink[FirstCase, paclet:ref/FirstCase]) can be implemented with a combination of (RefLink[Cases, paclet:ref/Cases]) and (RefLink[Replace, paclet:ref/Replace]):

FirstCase[{1,2,a,(Sqrt[2]),Pi,E},_Symbol]
FirstCase[{1,2,a,(Sqrt[2]),Pi,E},_StringQ]

Replace[Cases[{1,2,a,(Sqrt[2]),Pi,E},_Symbol],{{}:>Missing["NotFound"],l_:>First[l]}]
Replace[Cases[{1,2,a,(Sqrt[2]),Pi,E},_StringQ],{{}:>Missing["NotFound"],l_:>First[l]}]

(RefLink[FirstCase, paclet:ref/FirstCase]) is similar to (RefLink[SelectFirst, paclet:ref/SelectFirst]) except that it uses a pattern instead of a function:

list = RandomInteger[{3,7},{10,2}]

Select the first list that has a sum of elements less than 10:

smallQ=Total[#]<10&;

FirstCase[list,x_/;smallQ[x]]

Use (RefLink[SelectFirst, paclet:ref/SelectFirst]) to get the same result:

SelectFirst[list,smallQ]

OpenersExampleSection4(Spacer1)Possible Issues  (1)

A rule transforms the matching element into its right side:

FirstCase[{1,b->Automatic,c->3},_->Automatic]

Use (RefLink[HoldPattern, paclet:ref/HoldPattern]) to treat the rule itself as a pattern:

FirstCase[{1,b->Automatic,c->3},HoldPattern[_->Automatic]]

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(RefLink[Cases, paclet:ref/Cases])  ▪  (RefLink[FirstPosition, paclet:ref/FirstPosition])  ▪  (RefLink[SelectFirst, paclet:ref/SelectFirst])  ▪  (RefLink[First, paclet:ref/First])}})}})

({{DocumentationFooterIconsRelatedGuide.png, ({{Related Guides}, {▪(RefLinkPlain[Elements of Lists, paclet:guide/ElementsOfLists])}, {▪(RefLinkPlain[Function Composition & Operator Forms, paclet:guide/FunctionCompositionAndOperatorForms])}})}})