Class IteratorFactory


  • @PublicAPI
    public class IteratorFactory
    extends Object
    The IteratorFactory class provides implementations of Iterator to ease the handling of atoms and bonds used in Molecule objects and its descendants. The following iterators are included in this class:
    • AtomIterator
    • BondIterator
    • AtomNeighbourIterator
    • BondNeighbourIterator
    • RxnComponentIterator
    • RgComponentIterator

    API usage example:

          //initialize an RgMolecule; 
          RgMolecule mol = ... ;
          //create the iterator factory with the specified molecule and parameters related to atoms and bonds.
          IteratorFactory factory = new IteratorFactory(mol, IteratorFactory.INCLUDE_ALL_ATOMS, IteratorFactory.INCLUDE_ALL_BONDS);
          RgComponentIterator rgIterator = factory.createRgComponentIterator();
          //iteration on the components of the RgMolecule.
          while (rgIterator.hasNext()) {
              Molecule component = rgIterator.next();
              IteratorFactory ifc = new IteratorFactory(component, IteratorFactory.SKIP_PSEUDO_ATOM | IteratorFactory.SKIP_EXPLICIT_H,
                      IteratorFactory.SKIP_COORDINATE_BONDS);
              AtomIterator atomIterator = ifc.createAtomIterator();
              //iteration on the atoms of a component
              while (atomIterator.hasNext()){
                  MolAtom atom = atomIterator.next();
                  //process the atom
                  ...
              }
              //iteration on the bonds of a component
              BondIterator bondIterator = ifc.createBondIterator();
              while (bondIterator.hasNext()){
                  MolBond bond = bondIterator.next();
                  //process the bond
                  ...
              }
          }       
          
          //the inclusion pattern of IteratorFactory can be rewritten to exclude
          //more atoms and/or bonds, for example:
          IteratorFactory factory2 = new IteratorFactory(mol, 
            IteratorFactory.INCLUDE_CHEMICAL_ATOMS_ONLY, IteratorFactory.INCLUDE_ALL_BONDS) {
              //this ensures that only chemical atoms with properties are iterated
              public boolean isExcludedAtom(MolAtom atom) {
            return (atom.propertyCount() == 0);
              }
              //the same can be done for bonds with isExcludedBond(MolBond bond)
          };
     
    Since:
    Marvin 5.1
    See Also:
    MolAtom, MolBond, Molecule, RxnMolecule, RgMolecule
    • Field Detail

      • INCLUDE_ALL_BONDS

        public static final int INCLUDE_ALL_BONDS
        Include all bonds: covalent and coordinate bonds in bond iteration.
        See Also:
        Constant Field Values
      • SKIP_COORDINATE_BONDS

        public static final int SKIP_COORDINATE_BONDS
        Exclude coordinate bonds from bond iteration.
        See Also:
        Constant Field Values
      • SKIP_COVALENT_BONDS

        public static final int SKIP_COVALENT_BONDS
        Exclude covalent bonds from bond iteration.
        See Also:
        Constant Field Values
      • REPLACE_COORDINATE_BONDS

        public static final int REPLACE_COORDINATE_BONDS
        Replace coordinate bonds to multicenter atoms with coordinate bonds from the metal to the represented atoms (in the MulticenterSgroup of the multicenter). These secondary bonds are not added to the molecule of the factory, so do not use Molecule.indexOf for the secondary bonds!
        See Also:
        Constant Field Values
      • INCLUDE_ALL_ATOMS

        public static final int INCLUDE_ALL_ATOMS
        Include all atoms: chemical atoms, explicit hydrogen, multicenter, lone pair and pseudo atoms in atom iterations.
        See Also:
        Constant Field Values
      • SKIP_EXPLICIT_H

        public static final int SKIP_EXPLICIT_H
        Exclude explicit hydrogens from atom iteration.
        See Also:
        Constant Field Values
      • SKIP_MULTICENTER

        public static final int SKIP_MULTICENTER
        Exclude multicenters from atom iteration.
        See Also:
        Constant Field Values
      • SKIP_LONE_PAIR

        public static final int SKIP_LONE_PAIR
        Exclude lone pairs from atom iteration.
        See Also:
        Constant Field Values
      • SKIP_PSEUDO_ATOM

        public static final int SKIP_PSEUDO_ATOM
        Exclude pseudo atoms from atom iteration.
        See Also:
        Constant Field Values
      • INCLUDE_CHEMICAL_ATOMS_ONLY

        public static final int INCLUDE_CHEMICAL_ATOMS_ONLY
        Include only chemical atoms in iteration, skip multicenters, lone pairs and pseudo atoms.
        See Also:
        Constant Field Values
    • Constructor Detail

      • IteratorFactory

        public IteratorFactory​(Molecule mol,
                               int atomRelatedBehavior,
                               int bondRelatedBehavior)
        Constructs an iterator factory for the specified molecule with a specified atom and bond related behavior. Atom and bond related behavior can be set with the constants below, using the bitwise | operator (which means AND here) to combine them.
        Parameters:
        mol - the molecule whose atoms and bonds to be iterated.
        atomRelatedBehavior - the behavior how to iterate on atoms. Specify with the constants:
        • INCLUDE_ALL_ATOMS
        • INCLUDE_CHEMICAL_ATOMS_ONLY
        • SKIP_EXPLICIT_H
        • SKIP_MULTICENTER
        • SKIP_LONE_PAIR
        • SKIP_PSEUDO_ATOM
        bondRelatedBehavior - the behavior how to iterate on bonds. Specify with the constants:
        • INCLUDE_ALL_BONDS
        • SKIP_COORDINATE_BONDS
        • SKIP_COVALENT_BONDS
        • REPLACE_COORDINATE_BONDS
      • IteratorFactory

        public IteratorFactory​(Molecule mol)
        Constructs an iterator factory for the specified molecule with default atom and bond related behavior to include all atoms and bonds.
        See Also:
        INCLUDE_ALL_ATOMS, INCLUDE_ALL_BONDS
      • IteratorFactory

        public IteratorFactory​(MoleculeGraph mol)
        Constructs an iterator factory for the specified molecule with default atom and bond related behavior to include all atoms and bonds.
        See Also:
        INCLUDE_ALL_ATOMS, INCLUDE_ALL_BONDS
    • Method Detail

      • createAtomIterator

        public IteratorFactory.AtomIterator createAtomIterator()
        Constructs an atom iterator for the specified molecule of the factory according to the atom related behavior set in the factory.
        Returns:
        the atom iterator
      • createBondIterator

        public IteratorFactory.BondIterator createBondIterator()
        Constructs a bond iterator for the specified molecule of the factory according to bond related behavior set in the factory.
        Returns:
        the bond iterator
      • createSgroupIterator

        public IteratorFactory.SgroupIterator createSgroupIterator()
        Constructs an s-group iterator for the specified molecule of the factory.
        Returns:
        the s-group iterator
      • createAtomNeighbourIterator

        public IteratorFactory.AtomNeighbourIterator createAtomNeighbourIterator​(MolAtom atom)
        Constructs an iterator to get the atom neighbours of the specified atom. The following atoms are excluded:
        • atoms excluded in the atom related behavior of the factory and
        • atoms connecting with bonds that are excluded in the bond related behavior of the factory.
        Parameters:
        atom - the atom whose neighbour atoms to be iterated
        Returns:
        the atom neighbour iterator of the specified atom
      • createBondNeighbourIterator

        public IteratorFactory.BondNeighbourIterator createBondNeighbourIterator​(MolAtom atom)
        Constructs an iterator to get the bonds connecting to the specified atom. The following bonds are excluded:
        • bonds excluded in the bond related behavior of the factory and
        • bonds connecting to atoms that are excluded in the atom related behavior of the factory.
        Parameters:
        atom - the atom whose bonds to be iterated
        Returns:
        the bond neighbour iterator of the specified atom
      • createRxnComponentIterator

        public IteratorFactory.RxnComponentIterator createRxnComponentIterator()
        Constructs a reaction component iterator for the specified molecule of the factory if the molecule is an RxnMolecule, an empty iterator otherwise.
        Returns:
        the reaction component iterator
      • createRgComponentIterator

        public IteratorFactory.RgComponentIterator createRgComponentIterator()
        Constructs an rgroup definition component iterator for the specified molecule of the factory if the molecule is an RgMolecule, an empty iterator otherwise.
        Returns:
        the rgroup component iterator
      • isExcludedAtom

        public boolean isExcludedAtom​(MolAtom atom)
        By overriding this method, the inclusion pattern of IteratorFactory can be rewritten to exclude more atoms, than it would normally. By default, this method returns false.
        Parameters:
        atom - the atom to be checked
        Returns:
        whether the atom should be excluded
      • isExcludedBond

        public boolean isExcludedBond​(MolBond bond)
        By overriding this method, the inclusion pattern of IteratorFactory can be rewritten to exclude more bonds, than it would normally. By default, this method returns false.
        Parameters:
        bond - the bond to be checked
        Returns:
        whether the bond should be excluded
      • numberOfAtoms

        public int numberOfAtoms()
        Returns the number of atoms iterated by AtomIterator. It currently works by creating an AtomIterator, and iterating through it. This might make it unsuitable for some uses, where performance is important.
        Returns:
        the number of atoms
      • numberOfBonds

        public int numberOfBonds()
        Returns the number of bonds iterated by BondIterator. It currently works by creating a BondIterator, and iterating through it. This might make it unsuitable for some uses, where performance is important.
        Returns:
        the number of bonds
      • numberOfNeighbours

        public int numberOfNeighbours​(MolAtom atom)
        Returns the number of atoms/bonds iterated by (Atom/Bond)NeighbourIterator (the two values are the same). It currently works by creating a BondNeighbourIterator, and iterating through it. This might make it unsuitable for some uses, where performance is important.
        Returns:
        the number of neighbours