Method Syntax - MATLAB & Simulink (original) (raw)

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 argumentinputArg. 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

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 inputs5 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.

See Also

arguments