Daylight v4.9
Release Date: 1 February 2008


dt_vmatch - match a pattern against an object

Generic Prototype

dt_vmatch(dt_Handle, dt_Handle, dt_Boolean) => dt_Handle

C Prototype

#include "dt_smarts.h"

dt_Handle dt_vmatch(dt_Handle pat, dt_Handle target, dt_Boolean exists)

FORTRAN Prototype

include ''

integer*4 dt_f_vmatch(pat, target, exists)

integer*4 pat
integer*4 target
logical exists


Matches the pattern 'pat' against the molecule or reaction 'target' and returns a pathset indicating the results. Each path in the pathset contains a single atom, the one that matches the 'head' atom of the SMARTS from which the pattern is derived. Further, no two paths in the pathset will contain the same atom.

Note that 'pat' may not be a reaction pattern. It is illegal to perform a vector match using a reaction pattern (either explicitly or in recursive SMARTS).

If 'target' is a molecule or reaction, it must be in mod-off state.

The boolean parameter 'exists' indicates whether an exhaustive search or a first-only search are to be performed. If 'exists' is FALSE, an exhaustive search takes place and the returned pathset object will contain all the places in the molecule where pattern matches. If 'exists' is TRUE, the match stops as soon as the first match is found and the pathset will contain just the first path that the exhaustive search would find.

If the original SMARTS string for the pattern contains vector names, 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).

*If a vector binding is bound to a pathset, its name matches any atom that is a member of the pathset. (Note that the bound pathset's base molecule must be the same as that of pattern, otherwise no match is possible.)

Return Value

Returns a pathset or the NULL_OB if an error is detected. Each path in the pathset contains a single atom.

Related Topics

dt_alloc_pathset(3) dt_alloc_vbind(3) dt_getval(3) dt_name(3) dt_setval(3) dt_smartin(3) dt_smarts_opt(3) dt_match(3) dt_umatch(3)