Advanced Operations on Function Handles

Examining a Function Handle

Use the functions function to examine the contents of a function handle.

    Caution   MATLAB® provides the functions function for querying and debugging purposes only. Because its behavior may change in subsequent releases, you should not rely upon it for programming purposes.

The following example is a continuation of an example in an earlier section of the Function Handles documentation. See Example 1 in the section Capture Data Values For Later Use By a Function for the complete example.

Construct a function handle that contains both a function association, and data required by that function to execute. The following function constructs the function handle, h:

function h = get_plot_handle(lnSpec, lnWidth, mkEdge, ...
   mkFace, mkSize)
h = @draw_plot;
    function draw_plot(x, y)
        plot(x, y, lnSpec, ...
            'LineWidth', lnWidth, ...
            'MarkerEdgeColor', mkEdge, ...
            'MarkerFaceColor', mkFace, ...
            'MarkerSize', mkSize)
    end
end

Use functions to examine the contents of the returned handle:

f = functions(h)
f = 
     function: 'get_plot_handle/draw_plot'
         type: 'nested'
         file: 'D:\matlab\work\get_plot_handle.m'
    workspace: {[1x1 struct]}

The call to functions returns a structure with four fields:

  • function — Name of the function or local function to which the handle is associated. (Function names that follow a slash character (/) are implemented in the program code as local functions.)

  • type — Type of function (e.g., simple, nested, anonymous)

  • file — Filename and path to the file. (For built-in functions, this is the string 'MATLAB built-in function')

  • workspace — Variables in the function workspace at the time the handle was constructed, along with their values

Examine the workspace variables that you saved in the function handle:

f.workspace{:}
ans = 
            h: @get_plot_handle/draw_plot
       lnSpec: '--rs'
      lnWidth: 2
     mrkrEdge: 'k'
     mrkrFace: 'g'
     mrkrSize: 10

Converting to and from a String

Two functions, str2func and func2str enable you to convert between a string containing a function name and a function handle that is associated with that function name.

Converting a String to a Function Handle

Another means of creating a function handle is to convert a string that holds a function name to a handle for the named function. You can do this using the str2func function:

handle = str2func('functionname');

The example below takes the name of a function as the first argument. It compares part of the name to see if this is a polynomial function, converts the function string to a function handle if it is not, and then calls the function by means of its handle:

function run_function(funcname, arg1, arg2)
if strncmp(funcname, 'poly', 4)
    disp 'You cannot run polynomial functions on this data.'
    return
else
   h = str2func(funcname);
   h(arg1, arg2);
end

    Note:   Nested functions are not accessible to str2func. To construct a function handle for a nested function, you must use the function handle constructor, @.

Converting a Function Handle to a String

You can also convert a function handle back into a string using the func2str function:

functionname = func2str(handle);

This example converts the function handle h to a string containing the function name, and then uses the function name in a message displayed to the user:

function call_h(h, arg1, arg2) 
sprintf('Calling function %s ...\n', func2str(h))
h(arg1, arg2)

Comparing Function Handles

This section describes how MATLAB determines whether or not separate function handles are equal to each other:

Comparing Handles Constructed from a Named Function

MATLAB considers function handles that you construct from the same named function (e.g., handle = @sin) to be equal. The isequal function returns a value of true when comparing these types of handles:

func1 = @sin;
func2 = @sin;
isequal(func1, func2)
 ans =
     1

If you save these handles to a MAT-file, and then load them back into the workspace later on, they are still equal.

Comparing Handles to Anonymous Functions

Unlike handles to named functions, any two function handles that represent the same anonymous function (i.e., handles to anonymous functions that contain the same text) are not equal. This is because MATLAB cannot guarantee that the frozen values of non-argument variables (such as A, below) are the same.

A = 5;
h1 = @(x)A * x.^2;
h2 = @(x)A * x.^2;

isequal(h1, h2)
ans =
     0

    Note:   In general, MATLAB may underestimate the equality of function handles. That is, a test for equality may return false even when the functions happen to behave the same. But in cases where MATLAB does indicate equality, the functions are guaranteed to behave in an identical manner.

If you make a copy of an anonymous function handle, the copy and the original are equal:

h1 = @(x)A * x.^2;   h2 = h1;
isequal(h1, h2)
ans =
     1

Comparing Handles to Nested Functions

MATLAB considers function handles to the same nested function to be equal only if your code constructs these handles on the same call to the function containing the nested functions. Given this function that constructs two handles to the same nested function:

function [h1, h2] = test_eq(a, b, c)
h1 = @findZ;
h2 = @findZ;

   function z = findZ
   z = a.^3 + b.^2 + c';
   end
end

function handles constructed from the same nested function and on the same call to the parent function are considered equal:

[h1 h2] = test_eq(4, 19, -7);

isequal(h1, h2),  
ans =
     1

while those constructed from different calls are not considered equal:

[q1 q2] = test_eq(3, -1, 2);

isequal(h1, q1)
ans =
     0

Comparing Handles Saved to a MAT-File

If you save equivalent anonymous or nested function handles to separate MAT-files, and then load them back into the MATLAB workspace, they are no longer equal. This is because saving the function handle loses track of the original circumstances under which the function handle was created. Reloading it results in a function handle that compares as being unequal to the original function handle.

Create two equivalent anonymous function handles:

h1 = @(x) sin(x);
h2 = h1;

isequal(h1, h2)
ans =
     1

Save each to a different MAT-file:

save fname1 h1;
save fname2 h2;

Clear the MATLAB workspace, and then load the function handles back into the workspace:

clear all
load fname1
load fname2

The function handles are no longer considered equal:

isequal(h1, h2)
ans =
     0

Note, however, that equal anonymous and nested function handles that you save to the same MAT-file are equal when loaded back into MATLAB.

Was this topic helpful?