## The module "shortmatch" of the Mastrave modelling library

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.

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