Define Input Properties Programmatically in MATLAB File

How to Use `assert`

You can use the MATLAB^® assert function to define properties of primary function inputs directly in your MATLAB file.

Use the assert function to invoke standard MATLAB functions for specifying the class, size, and complexity of primary function inputs.

Specify Any Class

assert ( isa ( param, 'class_name') )

Sets the input parameter param to the MATLAB class class_name. For example, to set the class of input U to a 32-bit signed integer, call:

...
assert(isa(U,'embedded.fi'));
...

Note

If you set the class of an input parameter to fi, you must also set its numerictype, see Specify numerictype of Fixed-Point Input. You can also set its fimath properties, see Specify fimath of Fixed-Point Input.

If you set the class of an input parameter to struct, you must specify the properties of each field in the structure in the order in which you define the fields in the structure definition.

Specify fi Class

assert ( isfi ( param ) )
assert ( isa ( param, 'embedded.fi' ) )

Sets the input parameter param to the MATLAB class fi (fixed-point numeric object). For example, to set the class of input U to fi, call:

...
assert(isfi(U));
...

...
assert(isa(U,'embedded.fi'));
...

Note

Specify Structure Class

assert ( isstruct ( param ) )

Sets the input parameter param to the MATLAB class struct (structure). For example, to set the class of input U to a struct, call:

...
assert(isstruct(U));
...

...
assert(isa(U,'struct'));
...

Note

If you set the class of an input parameter to struct, you must specify the properties of each field in the structure in the order in which you define the fields in the structure definition.

Specify Cell Array Class

assert(iscell( param))
assert(isa(param, 'cell'))

Sets the input parameter param to the MATLAB class cell (cell array). For example, to set the class of input C to a cell, call:

...
assert(iscell(C));
...

...
assert(isa(C, 'cell'));
...

To specify the properties of cell array elements, see Specifying Properties of Cell Arrays.

Specify Any Size

assert ( all ( size (param) == [dims ] ) )

Sets the input parameter param to the size specified by dimensions dims. For example, to set the size of input U to a 3-by-2 matrix, call:

...
assert(all(size(U)== [3 2]));
...

Specify Scalar Size

assert ( isscalar (param ) )
assert ( all ( size (param) == [ 1 ] ) )

Sets the size of input parameter param to scalar. For example, to set the size of input U to scalar, call:

...
assert(isscalar(U));
...

...
assert(all(size(U)== [1]));
...

Specify Real Input

assert ( isreal (param ) )

Specifies that the input parameter param is real. For example, to specify that input U is real, call:

...
assert(isreal(U));
...

Specify Complex Input

assert ( ~isreal (param ) )

Specifies that the input parameter param is complex. For example, to specify that input U is complex, call:

...
assert(~isreal(U));
...

Specify numerictype of Fixed-Point Input

assert ( isequal ( numerictype ( fiparam ), T ) )

Sets the numerictype properties of fi input parameter fiparam to the numerictype object T. For example, to specify the numerictype property of fixed-point input U as a signed numerictype object T with 32-bit word length and 30-bit fraction length, use the following code:

...
% Define the numerictype object.
T = numerictype(1, 32, 30);

% Set the numerictype property of input U to T.
assert(isequal(numerictype(U),T));
...

Specify fimath of Fixed-Point Input

assert ( isequal ( fimath ( fiparam ), F ) )

Sets the fimath properties of fi input parameter fiparam to the fimath object F. For example, to specify the fimath property of fixed-point input U so that it saturates on integer overflow, use the following code:

...
% Define the fimath object.
F = fimath('OverflowAction','Saturate');

% Set the fimath property of input U to F.
assert(isequal(fimath(U),F));
...

Specify Multiple Properties of Input

assert ( function1 ( params ) && function2 ( params ) && function3 ( params ) && ... )

Specifies the class, size, and complexity of one or more inputs using a single assert function call. For example, the following code specifies that input U is a double, complex, 3-by-3 matrix, and input V is a 16-bit unsigned integer:

...
assert(isa(U,'double') && ~isreal(U) && all(size(U) == [3 3]) && isa(V,'uint16'));
...

Rules for Using assert Function

Follow these rules when using the assert function to specify the properties of primary function inputs:

Call assert functions at the beginning of the primary function, before any flow-control operations such as if statements or subroutine calls.
Do not call assert functions inside conditional constructs, such as if, for, while, and switch statements.
If you set the class of an input parameter to fi:
- You must also set its numerictype, see Specify numerictype of Fixed-Point Input.
- You can also set its fimath properties, see Specify fimath of Fixed-Point Input.
If you set the class of an input parameter to struct, you must specify the class, size, and complexity of each field in the structure in the order in which you define the fields in the structure definition.

