Daylight v4.9
Release Date: 1 February 2008

Name

dt_match - match a pattern against a target

Generic Prototype

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

include 'dt_f_smarts.inc'

integer*4 dt_f_match(pat, target, limit)

integer*4 pat
integer*4 target
integer*4 limit

Description

Matches 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).

- 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.

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 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_umatch(3) dt_vmatch(3) dt_xmatch(3)

Bugs

dt_match(3) is inconsistent in that it returns NULL_OB when no match is found. It should return an empty pathset object.