coder.nullcopy - Declare uninitialized variables in generated code - MATLAB (original) (raw)

Declare uninitialized variables in generated code

Syntax

Description

You can use coder.nullcopy to optimize the generated code by declaring uninitialized variables without copying variable values. Usecoder.nullcopy only in two specific situations:

• At code generation time, you see one of these errors:
  For code generation, all variables must be fully defined before use.
For code generation, all cell array elements must be fully defined before use.
  However, you have fully defined all variables and cell array elements on all execution paths, and you have considered and rejected other troubleshooting solutions. See Resolve Issue: Variables Must Be Fully Defined Before Use and Resolve Issue: Cell Array Elements Must Be Fully Defined Before Use.
• You see redundant variable assignments in the generated code. That is, a variable is assigned a value and then assigned a different value before it is used.

Use coder.nullcopy with caution. In most cases, the code generator automatically performs an optimization corresponding to coder.nullcopy, even if you do not include the coder.nullcopy function in your MATLAB® code. If you declare a variable using coder.nullcopy and do not fully assign the variable before you use it, the behavior of the generated code can be unpredictable.

`X` = coder.nullcopy([A](#mw%5F4ff48548-72e6-4379-8418-71100e1df231)) copies the type, size, and complexity of A to X, but does not copy element values. In the generated code,coder.nullcopy declares an uninitialized variable, preallocating memory for X without incurring the overhead of initializing memory. In MATLAB execution, coder.nullcopy returns the input value.

In most cases, coder.nullcopy applies recursively. That is, ifA is an aggregate type (a class, structure, or cell array),coder.nullcopy also preallocates memory for the fields, properties, or elements of A. However, if A is an aggregate type that contains one or more variable-size arrays, special considerations apply. See Declare Variable-Size Arrays Within Classes, Structures, or Cell Arrays.

Before you use or return X, you must assign values to all of its elements. Otherwise, the behavior of the generated code can be unpredictable.

example

Examples

collapse all

This example shows how to declare an array in the generated code, without the overhead of assigning a value to each element of the array.

Create a MATLAB function foo that returns an_n_-by-n matrix. Initialize the output matrix variable out by assigning a value of1 to each element of the array. Then, reassign values to each element of out by using afor-loop.

function out = foo(inp) %#codegen out = ones(inp); for idx = 1:inp*inp if mod(idx,2) == 0 out(idx) = idx; else out(idx) = idx + 1; end end

Generate C code for this function and examine the generated code. The C code explicitly assigns a value of 1.0 to each element ofout in a for-loop (lines 33 to 35 in the C code mapping). The generated code then reassigns values to the elements ofout in a second for-loop (lines 37 to 43).

Revise foo and use coder.nullcopy to declare out as an _n_-by-n matrix of doubles before assigning values to each element by using afor-loop.

function out = foo(inp) %#codegen out = coder.nullcopy(ones(inp)); for idx = 1:inp*inp if mod(idx,2) == 0 out(idx) = idx; else out(idx) = idx + 1; end end

Generate C code for this function and compare the generated code to the code generated without using coder.nullcopy. When you usecoder.nullcopy, the generated code assigns values to the elements of out only once.

When you call coder.nullcopy on an aggregate type (a class, structure, or cell array) that contains one or more variable-size arrays, you must also call coder.nullcopy directly on the variable-size arrays before assigning values by using a for-loop. This extra step is not necessary when you perform vectorized assignment or when the field, property, or cell array element is fixed-size.

For example, consider the function copyStructExample. This function returns a structure that has three fields, two of which are variable-size. Declare this structure by using coder.nullcopy and then assign values to each field.

• Assign values to fixed-size out.field1 by using afor-loop.
• Assign values to variable-size out.field2 by using vectorization.
• Call coder.nullcopy directly on variable-sizes.field3 and then assign values toout.field3 by using afor-loop.

function out = copyStructExample(n) %#codegen

s.field1 = ones(1,5); s.field2 = ones(1,n); s.field3 = ones(1,n); out = coder.nullcopy(s); % out is a structure with unassigned contents

for i = 1:5 out.field1(i) = i+2; end

out.field2 = 5:5:n*5;

out.field3 = coder.nullcopy(s.field3); for i = 1:n out.field3(i) = i*2; end end

Input Arguments

collapse all

Variable to copy, specified as a scalar, vector, matrix, structure, or multidimensional array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | struct | class
Complex Number Support: Yes

Limitations

• You cannot use coder.nullcopy on sparse matrices.
• You cannot use coder.nullcopy with classes that support overloaded parentheses or require indexing methods to access their data, such astable.

Extended Capabilities

Version History

Introduced in R2011a