# What does this syntax involving Entity mean?

I came across a different style of input while defining functions. Though I tried playing with this form, I have not understood how to interpret this input.

Country[country:Entity["Country", _]]:=

How different is it from the below-given input that I usually follow?

Country[country_String]:=
• Entity is an object that represents a real world bit of data with properties and things like that. Check the entity framework docs for more. – b3m2a1 Nov 18 '18 at 4:41
• @b3m2a1 I know about Entity. I am not sure as to what does this input mean w.r.t the first code Country["Bahamas"]. – exp ikr Nov 18 '18 at 4:46
• I'm unclear as to what the confusion is, unfortunately. Mathematica objects are basically structural and some Entity["Country", "Bahamas"] is the true form of the Bahamas entity. The first definition just means have the function take an Entity as input. – b3m2a1 Nov 18 '18 at 5:11

In Mathematica, the part that goes inside the brackets in a function definition can be any pattern. Thus, here is a valid function definition and usage:

f[xyz[x_, y_], qwerty[z_]] := {x, y, z}
f[xyz[1, 2], qwerty[3]]

{1, 2, 3}

f[xy[1,2], qwerty[3]] f.e. will not evaluate at all because the arguments don't match the pattern.

Here is another example utilizing the : style of labeling parts of the pattern:

f[list : {foo[_], bar[_]}] := list
f[{foo[1], bar[2]}]

{foo[1], bar[2]}

In this case, list is a label for the expression that follows, but the function will not evaluate at all if the pattern does not match the input, so e.g. f[{fo[1], bar[2]}] will not evaluate.

Entities are usually rendered like this in the frontend:

but like for all other typeset things in the frontend, there is also a plain text equivalent:

From the point of view of pattern matching, it is the plain text version that matters. Consequently, we may write

f[country: Entity["Country", _]]:= country

This will only evaluate if the input argument is in the form Entity["Country", (*Anything goes here*)]. Otherwise, it won't evaluate at all, just like in the examples that I showed earlier.

Some examples:

The country does not have to exist for this function definition to match:

This is very different from the other function definition that you mention. f[country_String]. You can only pass a string to this function, a function defined in that way will not evaluate on entities. If you are writing a function that deals with countries, it will often be desired to have them play nicely with the built-in country entities, and then you would instead use the f[country: Entity["Country", _]] definition.

You could also use a hybrid:

Now you have a flexible function that can accept both country names as strings and countries as entities.