mxCreateDoubleMatrix - what value is used to initialize the array ? Documentation incomplete

The doc mxCreateDoubleMatrix (C) says:

For applications built with the mex -R2018a command, the function initializes each data element to 0.

For all other mex release-specific build options, the function sets each element in the pr array. If ComplexFlag is mxCOMPLEX, then the function sets the pi array to 0.

The documentation is incomplete to my understanding.

What exactly is written to each element in the pr array when I compile without -R2018a (which is what I use by default) ?

Does the answer differ between mxREAL and mxCOMPLEX?

[Germain Pham]

I found an answer here : https://math.jhu.edu/~shiffman/370/help/techdoc/apiref/mxcreatedoublematrix.html

but the official documentation does not display the same content.

Going to report this issue to the support so that official documentation is fixed.

Answer 1

[James Tursa]

I agree that the official documentation could maybe be written better regarding how elements are initialized. I.e., simply adding "to 0" to the phrase you mention would clear things up:

For all other mex release-specific build options, the function sets each element in the pr array to 0.

Almost all of the mxCreateEtc( ) functions initialize the elements to 0's, regardless of data type (double, single, int32, char, logical, etc.), complexity (mxREAL or mxCOMPLEX), and compile flags (-R2018a or not).

The only exceptions I am aware of are the mxCreateUninitNumericArray( ) and mxCreateUninitNumericMatrix( ) functions, which in theory can run faster since they are not initializing the data. In practice, this might not always be true since the mxCreateEtc( ) functions might grab data memory from a memory block that has already been previously set to 0's, but that is a side issue.

Keep in mind, that if you use complex variables in R2018a and later but you compile without the -R2018a flag, you will get copy-in/copy-out behavior. All complex mxArray variables in R2018a and later are stored as interleaved in the background, regardless of the compile flag. So if you use complex variables in a mex routine but don't use the -R2018a compile flag, this will force MATLAB to deep copy to/from interleaved format whenever the variables are passed into and out of the mex routine. For large variables, this can be a significant performance hit. My advice is to always write mex code for complex variables in interleaved format to avoid this hit (using the -R2018a compile flag). And if you are porting older code, I would take the time to rewrite it as interleaved.