A function is an object definition that includes clauses its Implementation section.

Function are most commonly used as part of clauses of other functions. For example,

{ a } => Simplify[a]

Some functions are tied to commands and are executed when that command is invoked. See Commands Overview

The list of clauses in an object definition are normally evaluated as if they were wrapped in an ElseList object. See The ElseList object for details. Clauses are normally only evaluated until one of them returns a non-null result.

If the function has the BuildAll property assigned to it, then the list of clauses in the object definition are evaluated as if they were wrapped in a List object. With the BuildAll property, all of the clauses are evaluated and the non-null results are returned as parameters of a List object.

Functions where none of the clauses generate a result will return the null object. This is different from other functional languages like Haskell where falling through the last clause in the function is an error.

Since any function can return null, the type of the null object has to be a subtype of every other type. In other words, the type of the null object has to be the bottom type of the type system. We have named the bottom type to be Null.

Functions can have extensions. This allows you to extend existing functions and commands if you create new libraries. Functions with extensions include clauses in the more than one library. See Extensions to Functions for details.

To speed processing, results of functions are normally cached. When a function is executed, the cache is tested before the function is executed to see if the parameters for the current call have been used previously and if so the result is provided by the cache rather than executing the function again. Functions that have the IsNotFunction property are not cached since they are not guaranteed to have the same result the next time they are called even when the function is called with the same parameters. An example is the GetClipboardExpression function that retrieve expressions from the clipboard.

Properties used on Functions

Properties that are used with functions include:

  • BuildAll

    The normal execution of a function starts with the first clause and proceeds until a clause produces a result other than the null object. Execution of a function with the BuildAll property is different because every clause is executed, independent of the number of clauses that produce results.

    If more than one clause generates a result that is not null, all of the generated results that aren’t null become a List object and that object is the returned value of the function.

    As an example, if the function is:

    then if this function is run with the BuildAll property, it will give a result like that shown in this unit test:

    List functions can either have the BuildAll property attached to them in their definition or they can have the BuildAll property attached to a specific call to the function.

    One common use for list functions is to build a choice of results that are displayed for the user using a popup window.

  • IsNotFunction

    The IsNotFunction property determines whether function results can be cached by the application. We can only cache results for functions that always return the same result when the function is called with the same parameters.