Release Date: 1 February 2008
Namedt_xmatch - match a pattern against an object
Generic Prototypedt_xmatch(dt_Handle, dt_Handle, dt_Integer) => dt_Handle
C Prototype#include "dt_smarts.h"
dt_Handle dt_xmatch(dt_Handle pat, dt_Handle target, dt_Integer limit)
FORTRAN Prototypeinclude 'dt_f_smarts.inc'
integer*4 dt_f_xmatch(pat, target, limit)
DescriptionPerforms an exclusive match of the pattern 'pat' against the molecule or reaction 'target' and returns a pathset indicating the results. The paths in the result are completely non-overlapping; each atom appears in exactly one path. This is a more restrictive search than dt_umatch(3) and is typically much faster.
The 'target' must be in mod-off state. If the molecule or reaction
The paramater 'limit' indicates when to stop the search. If 'limit' is 0, an exhaustive search takes place and the returned pathset object will contain all non-overlapping matches in the target. If 'limit' is a positive integer, the match stops as soon as that number of matches is found. Note that if 'limit' is 1, dt_xmatch(3) is equivalent to dt_match(3).
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.)
NOTE: this function is not deterministic; it will give different answers under different circumstances. For example, matching the pattern 'CC' against the molecule 'CCCC' will give two pathsets. Matching the same pattern against 'C(CC)C' gives one pathset. In the first case, Carbons #1 and #2 are matched first, leaving #3 and #4 to match. In the second case, Carbons #2 and #3 are bound first, leaving #1 and #4, which don't match further.
Return ValueReturns a pathset or the NULL_OB if an error is detected.
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_match(3) dt_umatch(3) dt_vmatch(3)