mustBePositive

Validate that value is positive

Syntax

mustBePositive(value)

Description

mustBePositive(value) throws an error if value is not positive. Values are positive when they are real, numeric, and greater than zero. This function does not return a value.

mustBePositive calls these functions to determine if the input is not positive:

• isreal

• isnumeric or islogical

• gt

Class support: All numeric classes, logical, and MATLAB^® classes that overload the functions called by mustBePositive.

This function ignores input arguments that are empty values. Therefore, no error is thrown when the property or function argument value is empty.

Examples

Validate That Values Are Positive

Use mustBePositive to validate that the input contains only positive values.

The rand function creates a uniformly distributed random number.

A = rand(1,5) -0.5;

Validate that array elements are positive.

mustBePositive(A)

Value must be positive.

The result of subtracting 0.5 from the array return by rand can contain negative numbers. When a value is negative, mustBePositive issues an error.

Restrict Property Values

This class restricts the value of Prop1 to positive values.

classdef MyClass
   properties
      Prop1 {mustBePositive}
   end
end

Create an object and assign a value to its property.

obj = MyClass;
obj.Prop1 = 0;

Error setting property 'Prop1' of class 'MyClass'. Value must be positive.

When you assign a value to the property, MATLAB calls mustBePositive with the value being assigned to the property. mustBePositive issues an error because the value 0 is not positive.

Restrict Function Argument Values

This function declares two input arguments. Input A must be a numeric vector. Input ix must be a positive integer.

function r = mbPositive(A,ix)
    arguments
        A (1,:) {mustBeNumeric}
        ix {mustBePositive, mustBeInteger}
    end
    r = A(ix);
end

Calling the function with a value for ix that does not meet the requirement of mustBePositive results in an error.

A = 1:10;
ix = 0;
r = mbPositive(A,ix);

Error using mbPositive (line 4)
 r = mbPositive(A,ix);
                  ^^
Invalid argument at position 2. Value must be positive.

Input Arguments

value — Value to validate

scalar | array

Value to validate, specified as a scalar or an array of one of the following:

• logical or numeric class

• MATLAB classes that implement gt, isreal, and either isnumeric or islogical

Tips

• mustBePositive is designed to be used for property and function argument validation.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The mustBePositive function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2017a