The module "shortmatch" of the Mastrave modelling library

Copyright and license notice of the function shortmatch

Copyright © 2007,2008,2009,2010,2011,2012 Daniele de Rigo

The file shortmatch.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

[answer, position]  = shortmatch( strings                 ,
                                  match                   ,
                                  at_most = inf           ,
                                  mode    = 'match_order' )

Description

Utility for selecting with a simplified pattern matching a subset of strings among those passed as strings argument. The match argument is a string (or a cell-array of strings) whose characters must be present in each matching string of strings in the same order (from left to right), although they are not required to occupy adjacent positions in each strings element. This pattern matching convention is useful for example to shorten the way long names contained in strings are univocally identifiable.

If passed, the argument at_most limits the number of returned elements of strings . The optional mode argument can modify the way in which pattern matching is performed, and the order in which the matching results are returned.

Input arguments

 strings             ::cellstring|cellstring-2::
                     Cell-array of strings from which to extract those
                     matching the  match  query.
                     A key-value associative array can be passed instead
                     of a single cell-array of strings.  To do so, a couple
                     of cell-arrays have to be passed packed into a
                     two-element cell-array.  The first array is of strings
                     and is expected to provide the strings to be searched
                     for (the "keys"), while the second array is expected
                     to provide the corresponding objects to be associated
                     and returned (the "values"). "Keys" and "values" must
                     have the same number of elements.                      

 match               ::cellstring::
                     Query string(s).  It must be a string of a cell-array
                     of strings.

 at_most             ::scalar_index::
                     Maximum number of matching elements to find in
                      strings .  (Default: inf ). 

 mode                ::cellstring::
                     Criterion for extracting from  strings   at_most 
                     matching elements.
                     (Default: { 'len_order' 'first' } ).
                     Valid modes are:

                          mode      │      meaning
                     ───────────────┼─────────────────────────────────
                      'first'       │ Returns the first  at_most 
                                    │ matching elements of  strings 
                                    │ against  match .
                     ───────────────┼─────────────────────────────────
                      'last'        │ Returns the last  at_most 
                                    │ matching elements of  strings 
                                    │ against  match .
                     ───────────────┼─────────────────────────────────
                      'match_order' │ Sorts the matching elements of
                                    │  strings  against  match  in
                                    │ lexicographical order, with
                                    │ respect to the position of the
                                    │ matching characters inside each
                                    │ string of  strings .
                     ───────────────┼─────────────────────────────────
                      'len_order'   │ Sorts the matching elements of
                                    │  strings  against  match  from
                                    │ the shorter match to the longer
                                    │ one.  If two matches have the
                                    │ same length, they are ordered 
                                    │ with respect to the position of
                                    │ the matching characters inside
                                    │ each string of  strings .
                     ───────────────┼─────────────────────────────────
                      'regexp'      │ Considers  match  as a regular 
                                    │ expression following the same
                                    │ convention of @regexp   .
                                    │ This is different from the
                                    │ default behavior in which each
                                    │ character of  match  matches
                                    │ exactly one character of an 
                                    │ element of  strings , and the
                                    │ next  match  character is only
                                    │ required to match a subsequent
                                    │ (even if not adjacent) char of
                                    │ the same  string  element.
                     ───────────────┼─────────────────────────────────
                      'literal'     │ Considers even standard regexp
                                    │ operators (e.g. * ? . )
                                    │ as literal characters (e.g. 
                                    │ respectively \* \? \.) in case
                                    │ the mode 'regexp' is enabled.
                     ───────────────┼─────────────────────────────────
                      'token'       │ Same as enabling both 'regexp'
                                    │ and 'literal' modes.  It is the
                                    │ preferred way to express the
                                    │ request to match the  strings 
                                    │ elements containing  match  as
                                    │ their substring. 
                     ───────────────┼─────────────────────────────────
                      'exact'       │ Imposes to exclusively match
                                    │ the  strings  elements whose
                                    │ value is exactly  match .
                       

Example of usage

   % Basic usage:
   shortmatch( iskeyword , 'r' )
   shortmatch( iskeyword , 'cs' )
   shortmatch( iskeyword , 'fn' )
   shortmatch( iskeyword , 'et' )

   % Multiple matches:
   shortmatch( iskeyword , { 'cs' 'fn' 'et' } )


   % Limiting the number of results with  at_most  argument:
   shortmatch( iskeyword , 'r' , 2 )
   shortmatch( iskeyword , 'r' , 1 )


   % Special modes: ordering modes
   shortmatch( iskeyword , 'r' )
   shortmatch( iskeyword , 'r' , inf , { 'match_order' 'first' } )
   shortmatch( iskeyword , 'r' , inf , { 'match_order' 'last'  } )
   shortmatch( iskeyword , 'r' , inf , 'first' )
   shortmatch( iskeyword , 'r' , inf , 'last' )

   shortmatch( iskeyword , 'ie' , inf , 'match_order' )
   shortmatch( iskeyword , 'ie' , inf , 'len_order'   )


   % Special modes: modifying the pattern matching engine
   a = { 'foo' '/fo//o' '/*/' '/* foo */' '/* comment */' 'end/*/' '/*/begin' }
   shortmatch( a , '/*/' )
   shortmatch( a , '/*/' , inf , 'token'                )
   shortmatch( a , '/*/' , inf , 'regexp'               )
   shortmatch( a , '/*/' , inf , { 'regexp' 'literal' } ) % same as 'token'
   shortmatch( a , '/*/' , inf , 'literal'              )
   shortmatch( a , '/*/' , inf , 'exact'                )

   % Obtaining the position of matches
   [val, pos] = shortmatch( a , '/*/' , inf , 'token'   )
   [val, pos] = shortmatch( a , '/*/' , inf , 'literal' )
   [val, pos] = shortmatch( a , '/*/' , inf , 'exact'   )


   % Associative array
   assoc = { { 'foo', 'bar', 'baz' } { 'one', 2, {'baz is ' pi } } };
   [ answer, position ] = shortmatch( assoc, 'fo' )
   [ answer, position ] = shortmatch( assoc, 'ba' )
   [ answer, position ] = shortmatch( assoc, { 'fo' 'ba' } )

See also:
   mfind



Keywords:
   cell-array, string, indices



Version: 0.5.1

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.