Variable-Sizing Restrictions for Code Generation of Toolbox Functions - MATLAB & Simulink (original) (raw)
Common Restrictions
The following common restrictions apply to multiple toolbox functions, but only for code generation. To determine which of these restrictions apply to specific library functions, see the table in Toolbox Functions with Restrictions for Variable-Size Data.
Variable-length vector restriction
Inputs to the library function must be variable-length vectors or fixed-size vectors. A variable-length vector is a variable-size array that has the shape 1x:n or :nx1 (one dimension is variable sized and the other is fixed at size 1). Other shapes are not permitted, even if they are vectors at run time.
Automatic dimension restriction
This restriction applies to functions that take the working dimension (the dimension along which to operate) as input. In MATLAB® and in code generation, if you do not supply the working dimension, the function selects it. In MATLAB, the function selects the first dimension whose size does not equal 1. For code generation, the function selects the first dimension that has a variable size or that has a fixed size that does not equal 1. If the working dimension has a variable size and it becomes 1 at run time, then the working dimension is different from the working dimension in MATLAB. Therefore, when run-time error checks are enabled, an error can occur.
For example, suppose that X is a variable-size matrix with dimensions 1x:3x:5. In the generated code, sum(X) behaves like sum(X,2). In MATLAB, sum(X) behaves like sum(X,2) unless size(X,2) is 1. In MATLAB, when size(X,2) is 1, sum(X) behaves like sum(X,3).
To avoid this issue, specify the intended working dimension explicitly as a constant value. For example, sum(X,2).
Array-to-vector restriction
The function issues an error when a variable-size array that is not a variable-length vector assumes the shape of a vector at run time. To avoid the issue, specify the input explicitly as a variable-length vector instead of a variable-size array.
Array-to-scalar restriction
The function issues an error if a variable-size array assumes a scalar value at run time. To avoid this issue, specify scalars as fixed size.
Toolbox Functions with Restrictions for Variable-Size Data
The following table list functions that have code generation restrictions for variable-size data. For additional restrictions for these functions, and restrictions for all functions and objects supported for code generation, see Functions and Objects Supported for C/C++ Code Generation.
| Function | Restrictions for Variable-Size Data |
|---|---|
| all | See Automatic dimension restriction.An error occurs if you pass the first argument a variable-size matrix that is 0-by-0 at run time. |
| any | See Automatic dimension restriction.An error occurs if you pass the first argument a variable-size matrix that is 0-by-0 at run time. |
| cat | Dimension argument must be a constant. |
| conv | See Variable-length vector restriction.Input vectors must have the same orientation, either both row vectors or both column vectors. |
| cov | For cov(X), see Array-to-vector restriction. |
| cross | Variable-size array inputs that become vectors at run time must have the same orientation. |
| deconv | For both arguments, see Variable-length vector restriction. |
| detrend | For first argument for row vectors only, seeArray-to-vector restriction. |
| diag | See Array-to-vector restriction. |
| diff | See Automatic dimension restriction.Length of the working dimension must be greater than the difference order input when the input is variable sized. For example, if the input is a variable-size matrix that is 3-by-5 at run time, diff(x,2,1) works butdiff(x,5,1) generates a run-time error. |
| fft | See Automatic dimension restriction. |
| filter | For first and second arguments, see Variable-length vector restriction.See Automatic dimension restriction. |
| hist | For second argument, see Variable-length vector restriction.For second input argument, see Array-to-scalar restriction. |
| histc | See Automatic dimension restriction. |
| ifft | See Automatic dimension restriction. |
| ind2sub | First input (the size vector input) must be fixed size. |
| interp1 | For the xq input, see Array-to-vector restriction.If v becomes a row vector at run time, the array to vector restriction applies. Ifv becomes a column vector at run time, this restriction does not apply. |
| interpft | See Automatic dimension restriction. |
| ipermute | Order input must be fixed size. |
| issorted | See Automatic dimension restriction. |
| magic | Argument must be a constant.Output can be fixed-size matrices only. |
| max | See Automatic dimension restriction. |
| maxk | See Automatic dimension restriction. |
| mean | See Automatic dimension restriction.An error occurs if you pass as the first argument a variable-size matrix that is 0-by-0 at run time. |
| median | See Automatic dimension restriction.An error occurs if you pass as the first argument a variable-size matrix that is 0-by-0 at run time. |
| min | See Automatic dimension restriction. |
| mink | See Automatic dimension restriction. |
| mode | See Automatic dimension restriction.An error occurs if you pass as the first argument a variable-size matrix that is 0-by-0 at run time. |
| mtimes | Consider the multiplication A*B. If the code generator is aware that A is scalar and B is a matrix, the code generator produces code for scalar-matrix multiplication. However, if the code generator is aware that A and B are variable-size matrices, it produces code for a general matrix multiplication. At run time, if A turns out to be scalar, the generated code does not change its behavior. Therefore, when run-time error checks are enabled, a size mismatch error can occur. |
| nchoosek | The second input, k, must be a fixed-size scalar. The second input, k, must be a constant for static allocation. If you enable dynamic allocation, the second input can be a variable.You cannot create a variable-size array by passing in a variable, k, unless you enable dynamic allocation. |
| paddata | See Automatic dimension restriction. |
| permute | Order input must be fixed-size. |
| planerot | Input must be a fixed-size, two-element column vector. It cannot be a variable-size array that takes on the size 2-by-1 at run time. |
| poly | See Variable-length vector restriction. |
| polyfit | For first and second arguments, see Variable-length vector restriction. |
| prod | See Automatic dimension restriction.An error occurs if you pass as the first argument a variable-size matrix that is 0-by-0 at run time. |
| rand | For an upper-bounded variableN, rand(1,N) produces a variable-length vector of1x:M where M is the upper bound on N.For an upper-bounded variableN, rand([1 N]) may produce a variable-length vector of :1x:M whereM is the upper bound onN. |
| randi | For an upper-bounded variableN,randi(imax,1,N) produces a variable-length vector of 1x:M where M is the upper bound onN.For an upper-bounded variableN, randi(imax,[1 N]) may produce a variable-length vector of :1x:M whereM is the upper bound onN. |
| randn | For an upper-bounded variableN,randn(1,N) produces a variable-length vector of 1x:M where M is the upper bound onN.For an upper-bounded variableN, randn([1 N]) may produce a variable-length vector of :1x:M whereM is the upper bound onN. |
| reshape | If the input is a variable-size array and the output array has at least one fixed-length dimension, do not specify the output dimension sizes in a size vector sz. Instead, specify the output dimension sizes as scalar values, sz1,...,szN. Specify fixed-size dimensions as constants.When the input is a variable-size empty array, the maximum dimension size of the output array (also empty) cannot be larger than that of the input. |
| resize | See Automatic dimension restriction. |
| roots | See Variable-length vector restriction. |
| shiftdim | If you do not supply the second argument, the number of shifts is determined at compilation time by the upper bounds of the dimension sizes. Therefore, at run time the number of shifts is constant. An error occurs if the dimension that is shifted to the first dimension has length 1 at run time. To avoid the error, supply the number of shifts as the second input argument (must be a constant).First input argument must have the same number of dimensions when you supply a positive number of shifts. |
| sort | See Automatic dimension restriction. |
| std | See Automatic dimension restriction.An error occurs if you pass a variable-size matrix with 0-by-0 dimensions at run time. |
| sub2ind | First input (the size vector input) must be fixed size. |
| sum | See Automatic dimension restriction.An error occurs if you pass as the first argument a variable-size matrix that is 0-by-0 at run time. |
| trapz | See Automatic dimension restriction.An error occurs if you pass as the first argument a variable-size matrix that is 0-by-0 at run time. |
| trimdata | See Automatic dimension restriction. |
| typecast | See Variable-length vector restriction on first argument. |
| var | See Automatic dimension restriction.An error occurs if you pass a variable-size matrix with 0-by-0 dimensions at run time. |
| vecnorm | See Automatic dimension restriction. |