Logo Search packages:      
Sourcecode: cdk version File versions  Download package

IAtomContainer.java
/* $Revision$ $Author$ $Date$
 *
 * Copyright (C) 2006-2007  Egon Willighagen <egonw@users.sf.net>
 *
 * Contact: cdk-devel@lists.sourceforge.net
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 */
package org.openscience.cdk.interfaces;

import org.openscience.cdk.interfaces.IBond.Order;

import java.util.List;

/**
 *  Base class for all chemical objects that maintain a list of Atoms and
 *  ElectronContainers. <p>
 *
 *  Looping over all <code>IBond</code>s in the <code>IAtomContainer</code>
 *  is typically done like:
 *  <pre>
 *  for (IBond bond : atomContainer.bonds()) {
 *    // do something
 *  }
 *  </pre>
 * If you do need an explicit Iterator then use
 * <pre>
 * Iterator<IBond> bondIter = atomContainer.bonds().iterator();
 * </pre>
 *
 * @cdk.module interfaces
 * @cdk.githash
 *
 * @author     steinbeck
 * @cdk.created    2000-10-02
 */
00049 public interface IAtomContainer extends IChemObject, IChemObjectListener {

    /**
     * Adds an AtomParity to this container. If a parity is already given for the
     * affected Atom, it is overwritten.
     *
     * @param parity The new AtomParity for this container
     * @see   #getAtomParity
     */
    public void addAtomParity(IAtomParity parity);

    /**
     * Returns the atom parity for the given Atom. If no parity is associated
     * with the given Atom, it returns null.
     *
     * @param  atom   Atom for which the parity must be returned
     * @return The AtomParity for the given Atom, or null if that Atom does
     *         not have an associated AtomParity
     * @see    #addAtomParity
     */
    public IAtomParity getAtomParity(IAtom atom);
    
      /**
       * Sets the array of atoms of this AtomContainer.
       *
       * @param  atoms  The array of atoms to be assigned to this AtomContainer
       * @see           #atoms
       */
      public void setAtoms(IAtom[] atoms);
      
      /**
       * Sets the array of bonds of this AtomContainer.
       *
       * @param  bonds  The array of bonds to be assigned to
       *                             this AtomContainer
       * @see  #bonds
       */
      public void setBonds(IBond[] bonds);
      
      /**
       * Set the atom at position <code>number</code> in [0,..].
       *
       * @param  number  The position of the atom to be set.
       * @param  atom    The atom to be stored at position <code>number</code>
       * @see            #getAtom
       */
      public void setAtom(int number, IAtom atom);

      /**
       * Get the atom at position <code>number</code> in [0,..].
       *
       * @param  number  The position of the atom to be retrieved.
       * @return         The atom number
       * @see            #setAtom
       */
      public IAtom getAtom(int number);

      /**
       *  Get the bond at position <code>number</code> in [0,..].
       *
       *@param  number  The position of the bond to be retrieved.
       *@return         The bond number
       */
      public IBond getBond(int number);

      /**
       *  Get the lone pair at position <code>number</code> in [0,..].
       *
       *@param  number  The position of the LonePair to be retrieved.
       *@return         The lone pair number
       */
      public ILonePair getLonePair(int number);
      
      /**
       *  Get the single electron at position <code>number</code> in [0,..].
       *
       *@param  number  The position of the SingleElectron to be retrieved.
       *@return         The single electron number
       */
      public ISingleElectron getSingleElectron(int number);

      /**
       *  Returns an Iterable for looping over all atoms in this container.
       *
       *@return    An Iterable with the atoms in this container
       */
      public Iterable<IAtom> atoms();

      /**
       *  Returns an Iterable for looping over all bonds in this container.
       *
       *@return    An Iterable with the bonds in this container
       */
      public Iterable<IBond> bonds();
      
      /**
       *  Returns an Iterable for looping over all lone pairs in this container.
       *
       *@return    An Iterable with the lone pairs in this container
       */
      public Iterable<ILonePair> lonePairs();
      
      /**
       *  Returns an Iterable for looping over all single electrons in this container.
       *
       *@return    An Iterable with the single electrons in this container
       */
      public Iterable<ISingleElectron> singleElectrons();
      
      /**
       *  Returns an Iterable for looping over all electron containers in this container.
       *
       *@return    An Iterable with the electron containers in this container
       */
      public Iterable<IElectronContainer> electronContainers();
      
      /**
       *  Returns the atom at position 0 in the container.
       *
       *@return    The atom at position 0 .
       */
      public IAtom getFirstAtom();


      /**
       *  Returns the atom at the last position in the container.
       *
       *@return    The atom at the last position
       */
      public IAtom getLastAtom();


      /**
       *  Returns the position of a given atom in the atoms array. It returns -1 if
       *  the atom atom does not exist.
       *
       *@param  atom  The atom to be sought
       *@return       The Position of the atom in the atoms array in [0,..].
       */
      public int getAtomNumber(IAtom atom);


      /**
       *  Returns the position of the bond between two given atoms in the
       *  electronContainers array. It returns -1 if the bond does not exist.
       *
       *@param  atom1  The first atom
       *@param  atom2  The second atom
       *@return        The Position of the bond between a1 and a2 in the
       *               electronContainers array.
       */
      public int getBondNumber(IAtom atom1, IAtom atom2);


      /**
       *  Returns the position of a given bond in the electronContainers array. It
       *  returns -1 if the bond does not exist.
       *
       *@param  bond  The bond to be sought
       *@return       The Position of the bond in the electronContainers array in [0,..].
       */
      public int getBondNumber(IBond bond);

      /**
       * Returns the position of a given lone pair in the lone pair array. 
       * It returns -1 if the lone pair does not exist.
       *
       * @param  lonePair The lone pair to be sought
       * @return          The Position of the lone pair in the array..
       */
      public int getLonePairNumber(ILonePair lonePair);
      
      /**
       * Returns the position of a given single electron in the single electron array. 
       * It returns -1 if the single electron does not exist.
       *
       * @param  singleElectron The single electron to be sought
       * @return                The Position of the single electron in the array.
       */
      public int getSingleElectronNumber(ISingleElectron singleElectron);
      
      /**
       *  Returns the ElectronContainer at position <code>number</code> in the
       *  container.
       *
       *@param  number  The position of the ElectronContainer to be returned.
       *@return         The ElectronContainer at position <code>number</code>.
       *@see            #addElectronContainer(IElectronContainer) 
       */
      public IElectronContainer getElectronContainer(int number);


      /**
       * Returns the bond that connectes the two given atoms.
       *
       * @param  atom1  The first atom
       * @param  atom2  The second atom
       * @return        The bond that connectes the two atoms
       */
      public IBond getBond(IAtom atom1, IAtom atom2);



      /**
       *  Returns the number of Atoms in this Container.
       *
       *@return    The number of Atoms in this Container
       */
      public int getAtomCount();

      /**
       *  Returns the number of Bonds in this Container.
       *
       *@return    The number of Bonds in this Container
       */
      public int getBondCount();

      /**
       *  Returns the number of LonePairs in this Container.
       *
       *@return    The number of LonePairs in this Container
       */
      public int getLonePairCount();

      /**
       * Returns the number of the single electrons in this container.
       *
       * @return       The number of SingleElectron objects of this AtomContainer
       */
      public int getSingleElectronCount();
      
      /**
       * Returns the number of ElectronContainers in this Container.
       *
       * @return    The number of ElectronContainers in this Container
       */
      public int getElectronContainerCount();
      
      /**
       *  Returns an ArrayList of all atoms connected to the given atom.
       *
       *@param  atom  The atom the bond partners are searched of.
       *@return       The ArrayList with the connected atoms
       */
      public List<IAtom> getConnectedAtomsList(IAtom atom);

      /**
       *  Returns an ArrayList of all Bonds connected to the given atom.
       *
       *@param  atom  The atom the connected bonds are searched of
       *@return       The ArrayList with connected atoms
       */
      public List<IBond> getConnectedBondsList(IAtom atom);

      /**
       *  Returns the array of lone pairs connected to an atom.
       *
       *@param  atom  The atom for which to get lone pairs
       *@return       The array of LonePairs of this AtomContainer
       */
      public List<ILonePair> getConnectedLonePairsList(IAtom atom);

      /**
       *  Returns an array of all SingleElectron connected to the given atom.
       *
       *@param  atom  The atom on which the single electron is located
       *@return       The array of SingleElectron of this AtomContainer
       */
      public List<ISingleElectron> getConnectedSingleElectronsList(IAtom atom);
      
      /**
       *  Returns an ArrayList of all electronContainers connected to the given atom.
       *
       *@param  atom  The atom the connected electronContainers are searched of
       *@return       The ArrayList with the  connected atoms
       */
      public List<IElectronContainer> getConnectedElectronContainersList(IAtom atom);

      
      /**
       *  Returns the number of atoms connected to the given atom.
       *
       *@param  atom  The atom the number of bond partners are searched of.
       *@return       The the size of connected atoms
       */
      public int getConnectedAtomsCount(IAtom atom);
      
      /**
       *  Returns the number of Bonds for a given Atom.
       *
       *@param  atom  The atom
       *@return       The number of Bonds for this atom
       */
      public int getConnectedBondsCount(IAtom atom);

      /**
       *  Returns the number of connected atoms (degree) to the given atom.
       *
       *@param  atomnumber  The atomnumber the degree is searched for
       *@return             The number of connected atoms (degree)
       */
      public int getConnectedBondsCount(int atomnumber);

      /**
       *  Returns the number of LonePairs for a given Atom.
       *
       *@param  atom  The atom
       *@return       The number of LonePairs for this atom
       */
      public int getConnectedLonePairsCount(IAtom atom);
      
      /**
       *  Returns the sum of the SingleElectron for a given Atom.
       *
       *@param  atom  The atom on which the single electron is located
       *@return       The array of SingleElectron of this AtomContainer
       */
      public int getConnectedSingleElectronsCount(IAtom atom);
      
      /**
       * Returns the sum of the bond orders for a given Atom.
       *
       * @param  atom  The atom
       * @return       The number of bondorders for this atom
       */
      public double getBondOrderSum(IAtom atom);

    /**
       * Returns the maximum bond order that this atom currently has in the context
       * of this AtomContainer.
       *
       * @param  atom  The atom
       * @return       The maximum bond order that this atom currently has
       */
      public Order getMaximumBondOrder(IAtom atom);


      /**
       *  Returns the minimum bond order that this atom currently has in the context
       *  of this AtomContainer.
       *
       *@param  atom  The atom
       *@return       The minimim bond order that this atom currently has
       */
      public Order getMinimumBondOrder(IAtom atom);

      /**
       *  Adds all atoms and electronContainers of a given atomcontainer to this
       *  container.
       *
       *@param  atomContainer  The atomcontainer to be added
       */
      public void add(IAtomContainer atomContainer);


      /**
       *  Adds an atom to this container.
       *
       *@param  atom  The atom to be added to this container
       */
      public void addAtom(IAtom atom);


      /**
       *  Adds a Bond to this AtomContainer.
       *
       *@param  bond  The bond to added to this container
       */
      public void addBond(IBond bond);

      /**
       *  Adds a lone pair to this AtomContainer.
       *
       *@param  lonePair  The LonePair to added to this container
       */
      public void addLonePair(ILonePair lonePair);
      
      /**
       *  Adds a single electron to this AtomContainer.
       *
       *@param  singleElectron  The SingleElectron to added to this container
       */
      public void addSingleElectron(ISingleElectron singleElectron);

      /**
       *  Adds a ElectronContainer to this AtomContainer.
       *
       *@param  electronContainer  The ElectronContainer to added to this container
       */
      public void addElectronContainer(IElectronContainer electronContainer);


      /**
       *  Removes all atoms and electronContainers of a given atomcontainer from this
       *  container.
       *
       *@param  atomContainer  The atomcontainer to be removed
       */
      public void remove(IAtomContainer atomContainer);

      /**
       *  Removes the atom at the given position from the AtomContainer. Note that
       *  the electronContainers are unaffected: you also have to take care of
       *  removing all electronContainers to this atom from the container manually.
       *
       *@param  position  The position of the atom to be removed.
       */
      public void removeAtom(int position);

      /**
       *  Removes the given atom from the AtomContainer. Note that the
       *  electronContainers are unaffected: you also have to take care of removeing
       *  all electronContainers to this atom from the container.
       *
       *@param  atom  The atom to be removed
       */
      public void removeAtom(IAtom atom);
      
      /**
       *  Removes the bond at the given position from the AtomContainer.
       *
       *@param  position  The position of the bond to be removed.
       */
      public IBond removeBond(int position);
      
      /**
       * Removes the bond that connects the two given atoms.
       *
       * @param  atom1  The first atom
       * @param  atom2  The second atom
       * @return        The bond that connectes the two atoms
       */
      public IBond removeBond(IAtom atom1, IAtom atom2);

      /**
       * Removes the bond from this container.
       *
       * @param  bond   The bond to be removed.
       */
      public void removeBond(IBond bond);
      
      /**
       * Removes the lone pair at the given position from the AtomContainer.
       *
       * @param  position  The position of the LonePair to be removed.
       * @return           The removed ILonePair.
       */
      public ILonePair removeLonePair(int position);
      
      /**
       * Removes the lone pair from the AtomContainer.
       *
       * @param  lonePair  The LonePair to be removed.
       */
      public void removeLonePair(ILonePair lonePair);
      
      /**
       * Removes the single electron at the given position from the AtomContainer.
       *
       * @param  position  The position of the SingleElectron to be removed.
       * @return           The removed ISingleElectron
       */
      public ISingleElectron removeSingleElectron(int position);
      
      /**
       * Removes the single electron from the AtomContainer.
       *
       * @param  singleElectron  The SingleElectron to be removed.
       */
      public void removeSingleElectron(ISingleElectron singleElectron);
      
      /**
       * Removes the bond at the given position from this container.
       *
       * @param  position  The position of the bond in the electronContainers array
       * @return           the IElectronContainer that was removed
       */
      public IElectronContainer removeElectronContainer(int position);


      /**
       * Removes this ElectronContainer from this container.
       *
       * @param  electronContainer    The electronContainer to be removed
       */
      public void removeElectronContainer(IElectronContainer electronContainer);

      
      /**
       *  Removes the given atom and all connected electronContainers from the
       *  AtomContainer.
       *
       *@param  atom  The atom to be removed
       */
      public void removeAtomAndConnectedElectronContainers(IAtom atom);

      /**
       * Removes all atoms and bond from this container.
       */
      public void removeAllElements();


      /**
       *  Removes electronContainers from this container.
       */
      public void removeAllElectronContainers();

    /**
     *  Removes all Bonds from this container.
     */
    public void removeAllBonds();

      /**
       *  Adds a bond to this container.
       *
       *@param  atom1   Id of the first atom of the Bond in [0,..]
       *@param  atom2   Id of the second atom of the Bond in [0,..]
       *@param  order   Bondorder
       *@param  stereo  Stereochemical orientation
       */
      public void addBond(int atom1, int atom2, IBond.Order order, int stereo);


      /**
       *  Adds a bond to this container.
       *
       *@param  atom1  Id of the first atom of the Bond in [0,..]
       *@param  atom2  Id of the second atom of the Bond in [0,..]
       *@param  order  Bondorder
       */
      public void addBond(int atom1, int atom2, IBond.Order order);


      /**
       *  Adds a LonePair to this Atom.
       *
       *@param  atomID  The atom number to which the LonePair is added in [0,..]
       */
      public void addLonePair(int atomID);

      /**
       *  Adds a SingleElectron to this Atom.
       *
       *@param  atomID  The atom number to which the SingleElectron is added in [0,..]
       */
      public void addSingleElectron(int atomID);
      
      /**
       *  True, if the AtomContainer contains the given atom object.
       *
       *@param  atom  the atom this AtomContainer is searched for
       *@return       True, if the AtomContainer contains the given atom object
       */
      public boolean contains(IAtom atom);

      /**
       *  True, if the AtomContainer contains the given bond object.
       *
       *@param  bond  the bond this AtomContainer is searched for
       *@return       True, if the AtomContainer contains the given bond object
       */
      public boolean contains(IBond bond);
      
      /**
       *  True, if the AtomContainer contains the given LonePair object.
       *
       *@param  lonePair  the LonePair this AtomContainer is searched for
       *@return           True, if the AtomContainer contains the given LonePair object
       */
      public boolean contains(ILonePair lonePair);
      
      /**
       *  True, if the AtomContainer contains the given SingleElectron object.
       *
       *@param  singleElectron  the SingleElectron this AtomContainer is searched for
       *@return                 True, if the AtomContainer contains the given SingleElectron object
       */
      public boolean contains(ISingleElectron singleElectron);
      
      /**
       *  True, if the AtomContainer contains the given ElectronContainer object.
       *
       *@param  electronContainer ElectronContainer that is searched for
       *@return                   True, if the AtomContainer contains the given bond object
       */
      public boolean contains(IElectronContainer electronContainer);

}



Generated by  Doxygen 1.6.0   Back to index