Function Repository Resource:

FailIfUnevaluated

Source Notebook

Test if a function doesn't evaluate for given arguments

Contributed by: Sjoerd Smit

ResourceFunction["FailIfUnevaluated"][sym]

returns the value of a symbol if it evaluates and returns $Failed otherwise.

ResourceFunction["FailIfUnevaluated"][head[args…]]

returns the result of head[args…] if the evaluation is non-trivial and $Failed otherwise.

ResourceFunction["FailIfUnevaluated"][expr, default]

returns default instead of $Failed.

Details

For composite expressions, ResourceFunction["FailIfUnevaluated"] will first evaluate head and then args in accordance with the Attributes associated with head. After that, the full expression is tested to see if it evaluates in a non-trivial way.

Any evaluation associated with just the head or just the arguments is considered to be trivial.

ResourceFunction["FailIfUnevaluated"] is intended as a robust way to detect when built-in functions like Solve fail by returning unevaluated.

ResourceFunction["FailIfUnevaluated"] has the attribute HoldAllComplete.

Examples

Basic Examples (2)

Evaluate a symbol with a value:

In[1]:=

Out[1]=

A symbol without value gives $Failed:

In[2]:=

Out[2]=

This expression only evaluates in its arguments, the head f has no effect:

In[3]:=

Out[3]=

FailIfUnevaluated detects this and considers this a trivial evaluation:

In[4]:=

Out[4]=

It does not simply test if the head remains the same. This is an example of a non-trivial evaluation that FailIfUnevaluated allows:

In[5]:=

Out[6]=

Scope (4)

If the head evaluates on its own but afterwards no further evaluation takes place, FailIfUnevaluated will give $Failed:

In[7]:=

In[8]:=

Out[8]=

This fails because f is taken to be no more than a simple alias for g:

In[9]:=

Out[9]=

This will not fail:

In[10]:=

Out[11]=

In[12]:=

Out[12]=

However, if the whole expression transforms into another inert expression, this is still counted as a non-trivial evaluation:

In[13]:=

ClearAll[h, k];
h[x_] := k[x];
ResourceFunction["FailIfUnevaluated"][h[2 + 2]]

Out[15]=

Use a different default:

In[16]:=

Out[16]=

The default does not evaluate if it's not needed:

In[17]:=

Out[17]=

FailIfUnevaluated respects attributes of the head while testing for evaluation semantics:

In[18]:=

ClearAll[f];
SetAttributes[f, HoldFirst]
f[n_Integer] := n^2;

This expression evaluates:

In[19]:=

Out[19]=

In[20]:=

Out[20]=

This expression doesn't evaluate because of the HoldFirst attribute, which causes FailIfUnevaluated to fail:

In[21]:=

Out[21]=

In[22]:=

Out[22]=

The action of the Listable and Flat attributes is considered non-trivial, even if the original head does not evaluate afterwards:

In[23]:=

Out[23]=

In[24]:=

Out[24]=

In[25]:=

In[26]:=

Out[26]=

In[27]:=

Out[27]=

When the Orderless attribute sorts the arguments, this is counted as a trivial evaluation:

In[28]:=

Out[28]=

In[29]:=

Out[29]=

Applications (3)

Due to the symbolic nature of the language, many Wolfram Language functions stay unevaluated when given unsupported arguments:

In[30]:=

Out[30]=

In[31]:=

Out[31]=

This can be easily detected by FailIfUnevaluated:

In[32]:=

Out[32]=

In[33]:=

Out[33]=

Note that FailIfUnevaluated does not test for a specific return value. In the following examples, Or returns the same result, but the second example represents a partial evaluation which is considered non-trivial:

In[34]:=