Must a Function be in Scope Before Creating a Handle to It?

The doc page Create Function Handle states:

"Keep the following in mind when creating handles to functions:

• Scope — The function must be in scope at the time you create the handle. Therefore, the function must be on the MATLAB path or in the current folder."

Trying to verify that statement ....

Verify a proposed function name is not currently in scope

exist xyzzy

ans = 0

But we can create a handle to this non-existent function (seemingly contra to the doc page)

f = @xyzzy;

Error is generated if trying to use the handle, of course.

try
    f()
catch ME
    ME.message
end

ans = 'Unrecognized function or variable 'xyzzy'.'

After generating the handle we can create the function (typically through the editor, or renaming an existing file, or ....)

str = ["function a = xyzzy";"a=1;"];
writelines(str,"xyzzy.m");
type xyzzy.m

function a = xyzzy
a=1;

And now the function handle executes

f()

ans = 1

Am I misunderstanding something about that doc page, or is the the doc page wrong, or does the doc page reflect how Matlab is supposed to work and the preceding code indicates a bug of some sort?

Answer 1

[dpb]

I believe that particular item in the documentation was written with an unstated (and perhaps not recognized having done) implicit assumption by the author that the subsequent created function handle is valid to be exectued immediately after the the handle is created whereas, as your code demonstrates, a handle to a non-existing function can be created, just not used until a function matching the prototype does exist and is in scope.

Normally, as the documentation states, the function handle contains the complete path to the function; however, if it does not exist then the path to it doesn't exist, either. But, when/if a function handle variable is store'ed, the file path is not save'ed, either, so if/when reloaded the (perhaps formerly valid) handle will also be invalid unless the function is in scope at that time.

Probably some amplification of the documentation would be in order, but I believe the behavior is as designers intended. Of course, with the propretary language, whatever the actual design specification says isn't available to be studied for conformance nor is there a formal procedure to ask for a standards review of an arcane language corner as with languages with official Standards.

[Paul]

Hi dpb,

That statement in unequivocal. If the behavior shown is as the developers intended, the doc needs to be corrected. I also suspect that the doc page is suspect in the section Saving and Loading Function Handles, but I haven't done any testing.

[dpb]

Agreed -- the author of the documentation is rarely the developer and the documentation is not the design document or internal standard, however Mathworks controls/specifies functionality. It is not necessarily an easy thing to translate from the actual design documentation to an easily understood summary of behavior that is complete and entirely accurate and if, as hypothesized, the author of the documentation is thinking in a particular way while making that translation, such a misstatement may result. If the condition I gave were true, then the statement is accurate; it just doesn't match what the implementation does (and, as @Steven Lord's comment later on shows, that a function can be resolved later is not unexpected MATLAB behavior).

The documentation could use some amplification/clarification, indeed, but to expand to cover all possibilities is probably not practical, either, owing to the myriad of possible outcomes given how code could be constructed.

[Paul]

I've always wondered if the developers review the documentation to make sure intent and functionality is documented correctly.

If the documentation doesn't cover all possibilities, then the Matlab user doesn't know if code that uses an undocumented possibility is working as intended or not.

Writing documentation that is complete and entirely accurate might not be easy, but it is important to strive to do so, IMO.

[dpb]

No disagreement, but for a commercial company with a proprietary product, there's a real tradeoff between throroughness and the cost.

Unlike with a language such as Fortran or C/C++ with a publicly available Standard that can be verified against, Mathworks doesn't publish the actual design document for competitive advantage reasons.

For the user there are tradeoffs between the convenience of the packaged toolset for which one price is that it is proprietary and some features simply may not be completely documented.

I have found, however, that Mathworks does take enhancement requests seriously regarding the documentation and I'm sure if this were entered into the official enahncement/bug database by submitting a formal report/support request, it would (at least eventually) be reivewed and some edits made to more closely reflect actual behavior. @Steven Lord didn't mention doing so, but he may well although I'd recommend going ahead.

