Where in the documentation can I find a list of function argument types?

Question

Recently, I learned that it is possible to assign "types" to function arguments in the definition of a function. Suppose I have a function stringFun that does some operation (e.g., StringSplit) on an input string str. I could define the function in this way:

stringFun[str_] := StringSplit[str]

Or, I could define the argument str_ as being of type String:

stringFun[str_String] := StringSplit[str]

What other argument "types" exist in Mathematica? Can I use, for example, Real, List, or Table? I am using Mathematica 7, and I am having some difficulty locating a list of "types" in the documentation. Thanks for your time.

Answer 1

The notation foo[x_bar] := ... merely states that you're defining the function foo only for arguments that have the head bar. Here's a silly example to show you that:

Clear@foo
foo[x_bar] := First@x
foo[bar[2, 3]]
(* 2 *)

foo[{2, 3}]
(* foo[{2, 3}] *)

Note that the head can be any symbol (function) and not necessarily types such as string/real/integer, etc. Since everything in Mathematica is an expression which has a Head and possibly several Parts, you can create your own patterns to work only with certain heads as in the example above.

---

Differences between patterns with specific heads (_h) and equivalent pattern tests (_?hQ)

Probably a more important distinction is the difference between specifying heads in patterns and pattern tests for the same head, i.e. between, say, x_Integer and x_?IntegerQ. On the surface, they behave the same:

Clear[f, g]
f[x_Integer] := x^2
g[x_?IntegerQ] := x^2

{f[4], g[4]}
(* {16, 16} *)

but they have two important distinctions that are worth highlighting

1. Behaviour in functions with the HoldAll attribute

If your functions have the HoldAll attribute (or any Hold* attribute that has an equivalent effect on the pattern), the arguments are not evaluated by default. The latter form (using PatternTest) forces evaluation of the argument and hence is useful in this case. For example, slightly modifying the above:

Clear[f, g]
SetAttributes[#, HoldAll] & /@ {f, g};
f[x_Integer] := x^2
g[x_?IntegerQ] := x^2

{f[2 + 2], g[2 + 2]}
(* {f[2 + 2], 16} *)

2. Calls to the main evaluator

As Leonid notes, matches (or not) for patterns of the type x_foo are easily established by the pattern matcher, which can be very fast. On the other hand, the presence of a pattern test passes the evaluation to the main evaluator and introduces a sub-evaluation during the pattern matching and this can result in a big performance hit. As a simple example, consider the following:

Cases[Hold@{2, {Print["Evaluated!"]}, Pause[1.]}, _Integer, ∞] // AbsoluteTiming
(* {0.000028, {2}} *)

You can see that using the _Integer pattern did not result in evaluation of either the Print statement or the Pause statement. Now compare:

Cases[Hold@{2, {Print["Evaluated!"]}, Pause[1.]}, _?IntegerQ, ∞] // AbsoluteTiming
(* Evaluated!
   Evaluated!
   Evaluated!
   {2.000453, {2}} *)

You can see that the Print statement was evaluated as Cases walked through the expression tree (three times in total) and the Pause statement was executed twice.

So the take away message is that if you want to do something like strong type checking, then avoid PatternTests.

Answer 2

As J.M. pointed out: What you are matching is the Headof the expression. So basically you can match anything you like.

For example:

Head /@ {1, "a str", \[Pi], myWrap[x]}
(* ==>
{Integer, String, Symbol, myWrap}
*)

So you can define a function that only accepts "wrapped" expressions:

ClearAll[f]
f[exp_myWrap] := exp[[1]];
f /@ {1, "a str", Pi, myWrap[x]}

(* ==> {f[1], f["a str"], f[Pi], x} *)    

Answer 3

To save me having to remember the syntax each time, I have this current list of names in an initialization section (Or put this at the top of you notebook, or any where you want to use this each time):

(*definitions used for parameter checking*)

integerStrictPositive = (IntegerQ[#] && # > 0 &);
integerPositive = (IntegerQ[#] && # >= 0 &);
numericStrictPositive = (Element[#, Reals] && # > 0 &);
numericPositive = (Element[#, Reals] && # >= 0 &);
numericStrictNegative = (Element[#, Reals] && # < 0 &);
numericNegative = (Element[#, Reals] && # <= 0 &);
bool = (Element[#, Booleans] &);
numeric = (Element[#, Reals] &);
integer = (Element[#, Integers] &);

Then in the function definiitions, I use the above as

listClass[
  $size_?integer, $r0_?numericStrictPositive,
  .... ]:=Module[{},.....]

and so on.

This made it easier for me to use these checks since it a little easier to use as I do not have to look up the correct syntax each time as I did before.

I have a note in my FAQ on this with more documentation here http://alturl.com/a3p66