Package org.openscience.cdk.isomorphism.matchers

Class Expr

  • public final class Expr
extends Object
    A expression stores a predicate tree for checking properties of atoms and bonds. 
     Expr expr = new Expr(ELEMENT, 6);
 if (expr.matches(atom)) {
   // expression matches if atom is a carbon!
 }
    An expression is composed of an Expr.Type, an optional 'value', and optionally one or more 'sub-expressions'. Each expr can either be a leaf or an intermediate (logical) node. The simplest expression trees contain a single leaf node: 
     new Expr(IS_AROMATIC); // matches any aromatic atom
 new Expr(ELEMENT, 6);  // matches any carbon atom (atomic num=6)
 new Expr(VALENCE, 4);  // matches an atom with valence 4
 new Expr(DEGREE, 1);   // matches a terminal atom, e.g. -OH, =O
 new Expr(IS_IN_RING);  // matches any atom marked as in a ring
 new Expr(IS_HETERO);   // matches anything other than carbon or nitrogen
 new Expr(TRUE);        // any atom
    Logical internal nodes combine one or two sub-expressions with conjunction (and), disjunction (or), and negation (not).
    Consider the following expression tree, is matches fluorine, chlorine, or bromine. 
         OR
    /  \
   F   OR
      /  \
     Cl   Br
    We can construct this tree as follows: 
     Expr expr = new Expr(ELEMENT, 9) // F
                  .or(new Expr(ELEMENT, 17)) // Cl
                  .or(new Expr(ELEMENT, 35))  // Br
    A more verbose construction could also be used: 
     Expr leafF  = new Expr(ELEMENT, 9); // F
 Expr leafCl = new Expr(ELEMENT, 17); // Cl
 Expr leafBr = new Expr(ELEMENT, 35);  // Br
 Expr node4  = new Expr(OR, leaf2, leaf3);
 Expr node5  = new Expr(OR, leaf1, node4);
    Expressions can be used to match bonds. Note some expressions apply to either atoms or bonds. 
     new Expr(TRUE);               // any bond
 new Expr(IS_IN_RING);         // any ring bond
 new Expr(ALIPHATIC_ORDER, 2); // double bond
    See the documentation for Expr.Types for a detail explanation of each type.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Expr.Type
      Types of expression, for use in the Expr tree object.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int UNKNOWN_STEREO
      Sentinel value for indicating the stereochemistry configuration is not yet known.

    • Constructor Summary

      Constructors 
      Constructor Description
      Expr()
      Creates an atom expression that will always match (Expr.Type.TRUE).
      Expr​(Expr expr)
      Copy-constructor, creates a shallow copy of the provided expression.
      Expr​(Expr.Type op)
      Creates an atom expression for the specified primitive.
      Expr​(Expr.Type op, int val)
      Creates an atom expression for the specified primitive and 'value'.
      Expr​(Expr.Type op, IAtomContainer mol)
      Creates a recursive atom expression.
      Expr​(Expr.Type op, Expr left, Expr right)
      Creates a logical atom expression for the specified.

    • Field Detail

      • UNKNOWN_STEREO

        public static final int UNKNOWN_STEREO
        Sentinel value for indicating the stereochemistry configuration is not yet known. Since stereochemistry depends on the ordering of neighbors we can't check this until those neighbors are matched.
        See Also:
        Constant Field Values

    • Constructor Detail

      • Expr

        public Expr()
        Creates an atom expression that will always match (Expr.Type.TRUE).

      • Expr

        public Expr​(Expr.Type op)
        Creates an atom expression for the specified primitive.

      • Expr

        public Expr​(Expr.Type op,
            int val)
        Creates an atom expression for the specified primitive and 'value'.

      • Expr

        public Expr​(Expr.Type op,
            Expr left,
            Expr right)
        Creates a logical atom expression for the specified.

      • Expr

        public Expr​(Expr expr)
        Copy-constructor, creates a shallow copy of the provided expression.
        Parameters:
        expr - the expre

    • Method Detail

      • matches

        public boolean matches​(IBond bond,
                       int stereo)

      • matches

        public boolean matches​(IBond bond)

      • matches

        public boolean matches​(IAtom atom)
        Test whether this expression matches an atom instance.
        Parameters:
        atom - an atom (nullable)
        Returns:
        the atom matches

      • matches

        public boolean matches​(IAtom atom,
                       int stereo)

      • and

        public Expr and​(Expr expr)
        Utility, combine this expression with another, using conjunction. The expression will only match if both conditions are met.
        Parameters:
        expr - the other expression
        Returns:
        self for chaining

      • or

        public Expr or​(Expr expr)
        Utility, combine this expression with another, using disjunction. The expression will match if either conditions is met.
        Parameters:
        expr - the other expression
        Returns:
        self for chaining

      • negate

        public Expr negate()
        Negate the expression, the expression will not return true only if the condition is not met. Some expressions have explicit types that are more efficient to use, for example: IS_IN_RING => NOT(IS_IN_RING) => IS_IN_CHAIN. This negation method will use the more efficient type where possible. 
        
 Expr e = new Expr(ELEMENT, 8); // SMARTS: [#8]
 e.negate(); // SMARTS: [!#8]
        Returns:
        self for chaining

      • setPrimitive

        public void setPrimitive​(Expr.Type type,
                         int val)
        Set the primitive value of this atom expression.
        Parameters:
        type - the type of expression
        val - the value to check

      • setPrimitive

        public void setPrimitive​(Expr.Type type)
        Set the primitive value of this atom expression.
        Parameters:
        type - the type of expression

      • setLogical

        public void setLogical​(Expr.Type type,
                       Expr left,
                       Expr right)
        Set the logical value of this atom expression.
        Parameters:
        type - the type of expression
        left - the left sub-expression
        right - the right sub-expression

      • set

        public void set​(Expr expr)
        Set this expression to another (shallow copy).
        Parameters:
        expr - the other expression

      • type

        public Expr.Type type()
        Access the type of the atom expression.
        Returns:
        the expression type

      • value

        public int value()
        Access the value of this atom expression being tested.
        Returns:
        the expression value

      • left

        public Expr left()
        Access the left sub-expression of this atom expression being tested.
        Returns:
        the expression value

      • right

        public Expr right()
        Access the right sub-expression of this atom expression being tested.
        Returns:
        the expression value

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object