The other area is that of backwards compatibility; Standard languages progress at a relative snail's pace and very few changes are made that will "break" existing code. OTOH, Mathworks changes how stuff works virtually every release. Of course, they also introduce new (and often very useful) features regularly as well.

[dpb]

ADDENDUM: " to cover all possibilities is probably not practical, "

For clarification, I wrote the above because MATLAB documentation tends to be example-based more so than specification-based. If the design spec were reiterated, the intent at least could be documented albeit probably at a significant cost in readability. One could compare reading the Fortran Standard itself as opposed to the compiler vendor's programmers' language reference manual; translating/interpreting the Standard-speak into plain English isn't always a trivial task outside the formal specification language.

Then, of course, there's still always the possibility that the actual implementation doesn't quite match the actual specification as well...and that as noted earlier and as illustrated here with the later example posted by John D'Errico, behavior changes on occasion. Whether this particular change is from a revsion/update to the undisclosed internal specification or a bug/omission fix in that the prior implementation didn't meet the specification is indeterminate outside Mathworks and they're probably not saying unless it were to make one of the release notes.

[Steven Lord]

I've always wondered if the developers review the documentation to make sure intent and functionality is documented correctly.

Yes, they do. The developers work closely with the documentation staff.

If the documentation doesn't cover all possibilities, then the Matlab user doesn't know if code that uses an undocumented possibility is working as intended or not.

In cases like that, it's perfectly reasonable to submit a request to Technical Support asking 1) if the functionality is working correctly / as intended and/or 2) for it to be included in the documentation.

Writing documentation that is complete and entirely accurate might not be easy, but it is important to strive to do so, IMO.

The PDF documentation for MATLAB has a book, MATLAB Function Reference, that includes the reference pages for all the documented functions that are part of the product MATLAB (as far as I'm aware.) It doesn't go into all the details for all the functions. I strongly doubt any one person has read through it, cover to cover. [I certainly have not. Maybe some AI system has included it in its training set, but that's different.]

Why do I doubt this? It's 19828 pages long! For comparison, one of the prototypical "long books" that people usually refer to when they want to emphasize something taking a long time to read is War and Peace. The function reference book is over 16 War and Peaces in length.

functionReference = 19828;
warAndPeace = 1225;
lengthOfFunctionReferenceInWarAndPeaces = functionReference./warAndPeace

lengthOfFunctionReferenceInWarAndPeaces = 16.1861

I don't know how much longer a document it would be if it discussed every detail, edge case, and corner case of every function. Twice as long? Three times? How much of that document would people actually read?

OTOH, Mathworks changes how stuff works virtually every release. Of course, they also introduce new (and often very useful) features regularly as well.

If you wanted to be technical, we change "how stuff works" every single release. Every bug fix, every new function, even fixing a crash is technically at least a potential backwards incompatibility. [See the obligatory XKCD.] I seem to recall recently people complaining on Answers that we had caused problems in their code when we introduced the settings function a few years back and started shadowing their functions by that name, as one example. We do take compatibility into consideration when reviewing the designs for new features/functionality and often do when reviewing bug fixes as well.

[dpb]

Thanks for the comments, Steven...

Is there anything in the PDF documentation for MATLAB book, other than the content of the online documentation reformatted? I had always presumed they were identical content, the book just being created from the other doc so there wasn't really anything to be gained by wading through it line by line. (Although I'll note the page count is very high in part owing to the formatting that every section begins a new page while Tolstoy's publishers didn't begin each paragraph on a new page <vbg>)

One thing compared to the Programmers Reference Manual for a language such as Fortran is that MATLAB includes so much more functionality by bundling all the math matrix algebra, diff-eq, and graphics functions, etc., etc., etc., into the one package as opposed to also having to document IMSL, BLAS/LAPACK, etc., etc., etc., which also adds up to something approaching at least similar volume.

I'm still curious, though, about how MATLAB actually documents the design requirements -- does TMW have its own Standard language like J3 or similar or do they have another way of actually writing the specification...