({{, (RefLink[FirstPosition, paclet:ref/FirstPosition])[expr,pattern] 
gives the position of the first element in expr that matches pattern, or (RefLink[Missing, paclet:ref/Missing])["NotFound"] if no such element is found.}, {, (RefLink[FirstPosition, paclet:ref/FirstPosition])[expr,pattern,default]
gives default if no element matching pattern is found.}, {, (RefLink[FirstPosition, paclet:ref/FirstPosition])[expr,pattern,default,levelspec]
finds only objects that appear on levels specified by levelspec. }, {, (RefLink[FirstPosition, paclet:ref/FirstPosition])[pattern]
represents an operator form of (RefLink[FirstPosition, paclet:ref/FirstPosition]) that can be applied to an expression.}})

OpenersNotesSection(Spacer1)Details and Options

In (RefLink[FirstPosition, paclet:ref/FirstPosition])[expr,pattern,default], default is evaluated only if no element matching pattern is found.

The expression expr can be a list, an association, or any other type of expression. In the case of an association, (RefLink[FirstPosition, paclet:ref/FirstPosition]) gives a key.

The default level specification for (RefLink[FirstPosition, paclet:ref/FirstPosition]) is {0,(RefLink[Infinity, paclet:ref/Infinity])}, with (RefLink[Heads, paclet:ref/Heads])->(RefLink[True, paclet:ref/True]).

A part specification {} returned by (RefLink[FirstPosition, paclet:ref/FirstPosition]) represents the whole of expr.

(RefLink[FirstPosition, paclet:ref/FirstPosition])[list,pattern,default,{1},(RefLink[Heads, paclet:ref/Heads])->(RefLink[False, paclet:ref/False])] finds positions only of objects that appear as complete elements of list.

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

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 0 corresponds to the whole expression.

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

(RefLink[FirstPosition, paclet:ref/FirstPosition]) traverses expressions in depth-first order.

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

OpenersPrimaryExamplesSection(Spacer1)Examples  (12)

OpenersExampleSection0(Spacer1)Basic Examples  (3)

Find the first position at which b occurs:

FirstPosition[{a,b,a,a,b,c,b},b]

FirstPosition[{{a,a,b},{b,a,a},{a,b,a}},b]

FirstPosition[{x,y,z},b]

Find the first position at which x to any power appears:

FirstPosition[{1+x^2,5,x^4,a+(1+x^2)^2},x^_]

Find the first position in an (RefLink[Association, paclet:ref/Association]):

FirstPosition[<|{1->1+x^2,2-><|"a"->x^2|>,3->x^4,4->a+(1+x^2)^2}|>,x^_]

OpenersExampleSection1(Spacer1)Scope  (4)

Use a position operator:

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

Find the first position with a prime value:

FirstPosition[<|"a"->1,"b"->2,"c"->3,"d"->4|>,_Integer?PrimeQ]

Specify a custom default value:

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

Look for 3 anywhere:

FirstPosition[{{1,2},{2,3},{3,1}},3]

Look for only a 3 that appears as an element of the outermost list:

FirstPosition[{{1,2},{2,3},{3,1}},3,Missing["NotFound"],{1}]

OpenersExampleSection2(Spacer1)Options  (1)

OpenersExampleSubsection0(Spacer1)Heads  (1)

By default, (RefLink[FirstPosition, paclet:ref/FirstPosition]) will search expression heads:

FirstPosition[x^2+y^2,Power]

Use the option (RefLink[Heads, paclet:ref/Heads])->(RefLink[False, paclet:ref/False]) to exclude them:

FirstPosition[x^2+y^2,Power,Heads->False]

OpenersExampleSection3(Spacer1)Properties & Relations  (3)

The default value is only evaluated if needed:

FirstPosition[{1015177, "Junk",EndOfFile},_?PrimeQ,Print["CriticalError"];$Failed]

FirstPosition[{1015177, 2015177,3015177},_?PrimeQ,Print["CriticalError"];$Failed]

Use (RefLink[Extract, paclet:ref/Extract]) to extract parts based on results from (RefLink[FirstPosition, paclet:ref/FirstPosition]):

u={1+(x^2),5,(x^4),a+(((1+(x^2)))^2)};

FirstPosition[u,x^_]

Extract[u,%]

(RefLink[FirstPosition, paclet:ref/FirstPosition]) returns only the first position:

FirstPosition[{a,b,b,a,a,c},a]

(RefLink[Position, paclet:ref/Position]) returns all positions:

Position[{a,b,b,a,a,c},a]

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

FirstPosition[{a,b,b,a,a,c},b]
FirstPosition[{a,b,b,a,a,c},d]

Replace[Position[{a,b,b,a,a,c},b],{{}:>Missing["NotFound"],l_:>First[l]}]
Replace[Position[{a,b,b,a,a,c},d],{{}:>Missing["NotFound"],l_:>First[l]}]

OpenersExampleSection4(Spacer1)Possible Issues  (1)

(RefLink[FirstPosition, paclet:ref/FirstPosition]) searches based on patterns, which may not be the same as numerical equality:

FirstPosition[Range[-1,1,0.05],0.1]

Write a pattern using (RefLink[Condition, paclet:ref/Condition]) to force searching based on numerical equality:

FirstPosition[Range[-1,1,0.05],n_ /; n==0.1]

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

({{DocumentationFooterIconsRelatedGuide.png, ({{Related Guides}, {▪(RefLinkPlain[Elements of Lists, paclet:guide/ElementsOfLists])}})}})

({{(Spacer1), ({{(Spacer1)Related Links}, {(WebLink[DocumentationFooterIconsRelatedLinks-EIWL.png(Spacer1)An Elementary Introduction to the Wolfram Language, https://www.wolfram.com/language/elementary-introduction/31-parts-of-lists.html])(WebLink[: Parts of Lists, https://www.wolfram.com/language/elementary-introduction/31-parts-of-lists.html])}})}})