Method Syntax

This topic describes how to define class methods in MATLAB^® using methods...end blocks, and it introduces method argument validation. This topic focuses on nonstatic, concrete methods, also referred to as ordinary methods. For other types of methods, see:

Methods Definition Block

The methods and end keywords define one or more class methods that have the same attribute settings. The methods themselves are defined using MATLAB function blocks. The syntax for defining a block of ordinary methods is:

methods (attributes)
   function method1(obj,arg1,...)
      ...
   end
   function method2(obj,arg1,...)
      ...
   end
   ...
end

With the exception of static methods, you must pass an object of the class explicitly to a MATLAB method.

For example, this class defines one public property and two public methods. Each method takes two input arguments: the object itself and a user-provided argument inputArg. The methods calculate the product and quotient of the value of the class property, Property1, and the input argument.

classdef methodDemo
   properties
      Property1
   end
   methods
      function prod = propMultiply(obj,inputArg)
         prod = obj.Property1*inputArg;
      end
      function quotient = propDivide(obj,inputArg)
         quotient = obj.Property1/inputArg;
      end
   end
end

You can also define multiple method blocks with different attributes. In this example, the first method is protected, and the second method is private. For more information, see Method Attributes.

classdef attributeDemo
   methods (Access = protected)
      function out = method1(obj,inputArg)
         ...
      end
   end
   methods (Access = private)
      function out = method2(obj,inputArg)
          ...
      end
   end
end

Method Argument Validation

You can define restrictions for method input and output arguments. To validate method arguments, add arguments blocks to your methods in the same way you would with a function. See arguments for more information.

Input Argument Validation

Input argument validation enables you to restrict the size, class, and other characteristics of a method input argument. The syntax for input argument validation is:

arguments
   argName1 (dimensions) class {validators} = defaultValue
   ...
end

(dimensions) — Input size, specified as a comma-separated list of two or more numbers, such as (1,2).
class — Class, specified as a class name, such as double or the name of a user-defined class.
{validators} — Comma-separated list of validation functions, such as mustBeNumeric and mustBeScalarOrEmpty, enclosed in curly brackets. For a list of validation functions, see Argument Validation Functions.
defaultValue — Default values must conform to the specified size, type, and validation rules.

See arguments for the full description of elements in input argument validation syntax.

Input argument validation is useful for methods with public access. Restricting the types of argument values allowed from callers of the method can prevent errors before the body of the method is executed. For example, the Rectangle class represents a rectangle in the coordinate plane, with properties specifying its location (X and Y) as well as its width and height.

classdef Rectangle
    properties
        X (1,1) double {mustBeReal} = 0
        Y (1,1) double {mustBeReal} = 0
        Width (1,1) double {mustBeReal} = 0
        Height (1,1) double {mustBeReal} = 0
    end
    
    methods
        function R = enlarge(R,x,y)
            arguments (Input)
                R (1,1) Rectangle
                x (1,1) {mustBeNonnegative}
                y (1,1) {mustBeNonnegative}
            end
            arguments (Output)
                R (1,1) Rectangle
            end
            R.Width = R.Width + x;
            R.Height = R.Height + y;
        end
    end
end

The enlarge method increases the height and width of the rectangle by adding the user inputs x and y to Width and Height, respectively. Because the intent of the method is to enlarge one rectangle, the validation restricts the input arguments to scalar values with a (1,1) size restriction and nonnegative numeric values with mustBeNonnegative.

Instantiate the class, and call enlarge with inputs 5 and -1 to enlarge. The argument validation returns an error.

rect1 = Rectangle;
rect1.enlarge(5,-1))

Error using Rectangle/enlarge
 rect1.enlarge(5,-1)
                 ↑
Invalid argument at position 2. Value must be nonnegative.

Tip

The (Input) attribute for an input arguments block is optional, but it is recommended for readability when defining both input and output argument blocks in a single method. MATLAB interprets an argument block with neither attribute as an input argument block.

Output Argument Validation

The syntax for output argument validation is the same as input validation, except that you must specify (Output) as an attribute of the arguments block, and you cannot set a default value.

arguments (Output)
   argName1 (dimensions) class {validators}
   ...
end

See arguments for the full description of the output argument validation syntax.

Output argument validation enables class authors to document what type of outputs a method returns, as well as acting as a fail-safe against future changes to the code that might alter the output types. For example, the enlarge method of Rectangle uses output argument validation to ensure that the object method returns a scalar instance of Rectangle.

arguments (Output)
   R (1,1) Rectangle
end

If enlarge were later revised to return only the dimensions of the Rectangle and not the object itself, for example, the output validation would help catch this potential mistake.

Special Considerations for Validation in Methods

Argument validation for class methods works much like it does for functions, but some aspects of argument validation are unique to methods.

If a classdef file includes method prototypes for methods defined in separate files, any arguments blocks you want to define for those methods must be defined in the separate files. For more information on defining methods in separate files, see Methods in Separate Files.
Subclass methods do not inherit argument validation. To preserve argument validation in subclass methods that override superclass methods, repeat the argument validation from the superclass method in the subclass method.
Abstract methods do not support argument validation because they cannot define arguments blocks. For more information, see Abstract Classes and Class Members.
Handle class destructor methods cannot use argument validation. In handle classes, a destructor method named delete is called by MATLAB when a handle object becomes unreachable or is explicitly deleted with a call to delete. A destructor must have exactly one input, no outputs, and no argument validation. MATLAB treats a method defined in any other way as an ordinary method and does not use it as a destructor. For more information, see Handle Class Destructor.