dt_umatch

Daylight v4.9
Release Date: 1 February 2008

Name

dt_umatch - match a pattern against an object

Generic Prototype

dt_umatch(dt_Handle, dt_Handle, dt_Boolean) => dt_Handle

C Prototype

#include "dt_smarts.h"

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

FORTRAN Prototype

include 'dt_f_smarts.inc'

integer*4 dt_f_umatch(pat, target, exists)

integer*4 pat
integer*4 target
logical exists

Description

Matches the pattern 'pat' against the molecule or reaction 'target' and returns a pathset indicating the results. Each path in the pathset contains a unique set of atoms relative to all other paths in the pathset.

In effect, dt_umatch(3) performs a dt_match(3) and then removes any redundant paths. Redundant paths are not necessarily equivalent, but do contain the same set of atoms. For example, paths which contain cycles may have different bonding to the same sets of atoms, and will be considered redundant.

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. Note that if 'exists' is TRUE, dt_umatch(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.)

Return Value