nelson.lang.invalidHandle

Create an invalid handle with a specified handle class.

📝Syntax

h = nelson.lang.invalidHandle(classname)
h = nelson.lang.invalidHandle(classname, n)
h = nelson.lang.invalidHandle(classname, m, n, ...)
h = nelson.lang.invalidHandle(classname, sz)

📥Input Arguments

Parameter	Description
classname	name of a handle class as a character vector or string scalar.
n, m, sz	nonnegative integer dimensions for the returned handle array.

📤Output Arguments

Parameter	Description
h	an invalid handle scalar or handle array whose class is classname.

📄Description

nelson.lang.invalidHandle creates a handle value that has the requested handle class but is not valid.

isvalid(h) returns false for every element of the result.

The class name must identify a classdef handle class. Value classes and unknown class names raise an error.

With no dimension arguments, the result is a scalar. With one numeric scalar dimension n, the result is n-by-n. With multiple scalar dimensions or a numeric vector sz, the result has those dimensions.

This function is useful for APIs that need to preserve the class of a missing handle target.

The returned value behaves like a handle array for class, size, concatenation with compatible handle arrays, and isvalid. It has no live object behind it.

Invalid handles are not made valid later. To obtain a live handle, construct a new object of the same class.

All dimensions must be nonnegative integer values. Empty dimension vectors create an empty handle array.

A single scalar dimension follows the same convention as common array constructors: nelson.lang.invalidHandle(classname, 3) returns a 3-by-3 array.

The class is loaded before the handle array is created. This allows user-defined handle classes on the path to be used by name.

Use nelson.lang.HandlePlaceholder when no more specific handle class is available.

💡Examples

Create an invalid placeholder handle.

h = nelson.lang.invalidHandle('nelson.lang.HandlePlaceholder');
class(h)
isvalid(h)

Create an invalid handle array.

h = nelson.lang.invalidHandle('nelson.lang.HandlePlaceholder', 2, 3);
size(h)
isvalid(h)

Create an invalid handle array from a size vector.

h = nelson.lang.invalidHandle("nelson.lang.HandlePlaceholder", [1 4]);
size(h)
class(h)
isvalid(h)

Use a user-defined handle class.

d = [tempdir(), 'nelson_help_invalid_handle/'];
mkdir(d);
filewrite([d, '/NelsonHelpInvalidHandleTarget.m'], ["classdef NelsonHelpInvalidHandleTarget < handle"; "end"]);
addpath(d);
h = nelson.lang.invalidHandle('NelsonHelpInvalidHandleTarget');
class(h)
isvalid(h)

Reject a value class name.

try
  nelson.lang.invalidHandle('double');
catch exception
  disp(exception.message)
end

🕔Version History

Version	Description
2.0.0	initial version

Edit this page on GitHub