## The unchecked module "mfind_" of the Mastrave modelling library

Daniele de Rigo

The file mfind_.m is part of Mastrave.

Mastrave is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Mastrave is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Mastrave. If not, see http://www.gnu.org/licenses/.

#### Function declaration

[ match_id , val_id , ... ] = mfind_( matches           ,
values            ,
at_most = inf     ,
mode    = 'first' )



#### Description

Warning: mfind_ should not be used in end-user code because it deliberately skips input and output arguments checks and other pre- and post-condition testing. End-user code should use instead the mfind function (without the ending underscore).

Find indices and values of those elements of values that are equal to any element of matches . This function extends the find(.) function. If matches is a scalar variable m , find(.) and mfind_(.) behave equivalently using the following notation:
id = find( m == values )
id = mfind_( m , values ) If m is not scalar, only mfind_(.) notation is able to scale up to the vectorial case.

If more than one output are assigned, the behavior is analogous to that of the find(.) function, with the relevant exception that the output arguments equivalent to those of find(.) are always preceded by match_id which is a vector containing the position of each element of matches matching with (equal to) at least an element of values .

If matches is a scalar variable m , with find(.) it is possible to find non matching elements of values by using the notation:
nonmatching_id = find( m ~= values ) which is equivalent to:
nonmatching_id = find( m ~= values , inf , 'first' ) The equivalent notation using mfind_(.) is:
nonmatching_id = mfind_( m , values , inf , 'nfirst' ) Again, if m is not scalar only mfind_(.) notation is able to scale up to the vectorial case. When passing 'nfirst' or 'nlast' criteria as mode , the i-th element of val_id is the position of the values element which is closer to the i-th element of match_id (i.e. the i-th non-matching element of matches ).

#### Input arguments


matches                 ::numstring,vector::
Array  of numbers or of characters whose
elements are to be matched in  values .

values                  ::numstring::
Matrix of numbers or of characters in
which to find elements matching any of
those contained in  matches  .

at_most                 ::scalar_numel::
Maximum number of matching elements to
find in  values .  (Default: inf ).

mode                    ::string::
Criterion for extracting from  values
at_most  matching elements.
(Default: 'first').  Valid modes are:

mode    │      meaning
─────────────┼─────────────────────────────
'first'     │ Returns the first  at_most
│ matching elements of
│  matches  against  values .
─────────────┼─────────────────────────────
'last'      │ Returns the last  at_most
│ matching elements of
│  matches  against  values .
─────────────┼─────────────────────────────
'nfirst'    │ Returns the first  at_most
│ non-matching elements of
│  matches  against  values .
─────────────┼─────────────────────────────
'nlast'     │ Returns the last  at_most
│ non-matching elements of
│  matches  against  values .

Implementation limits:
values  and  matches  cannot have more unique values than the maximum
integer (intmax, usually 2^31 ─ 1).



#### Example of usage


% Performance against find(.)
n = 300; N = n*n;
A = reshape( 1:N , n , n );
p = primes( N );

tic; [ which_p , r1 , c1 ] = mfind_( p , A ); toc

tic;
r2 = zeros(numel(p),1);  c2 = r2;
for i=1:numel(p)
[ r2(i), c2(i) ] = find( p(i) == A );
end
toc

all( r1 == r2 )
all( c1 == c2 )
hist( c1 , n )

% Dealing with strings
t                              =  'mfind_( matches, values )'  ;
[which_punct, indexes]         =   mfind_( '(,)' , t )
[which_punct, rows, cols]      =   mfind_( '(,)' , t )
[which_punct, rows, cols, val] =   mfind_( '(,)' , t )

t( t == ' ' )                  = [];  % erase spaces
[which_punct, rows, cols, val] =   mfind_( '(,)' , t )
t( cols )                      = [];  % erase separators
len                            = diff([0 cols])-1; % token length
tokens                         = mat2cell( t , 1 , len )

% Finding matches inside a matrix of values
V               = zeros( 5 , 4 );
nV              = numel( V );
rnd             = ceil( 99 * rand( 1 , nV ) ) / 10;
V(:)            = rnd( ceil( rand( 1 , nV ) * numel(rnd) ) )
m               = rnd( ceil( rand( 1 , 8  ) * numel(rnd) ) )
[ mpos , Vpos ] = mfind_( m , V )
[ mpos , Vpos ] = mfind_( m , V , 3 )
all( m( mpos(:).' )  == V( Vpos(:)' ) )
[ mpos , r , c , v ] = mfind_( m , V , 3, 'first')
all( V( Vpos ) == v )
all( V( Vpos ) == V( sub2ind( size(V) , r , c ) ) )
[ mpos , r , c , v ] = mfind_( m , V , 3, 'last')

% Finding non-matching  matches
[ mpos , Vpos ]      = mfind_( m , V , inf, 'nfirst')
[ mpos , r , c , v ] = mfind_( m , V , inf, 'nfirst')
all( V( Vpos ) == v )
all( V( Vpos ) == V( sub2ind( size(V) , r , c ) ) )
% Check Vpos against the loop version of the algorithm
Vpos2           = []
for i=1:numel(m)
[ dist , pos ]    = min( abs( m(i) - V(:) ) );
if dist ~= 0
Vpos2( end+1 ) = pos;
end
end
all( Vpos == Vpos2 )

[ mpos , Vpos ]      = mfind_( m , V , 3, 'nlast')
[ mpos , r , c , v ] = mfind_( m , V , 3, 'nlast')
all( V( Vpos ) == v )
all( V( Vpos ) == V( sub2ind( size(V) , r , c ) ) )


Version: 0.7.2

#### Support

The Mastrave modelling library is committed to provide reusable and general - but also robust and scalable - modules for research modellers dealing with computational science.  You can help the Mastrave project by providing feedbacks on unexpected behaviours of this module.  Despite all efforts, all of us - either developers or users - (should) know that errors are unavoidable.  However, the free software paradigm successfully highlights that scientific knowledge freedom also implies an impressive opportunity for collectively evolve the tools and ideas upon which our daily work is based.  Reporting a problem that you found using Mastrave may help the developer team to find a possible bug.  Please, be aware that Mastrave is entirely based on voluntary efforts: in order for your help to be as effective as possible, please read carefully the section on reporting problems.  Thank you for your collaboration.

Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016 Daniele de Rigo