Release Date: 1 February 2008
Namedt_match - match a pattern against a target
Generic Prototypedt_match(dt_Handle, dt_Handle, dt_Integer) => dt_Handle
C Prototype#include "dt_smarts.h"
dt_Handle dt_match(dt_Handle pat, dt_Handle target, dt_Integer limit)
FORTRAN Prototypeinclude 'dt_f_smarts.inc'
integer*4 dt_f_match(pat, target, limit)
DescriptionMatches the pattern 'pat' against 'target' and returns a pathset indicating the places where the pattern matched the target.
If 'target' is a molecule object, 'pat' must be a pattern object (from dt_smartin(3)). If 'target' is a reaction object, 'pat' can be either a molecule or reaction pattern.
If 'target' is a molecule or reaction, it must be in mod-off state.
The integer parameter 'limit' indicates whether an exhaustive search or a limited search is to be performed. If 'limit' is zero, an exhaustive search takes place and the returned pathset object will contain all the places in 'target' where 'pat' matches. A non-zero value for 'limit' causes a non-exhaustive search to take place; the behavior in this case depends on the type of 'target', as described below.
If 'limit' is non-zero, then the search stops as soon as the first match is found, and the pathset will contain just the first path that an exhaustive search would find.
If the original SMARTS string for the pattern contains vector names (see dt_vbind(3)), the result of the match will depend upon the current values bound to those names as follows:
- If a vector binding is bound to a pattern, its name matches an atom if the pattern bound to it matches that atom using dt_match(3).
Return ValueReturns a pathset or the NULL_OB if an error is detected.
Corresponding objects (atoms and bonds) of the paths in the pathset are guaranteed to have matched the same underlying construct in the pattern in the same order. That is, the atoms and bonds in any paths returned from dt_match(3) will appear in the same order as the expressions in the pattern to which they match.
Related Topicsdt_alloc_pathset(3) dt_alloc_vbind(3) dt_getval(3) dt_name(3) dt_setval(3) dt_smartin(3) dt_smarts_opt(3) dt_umatch(3) dt_vmatch(3) dt_xmatch(3)
Bugsdt_match(3) is inconsistent in that it returns NULL_OB when no match is found. It should return an empty pathset object.