The unchecked module "mfind_" of the Mastrave modelling library

Copyright and license notice of the function mfind_

Copyright © 2005,2006,2007,2009,2010 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

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.