matlab.lang.invalidHandle

Construct array of invalid handles

Since R2024b

Syntax

invArr = matlab.lang.invalidHandle(classname)

invArr = matlab.lang.invalidHandle(classname,sz1,...,szN)

Description

invArr = matlab.lang.invalidHandle(classname) returns an invalid handle to a scalar instance of classname. No object of classname is constructed.

invArr = matlab.lang.invalidHandle(classname,sz1,...,szN) returns an array of invalid handles with dimensions specified by sz1,...,szN.

Examples

Create Array of Invalid Handles

Create a 2-by-3 array of invalid handles to TrialData objects. (See the end of the example for the TrialData class code.)

h = matlab.lang.invalidHandle("TrialData",2,3)

h = 

  2×3 TrialData array with properties:

    trialNumber
    trialResults

Access one of the array elements to verify that it holds a handle to a deleted TrialData object.

h(1,1)

ans = 

  handle to deleted TrialData

Code for TrialData Class

classdef TrialData < handle
    properties
        trialNumber string = "A001"
        trialResults double = 0
    end
end

Set Default Value for Property Defined as WeakHandle

Properties defined using the WeakHandle attribute must use class validation. When WeakHandle properties define a default value, that default must be an empty array or an invalid handle array that satisfies the class validation.

Create a class that defines a WeakHandle property of class TrialData with size (1,3). (See the end of Create Array of Invalid Handles for the TrialData class code.) Use matlab.lang.invalidHandle to create a default value for the property.

classdef WeakDefault
   properties (WeakHandle)
      Prop1 (1,3) TrialData = matlab.lang.invalidHandle("TrialData",1,3)
   end
end

Construct an instance of the class.

wd = WeakDefault

wd = 

  WeakDefault with properties:

    Prop1: [1×3 TrialData]

Access one of the elements of wd.Prop1 to verify that it holds a handle to a deleted instance of TrialData.

wd.Prop1(1,1)

ans = 

  handle to deleted TrialData

Input Arguments

classname — Class for which to create invalid handle

string scalar | character vector

Class for which to create an invalid handle, specified as a string scalar or character vector. Valid inputs include names of fundamental MATLAB^® classes (see Fundamental MATLAB Classes) as well as user-defined classes.

sz1,...,szN — Size of each dimension

two or more integer values

Size of each dimension, specified as two or more integer values. The output is a sz1-by-...-by-szN array.

• If the size of any dimension is 0, then the output is an empty array.

• If the size of any dimension is negative, then it is treated as 0.

• If trailing dimensions greater than 2 have a size of 1, then the output does not include those dimensions. For example, matlab.lang.invalidHandle(classname,3,1,1,1) returns a 3-by-1 vector of invalid handles to objects of classname.

Tips

• matlab.lang.invalidHandle errors for classes that override copy in such a way that the method errors for invalid handles.

Version History

Introduced in R2024b