coder.nullcopy

Declare uninitialized variables in code generation

Syntax

X = coder.nullcopy(A)

Description

X = coder.nullcopy(A) copies type, size, and complexity of A to X, but does not copy element values. The function preallocates memory for X without incurring the overhead of initializing memory. In code generation, the coder.nullcopy function declares uninitialized variables. In MATLAB^®, coder.nullcopy returns the input such that X is equal to A.

If X is a structure or a class containing variable-sized arrays, then you must assign the size of each array. coder.nullcopy does not copy sizes of arrays or nested arrays from its argument to its result.

Note

Before you use X in a function or a program, ensure that the data in X is completely initialized. Declaring a variable through coder.nullcopy without assigning all the elements of the variable results in nondeterministic program behavior. For more information, see How to Eliminate Redundant Copies by Defining Uninitialized Variables.

Examples

Declare a Variable Without Initialization

This example shows how to declare an array type variable without initializing any value in the array.

To generate code for the following function, you must fully declare the output variable outp as a n-by-n array of real doubles before subscripting into outp. To perform this declaration without initializing all the values in the array, use coder.nullcopy.

function outp = foo(n) %#codegen

outp = coder.nullcopy(ones(n));
for idx = 1:n*n
   if mod(idx,2) == 0
      outp(idx) = idx;
   else
      outp(idx) = idx + 1;
   end
end

Run this codegen command to generate code and launch report.

codegen -config:lib -c foo -args {0} -launchreport 

In the code generation report, click Trace Code to see the mapping between the MATLAB code and the generated code. To use the code traceability feature, you must have Embedded Coder^®.

The following figures show the comparison between the code generated with and without coder.nullcopy. Using coder.nullcopy with ones can specify the size of array outp without initializing each element to one.

If you do not use coder.nullcopy, the generated code explicitly initializes every element in outp to one (see lines 32 to 35).

Note

In some situations, the code generator automatically performs the optimization corresponding to coder.nullcopy, even if you do not explicitly include the coder.nullcopy directive in your MATLAB code.

Input Arguments

A — Variable to copy

scalar | vector | matrix | class | multidimensional array

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

Example: coder.nullcopy(A);

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | 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