Documentation

coder.ref

Pass argument by reference

Syntax

coder.ref(arg)

Description

example

coder.ref(arg) passes arg by reference to an external C/C++ function that you call by using coder.ceval. Use coder.ref inside a coder.ceval call only. The C/C++ function can read from or write to the variable passed by reference. Use a separate coder.ref construct for each argument that you pass by reference to the function.

Examples

Pass Scalar Variable by Reference

Pass a variable by reference to a C function that adds 1 to the variable.

Suppose that you have a C function addone.

void addone(double* p) {
  *p = *p + 1;
}

The C function prototype defines the input as a pointer because it is passed by reference.

Pass a variable by reference to addone.

...
u = 42;
coder.ceval('addone', coder.ref(u));
...

Pass Multiple Arguments by Reference

...
u = 1;
v = 2; 
y = coder.ceval('my_fcn', coder.ref(u), coder.ref(v));
...

Pass Class Property by Reference

...
x = myClass;
x.prop = 1;
coder.ceval('foo', coder.ref(x.prop));
...

Pass a Structure by Reference

To indicate that the structure type is defined in a C header file, use coder.cstructname.

Suppose that you have the C function incr_struct.

void incr_struct(struct MyStruct *my_struct)
{
  my_struct->f1 =  my_struct->f1 + 1;
  my_struct->f2 =  my_struct->f2 + 1;
}

Suppose that a C header file, MyStruct.h, defines a structure type named MyStruct.

...
typedef struct MyStruct
{
    double f1;
    double f2;
    
} MyStruct;

void incr_struct(struct MyStruct *my_struct);

...

In your MATLAB® function, pass a structure by reference to incr_struct. To indicate that the structure type for s has the name MyStruct that is defined in a C header file MyStruct.h, use coder.cstructname.

...
s = struct('f1', 1, 'f2', 2);
coder.cstructname(s, 'MyStruct', 'extern', 'HeaderFile', 'MyStruct.h');
coder.ceval('incr_struct', coder.ref(s));
...

Pass Structure Field by Reference

...
s = struct('s1', struct('a', [0 1]));
coder.ceval('foo', coder.ref(s.s1.a));
...

Input Arguments

collapse all

Argument to pass by reference to an external C/C++ function. The argument cannot be a class, a System object™, a cell array, or an index into a cell array.

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

Limitations

  • You cannot pass these data types by reference:

    • Class or System object

    • Cell array or index into a cell array

  • If a property has a get method, a set method, or validators, or is a System object property with certain attributes, then you cannot pass the property by reference to an external function. See Passing By Reference Not Supported for Some Properties.

Tips

  • When you pass a structure by reference to an external C/C++ function, use coder.cstructname to provide the name of a C structure type that is defined in a C header file.

  • In MATLAB, coder.ref results in an error. To parameterize your MATLAB code so that it can run in MATLAB and in generated code, use coder.target.

  • You can use coder.opaque to declare variables that you pass to and from an external C/C++ function.

Introduced in R2011a

Was this topic helpful?