Main Content

matlab.lang.invalidHandle

Construct array of invalid handles

Since R2024b

    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.

    example

    Examples

    collapse all

    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
    

    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

    collapse all

    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.

    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