dt_xmatch

Daylight v4.9
Release Date: 1 February 2008

Name

dt_xmatch - match a pattern against an object

Generic Prototype

dt_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 Prototype

include 'dt_f_smarts.inc'

integer*4 dt_f_xmatch(pat, target, limit)

integer*4 pat
integer*4 target
logical limit

Description

Performs 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 Value