mustBeNonzero

Validate that value is nonzero

Syntax

mustBeNonzero(value)

Description

mustBeNonzero(value) throws an error if value is zero. This function does not return a value.

mustBeNonzero calls the eq function to determine if the input is not zero. (since R2026a)

Class support: All numeric classes, logical, and MATLAB^® classes that implement eq.

Examples

Validate That Values Are Not Zero

Use mustBeNonzero to validate that the input does not contain values that are zero.

A = sin([-1,0,1]);
mustBeNonzero(A)

Value must not be zero.

Restrict Property to Nonzero Values

This class restricts the value of Prop1 to be nonzero.

classdef MyClass
   properties
      Prop1 {mustBeNonzero}
   end
end

Create an object and assign a value to its property.

obj = MyClass;
obj.Prop1 = sin([-1,0,1]);

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

When you assign a value to the property, MATLAB calls mustBeNonzero with the value being assigned to the property. mustBeNonzero issues an error because the one of the values in A is zero.

Restrict Function Argument Values

This function declares two input arguments. Input A must be a numeric array and input offset must be a scalar that is not equal to zero.

function r = mbNonzero(A,offset)
    arguments
        A {mustBeNumeric}
        offset (1,1) {mustBeNonzero}
    end
    r = A + offset;
end

Calling the function with a value for offset equal to zero does not meet the requirements of mustBeNonzero and results in an error.

A = [12.7, 45.4, 98.9, 77.1, 53.1];
r = mbNonzero(A,0);

Error using mbNonzero (line 4)
 r = mbNonzero(A,0);
                 ^
Invalid argument at position 2. Value must not be zero.

Input Arguments

value — Value to validate

scalar | array

Value to validate, specified as a scalar or an array of one of these types:

• logical or numeric class

• MATLAB classes that implement eq

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | categorical | datetime | duration | table | timetable
Complex Number Support: Yes

Tips

• mustBeNonzero 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 Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Distributed Arrays

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

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

Version History

Introduced in R2017a

R2026a: mustBeNonzero no longer restricts input data to be numeric or logical

The mustBeNonzero function no longer calls the isnumeric and islogical functions to validate input. As a result, mustBeNonzero accepts any data type supported by the underlying comparison operator eq (or ==), such as character vectors, strings, and date and time types.

For example, the Interval property definition in MyClass restricts property values using the mustBeNonzero validation function.

classdef MyClass
   properties
      Interval {mustBeNonzero}
   end
end

You can now specify the property as a value of type duration.

A = datetime("yesterday");
B = datetime("today");
s = MyClass;
s.Interval = B - A;

In previous releases, specifying the Interval property as a duration value returned this error:

Error setting property 'Interval' of class 'MyClass'. Value must be numeric or logical.

To preserve the behavior of previous releases, explicitly use mustBeNumericOrLogical in your validation checks. For example, this code preserves the previous behavior of mustBeNonzero in the Interval property definition.

classdef MyClass
   properties
      Interval {mustBeNumericOrLogical,mustBeNonzero}
   end
end