coder.findOrError

Find indices and values of nonzero elements in an array in generated C/C++ code

Since R2026a

collapse all in page

Syntax

k = coder.findOrError(X,n)
k = coder.findOrError(X,n,direction)
[row,col] = coder.findOrError(___)
[row,col,v] = coder.findOrError(___)

Description

k = coder.findOrError(X,n) returns the first n linear indices corresponding to the nonzero elements in the array X. If you only provide the X argument, coder.findOrError uses the default value 1 for n.

  • If X is a vector, then k is a vector with the same orientation as X.

  • If X is a multidimensional array, then k is a column vector.

  • If X is a variable-size matrix at code generation time and a row vector at run time, then the output of the generated MEX function is a column vector, not a row vector.

In MATLAB® execution, if the array X contains fewer than n nonzero elements, coder.findOrError has the same behavior as find. For such inputs, code generation produces either a compile-time or a run-time error.

Note

Unlike the find function that always returns variable-length vectors in code generation, the coder.findOrError function returns vectors of fixed length n if the argument n is a constant during code generation. If the array X contains fewer than n nonzero elements, coder.findOrError produces either a compile-time or a run-time error.

example

k = coder.findOrError(X,n,direction), where direction is 'last', finds the last n indices corresponding to nonzero elements in X. The default for direction is 'first', which finds the first n indices corresponding to nonzero elements.

example

[row,col] = coder.findOrError(___) returns the row and column subscripts of the nonzero elements in array X using any of the input arguments in previous syntaxes.

[row,col,v] = coder.findOrError(___) also returns vector v, which contains the nonzero elements of X.

example

Examples

collapse all

In this example, you find the linear indices of the first n nonzero elements of a fixed-size matrix, where n is a constant during code generation. Because n is a constant, the output of coder.findOrError is a fixed-size vector of length n. This example uses a value of 3 for n.

Define an entry-point function locateFirstThreeNonzeroElements that returns the linear indices of the first three nonzero elements of a 3-by-4 matrix.

function k = locateFirstThreeNonzeroElements(X)
arguments
    X (3,4) double
end

k = coder.findOrError(X,3);
end

Because the expected number of nonzero elements is a constant, the output k has a fixed size of 3 in the generated code. In addition, the input array X is of fixed size as well. Therefore, you can disable support for variable-size arrays when generating code for this function.

Generate a MEX function for locateFirstThreeNonzeroElements that only uses fixed-size arrays.

cfg = coder.config("mex");
cfg.EnableVariableSizing = false;
codegen -config cfg locateFirstThreeNonzeroElements
Code generation successful.

Run the generated MEX function with an 3-by-4 input array. The function returns the linear indices of the first three nonzero elements of the input array.

locateFirstThreeNonzeroElements_mex([0 1 1 0; 0 0 0 0; 1 0 1 0])
ans =

  3×1 int32 column vector

   3
   4
   7

Run the generated MEX function with a different 3-by-4 input array that has only two nonzero elements. The function produces a run-time error.

locateFirstThreeNonzeroElements_mex([0 1 0 0; 0 0 0 0; 1 0 0 0])
Function coder.findOrError expects 3 non-zero elements, but receives 2.

In this example, you find the values of the last n nonzero elements of an unbounded variable-size row vector, where the value of n is provided at run time. Because n is a not a constant during code generation, the output of coder.findOrError is a variable-size vector.

Define an entry-point function findLastNNonzeroElements that returns the values of the last n nonzero elements of an unbounded variable-size row vector X.

function v = findLastNNonzeroElements(X,n)
arguments
    X (1,:) double
    n (1,1) double
end

[~,~,v] = coder.findOrError(X,n,"last");
end

Generate a MEX function for findLastNNonzeroElements with the default configuration settings. Because the input array X is unbounded variable size, the generated code must have support for both variable-size data and dynamic memory allocation enabled.

codegen findLastNNonzeroElements
Code generation successful.

Run the generated MEX function with example inputs. The function returns the linear indices of the first four nonzero elements of the input vector.

findLastNNonzeroElements_mex([1 3 0 0 0 3 4 2 0],4)
ans =

     3     3     4     2

Input Arguments

collapse all

Input array, specified as a scalar, vector, matrix, or multidimensional array.

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

Number of nonzeros to find, specified as a positive integer scalar.

Search direction, specified as the string "first" or "last". Look for the last n nonzero elements in X using find(X,n,"last").

Output Arguments

collapse all

Indices to nonzero elements, returned as a vector of int32 values.

You can return the nonzero values in X using X(k).

Row subscripts, returned as a vector of int32 values. Together, row and col specify the X(row,col) subscripts corresponding to the nonzero elements in X.

Column subscripts, returned as a vector of int32 values. Together, row and col specify the X(row,col) subscripts corresponding to the nonzero elements in X.

If X is a multidimensional array with N > 2, then col is a linear index over the N-1 trailing dimensions of X. This preserves the relation X(row(i),col(i)) == v(i).

Nonzero elements of X, returned as a vector.

Extended Capabilities

expand all

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 R2026a

See Also

Topics