SHAREDCHILD creates a shared data copy of contiguous subset

SHAREDCHILD creates a shared data copy of a contiguous subsection of an existing variable

SHAREDCHILD creates a shared data copy of a contiguous subarray of an existing variable. The motivation for creating this mex routine is to have the ability to effectively create a reference to a contiguous sub-section of a variable without needing to create a deep data copy. For very large variables, this can have obvious benefits instead of creating a deep data copy that would be required at the m-code level.
EXAMPLES of using real & imag parts:

>> x = reshape(1:24,2,3,4) - reshape(1:24,2,3,4)*1i % Arbitrary 3D complex
x(:,:,1) =
1.0000 - 1.0000i 3.0000 - 3.0000i 5.0000 - 5.0000i
2.0000 - 2.0000i 4.0000 - 4.0000i 6.0000 - 6.0000i
x(:,:,2) =
7.0000 - 7.0000i 9.0000 - 9.0000i 11.0000 -11.0000i
8.0000 - 8.0000i 10.0000 -10.0000i 12.0000 -12.0000i
x(:,:,3) =
13.0000 -13.0000i 15.0000 -15.0000i 17.0000 -17.0000i
14.0000 -14.0000i 16.0000 -16.0000i 18.0000 -18.0000i
x(:,:,4) =
19.0000 -19.0000i 21.0000 -21.0000i 23.0000 -23.0000i
20.0000 -20.0000i 22.0000 -22.0000i 24.0000 -24.0000i

>> s = sharedchild(x,[1 2 1],[2 3 1]) % Rectangular child
s =
3.0000 - 3.0000i 5.0000 - 5.0000i
4.0000 - 4.0000i 6.0000 - 6.0000i

>> t = sharedchild(s,'ir') % Swapped real & imag version of s
t =
-3.0000 + 3.0000i -5.0000 + 5.0000i
-4.0000 + 4.0000i -6.0000 + 6.0000i

>> c = sharedchild(x,[2 1 3],[2 2 4],'i') % Not nD rectangle, so row
c =
-14 -15 -16 -17 -18 -19 -20 -21 -22

>> r = sharedchild(c,'rr').' % Real part of c used for real & imag parts of r
r =
-14.0000 -14.0000i
-15.0000 -15.0000i
-16.0000 -16.0000i
-17.0000 -17.0000i
-18.0000 -18.0000i
-19.0000 -19.0000i
-20.0000 -20.0000i
-21.0000 -21.0000i
-22.0000 -22.0000i

For the R2018a and later versions, note that MATLAB now uses interleaved real/imag data instead of separate real/imag data. This means you can no longer mix & match real & imag parts to create the child subarrays as shown above. What you *can* do in R2018a+ is reinterpret real variables as complex variables (with 1/2 the number of elements as the source), and you can reinterpret complex variables as real variables (with 2x the number of elements as the source). The sharedchild_test function has added tests for this functionality, as well as tests for the real2complex and complex2real mex routines (see next paragraph).

Also added for the R2018a version are the standalone mex routines real2complex and complex2real. These are simple bare-bones mex routines that reinterpret real variables as complex (with first dimension halved) and complex variables as real (with first dimension doubled) respectively. They always operate on the whole variables, always return shared data copies, and do not require any persistent variables being held inside the mex routines. They can only be used with full variables (the sparse storage format is incompatible with this). They don't really provide any additional functionality that is not already present in sharedchild. Their main purpose is to provide mex programmers example code for how to do these tasks in the simplest way possible without all of the extra baggage contained in sharedchild.

*** DISCLAIMER ***

This mex routine uses undocumented API functions and hacks into the mxArray itself in order to create the child shared data copy. I have tried to code it in such a way that the routine will not crash MATLAB, but caveat emptor. In particular, the child variable that is returned from this mex routine is actually an invalid mxArray variable. The data pointers of the child are invalid since they point to the interior of an allocated memory block. This mex routine attempts to keep MATLAB from ever trying to free the memory behind these data pointers directly. All that being said, the rules for how MATLAB uses data pointers are not published, so I cannot guarantee that this mex routine will not crash MATLAB in some circumstances. Also, the hacks that this mex routine uses to create and manage these invalid child variables may not play nice with other mex routines using similar hacks. Updated and tested for various 32-bit and 64-bit MATLAB PCWIN versions R2009a - R2019b. Note that isempty( ) will not work in R2015b+ for emptied variables for some unknown reason (this was the primary cause of the testing failures in version 1.0). And numel( ) will crash MATLAB for emptied variables in R2015b (also for some unknown reason). It is suggested to manually clear the child subarray variables or 'UNSHARE' them rather than using the 'EMPTY' option if at all possible.

If you encounter a crash, please contact the author.