Class IteratorFactory

java.lang.Object
chemaxon.util.iterator.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:
  • Field Details

    • INCLUDE_ALL_BONDS

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

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

      public static final int SKIP_COVALENT_BONDS
      Exclude covalent bonds from bond iteration.
      See Also:
    • 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:
    • 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:
    • SKIP_EXPLICIT_H

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

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

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

      public static final int SKIP_PSEUDO_ATOM
      Exclude pseudo atoms from atom iteration.
      See Also:
    • INCLUDE_CHEMICAL_ATOMS

      @Deprecated(forRemoval=true) @SubjectToRemoval(date=JUL_01_2025) public static final int INCLUDE_CHEMICAL_ATOMS
      Deprecated, for removal: This API element is subject to removal in a future version.
      As of Marvin 6.2, Use INCLUDE_CHEMICAL_ATOMS_ONLY instead.
      Include only chemical atoms in iteration, skip multicenters, lone pairs and pseudo atoms.
      See Also:
    • 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:
  • Constructor Details

    • 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:
    • 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:
  • Method Details

    • 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