Semantic array programming: abstract, portable and scalable data-transformation modelling for the community of computational scientists.
The 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
% 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.