Specifying Properties of Primary Fixed-Point Inputs

In the following example, the primary MATLAB function emcsqrtfi takes one fixed-point input: x. The code specifies the following properties for this input:

Property	Value
class	`fi`
`numerictype`	`numerictype` object `T`, as specified in the primary function
`fimath`	`fimath` object `F`, as specified in the primary function
size	`scalar` (by default)
complexity	`real` (by default)

function y = emcsqrtfi(x)
T = numerictype('WordLength',32,'FractionLength',23,...
      'Signed',true);
F = fimath('SumMode','SpecifyPrecision',...
      'SumWordLength',32,'SumFractionLength',23,...
      'ProductMode','SpecifyPrecision',...
      'ProductWordLength',32,'ProductFractionLength',23);
assert(isfi(x));
assert(isequal(numerictype(x),T));
assert(isequal(fimath(x),F));

y = sqrt(x);

Specifying Properties of Cell Arrays

To specify the MATLAB class cell (cell array), use one of the following syntaxes:

assert(iscell(param))
assert(isa( param, 'cell'))

For example, to set the class of input C to cell, use:

...
assert(iscell(C));
...

...
assert(isa(C, 'cell'));
...

You can also specify the size of the cell array and the properties of the cell array elements. The number of elements that you specify determines whether the cell array is homogeneous or heterogeneous. See Code Generation for Cell Arrays (MATLAB Coder).

If you specify the properties of the first element only, the cell array is homogeneous. For example, the following code specifies that C is a 1x3 homogeneous cell array whose elements are 1x1 double.

...
assert(isa(C, 'cell'));
assert(all(size(C) == [1  3]));
assert(isa(C{1}, 'double'));
...

If you specify the properties of each element, the cell array is heterogeneous. For example, the following code specifies a 1x2 heterogeneous cell array whose first element is 1x1 char and whose second element is 1x3 double.

...
assert(isa(C, 'cell'));
assert(all(size(C) == [1  2]));
assert(isa(C{1}, 'char'));
assert(all(size(C{2}) == [1 3]));
assert(isa(C{2}, 'double'));
...

If you specify more than one element, you cannot specify that the cell array is variable size, even if all elements have the same properties. For example, the following code specifies a variable-size cell array. Because the code specifies the properties of the first and second elements, code generation fails.

...
assert(isa(C, 'cell'));
assert(all(size(C) <= [1  2]));
assert(isa(C{1}, 'double'));
assert(isa(C{2}, 'double'));
...

In the previous example, if you specify the first element only, you can specify that the cell array is variable-size. For example:

...
assert(isa(C, 'cell'));
assert(all(size(C) <= [1  2]));
assert(isa(C{1}, 'double'));
...

Specifying Class and Size of Scalar Structure

Assume you have defined S as the following scalar MATLAB structure:

S = struct('r',double(1),'i',fi(4,true,8,0));

This code specifies the class and size of S and its fields when passed as an input to your MATLAB function:

function y = fcn(S)

% Specify the class of the input as struct.
assert(isstruct(S));

% Specify the size of the fields r and i
% in the order in which you defined them.
T = numerictype('Wordlength', 8,'FractionLength', ...
   0,'signed',true);
assert(isa(S.r,'double'));
assert(isfi(S.i) && isequal(numerictype(S.i),T));

y = S;

Note

The only way to name a field in a structure is to set at least one of its properties. Therefore in the preceding example, an assert function specifies that field S.r is of type double, even though double is the default.

Specifying Class and Size of Structure Array

For structure arrays, you must choose a representative element of the array for specifying the properties of each field. For example, assume you have defined S as the following 1-by-2 array of MATLAB structures:

S = struct('r',{double(1), double(2)},'i',...
   {fi(4,1,8,0), fi(5,1,8,0)});

The following code specifies the class and size of each field of structure input S using the first element of the array:

function y = fcn(S)

% Specify the class of the input S as struct.
assert(isstruct(S));
T = numerictype('Wordlength', 8,'FractionLength', ...
   0,'signed',true);

% Specify the size of the fields r and i
% based on the first element of the array.
assert(all(size(S) == [1 2]));
assert(isa(S(1).r,'double'));
assert(isfi(S(1).i) && isequal(numerictype(S(1).i),T));

y = S;

Note

The only way to name a field in a structure is to set at least one of its properties. Therefore in the example above, an assert function specifies that field S(1).r is of type double, even though double is the default.