Matlab has a variety of internal helper functions which are used by the main (documented) functions. Some of these helper functions are undocumented and unsupported, but may be helpful in their own right – not just as internal support functions.

In this post I want to present Matlab’s built-in * ismembc* helper function. This function is used within the stock Matlab

*and*

**ismember****functions for fast processing of the core**

*setxor**functionality in “regular” cases: arrays of sorted, non-sparse, non-NaN data in which we’re only interested in the logical membership information (not the index locations of the found members). In such cases,*

**ismember***can be used directly, saving*

**ismembc***‘s sanity-checks overhead.*

**ismember***uses the same interface (two inputs, single logical output) as*

**ismembc***and can be a drop-in replacement for*

**ismember***for these “regular” cases.*

**ismember**The performance improvement may be significant: In a recent post, MathWorks’ Loren Shure presented different approaches for fast data retrieval, highlighting the * ismember* function. Let’s compare:

>> % Initial setup >> n=2e6; a=ceil(n*rand(n,1)); b=ceil(n*rand(n,1)); >> % Runseveral times, to rule-out JIT compilation overheads >> tic;ismember(a,b);toc; Elapsed time is 2.882907 seconds. >> tic;ismember(a,b);toc; Elapsed time is 2.818318 seconds. >> tic;ismember(a,b);toc; Elapsed time is 3.005967 seconds. >> % Now useismember: >> tic;ismembc(a,b);toc; Elapsed time is 0.162108 seconds. >> tic;ismembc(a,b);toc; Elapsed time is 0.204108 seconds. >> tic;ismembc(a,b);toc; Elapsed time is 0.156963 seconds.ismembc

* ismembc* is actually a MEX file (%matlabroot%\toolbox\matlab\ops\ismembc.mexw32). Its source code is included in the same folder (%matlabroot%\toolbox\matlab\ops\ismembc.cpp) and is actually very readable. From the source code comments we learn that the comment in

*about*

**setxor***usage is misleading: that comment stated that the inputs must be real, but the source-code indicates that imaginary numbers are also accepted and that only the real-part should be sorted.*

**ismembc*** ismembc* should not be used carelessly: as noted, its inputs must be sorted non-sparse non-NaN values. In the general case we should either ensure this programmatically (as done in

*) or use*

**setxor***, which handles this for us.*

**ismember**The nice thing about * ismembc* is that its source code (ismembc.cpp) is included, so even if future Matlab releases stop using this function, you can always mex-compile the source code and use it.

Readers interested in * ismembc* might also be interested in its sibling help function,

*, which is also a mex file located (with source-code) in the same folder as*

**ismembc2***. Whereas*

**ismembc***returns an array of logical values,*

**ismembc***returns the index locations of the found members.*

**ismembc2**Related posts:

- sprintfc – undocumented helper function The built-in sprintfc function can be used to quickly generate a cell-array of formatted strings. ...
- Undocumented feature() function Matlab's undocumented feature function enables access to some internal experimental features...
- tic / toc – undocumented option Matlab's built-in tic/toc functions have an undocumented option enabling multiple nested clockings...
- Function call timeline profiling A new utility enables to interactively explore Matlab function call timeline profiling. ...
- Function definition meta-info There are multiple ways to retrieve meta-info about functions in Matlab. ...
- cellfun – undocumented performance boost Matlab's built-in cellfun function has an undocumented option to significantly improve performance in some cases....

Pingback: Datenum performance | Undocumented Matlab

interestingly, it appears that the variable “a” does not have to be sorted for using ismembc(), but the algorithm runs much more quickly if it is.

For ismembc(), the first input needs NOT to be sorted. Follows the heuristic that tests the assertion(terminate execution with CTRL+C):

The same holds true for ismembc2(), i.e. first input needs not to be sorted, IFF we are getting the positions under the ‘legacy’ flag:

The pos output:

To reproduce the same pos as with ismember() in >= R2012b, you do NOT need sorted A, but should have unique and sorted B.

Pingback: Undocumented Matlab at Nordt Blog

It doesn’t work if it’s not sorted. The function stops as soon as it meets a higher value. The given example is bad because the function stops most of the time too early (but ismembc is indeed faster).

@Vivien – the preconditions required by

were indeed mentioned in the article:ismembcshould not be used carelessly: as noted, its inputs must be sorted non-sparse non-NaN values. In the general case we should either ensure this programmatically (as done inismembc) or usesetxor, which handles this for us.ismemberPingback: sprintfc – undocumented helper function | Undocumented Matlab

There is almost no difference in the new 2013b version of Matlab:

@Ramy – I am not sure I understand – you ran the same

command several times, of course it would take a similar amount of time. If you run the same thing withismemberyou’ll see that it’s much faster. On the other hand, remember thatismembcmust have sorted inputs, and your inputs are currently random…ismembcIf I’ve understood (and tested) it correctly, Inf-padding at the end of any of the 2 input vectors should not be a problem (sometimes vectors are 0 or NaN padded to preserve certain dimensionality)…

Otherwise, a very nice post, it really helped me a lot!