coder.nullcopy

Declare uninitialized variables in generated code

Syntax

X = coder.nullcopy(A)

Description

You can use coder.nullcopy to optimize the generated code by declaring uninitialized variables without copying variable values. Use coder.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 (MATLAB Coder) 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) 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, if A 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.

Examples

Declare a Variable Without Assigning Values

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 of 1 to each element of the array. Then, reassign values to each element of out by using a for-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 of out in a for-loop (lines 33 to 35 in the C code mapping). The generated code then reassigns values to the elements of out 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 a for-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 use coder.nullcopy, the generated code assigns values to the elements of out only once.

Declare Variable-Size Arrays Within Classes, Structures, or Cell Arrays

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 a for-loop.

• Assign values to variable-size out.field2 by using vectorization.

• Call coder.nullcopy directly on variable-size s.field3 and then assign values to out.field3 by using a for-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

A — Variable to copy

scalar | vector | matrix | class | structure | multidimensional array

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 as table.

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

Version History

Introduced in R2011a