RDKit
Open-source cheminformatics and machine learning.
RWMol.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2003-2021 Greg Landrum and other RDKit contributors
3 //
4 // @@ All Rights Reserved @@
5 // This file is part of the RDKit.
6 // The contents are covered by the terms of the BSD license
7 // which is included in the file license.txt, found at the root
8 // of the RDKit source tree.
9 //
10 /*! \file RWMol.h
11 
12  \brief Defines the editable molecule class \c RWMol
13 
14 */
15 
16 #include <RDGeneral/export.h>
17 
18 #ifndef RD_RWMOL_H
19 #define RD_RWMOL_H
20 
21 // our stuff
22 #include "ROMol.h"
23 #include "RingInfo.h"
24 
25 namespace RDKit {
26 
27 //! RWMol is a molecule class that is intended to be edited
28 /*!
29  See documentation for ROMol for general remarks
30 
31  */
33  public:
34  RWMol() : ROMol() {}
35  //! copy constructor with a twist
36  /*!
37  \param other the molecule to be copied
38  \param quickCopy (optional) if this is true, the resulting ROMol will not
39  copy any of the properties or bookmarks and conformers from \c other.
40  This can
41  make the copy substantially faster (thus the name).
42  \param confId if this is >=0, the resulting ROMol will contain only
43  the specified conformer from \c other.
44  */
45  RWMol(const ROMol &other, bool quickCopy = false, int confId = -1)
46  : ROMol(other, quickCopy, confId) {}
47  RWMol(const RWMol &other) : ROMol(other) {}
48  RWMol &operator=(const RWMol &);
49 
50  //! insert the atoms and bonds from \c other into this molecule
51  void insertMol(const ROMol &other);
52 
53  //! \name Atoms
54  //@{
55 
56  //! adds an empty Atom to our collection
57  /*!
58  \param updateLabel (optional) if this is true, the new Atom will be
59  our \c activeAtom
60 
61  \return the index of the added atom
62 
63  */
64  unsigned int addAtom(bool updateLabel = true);
65 
66  //! adds an Atom to our collection
67  /*!
68  \param atom pointer to the Atom to add
69  \param updateLabel (optional) if this is true, the new Atom will be
70  our \c activeAtom
71  \param takeOwnership (optional) if this is true, we take ownership of \c
72  atom
73  instead of copying it.
74 
75  \return the index of the added atom
76  */
77  unsigned int addAtom(Atom *atom, bool updateLabel = true,
78  bool takeOwnership = false) {
79  return ROMol::addAtom(atom, updateLabel, takeOwnership);
80  }
81 
82  //! adds an Atom to our collection
83 
84  //! replaces a particular Atom
85  /*!
86  \param idx the index of the Atom to replace
87  \param atom the new atom, which will be copied.
88  \param updateLabel (optional) if this is true, the new Atom will be
89  our \c activeAtom
90  \param preserveProps if true preserve the original atom property data
91 
92  */
93  void replaceAtom(unsigned int idx, Atom *atom, bool updateLabel = false,
94  bool preserveProps = false);
95  //! returns a pointer to the highest-numbered Atom
96  Atom *getLastAtom() { return getAtomWithIdx(getNumAtoms() - 1); }
97  //! returns a pointer to the "active" Atom
98  /*!
99  If we have an \c activeAtom, it will be returned,
100  otherwise the results of getLastAtom() will be returned.
101  */
103  //! sets our \c activeAtom
104  void setActiveAtom(Atom *atom);
105  //! \overload
106  void setActiveAtom(unsigned int idx);
107  //! removes an Atom from the molecule
108  void removeAtom(unsigned int idx);
109  //! \overload
110  void removeAtom(Atom *atom);
111 
112  //@}
113 
114  //! \name Bonds
115  //@{
116 
117  //! adds a Bond between the indicated Atoms
118  /*!
119  \return the number of Bonds
120  */
121  unsigned int addBond(unsigned int beginAtomIdx, unsigned int endAtomIdx,
123  //! \overload
124  unsigned int addBond(Atom *beginAtom, Atom *endAtom,
126 
127  //! adds a Bond to our collection
128  /*!
129  \param bond pointer to the Bond to add
130  \param takeOwnership (optional) if this is true, we take ownership of \c
131  bond
132  instead of copying it.
133 
134  \return the new number of bonds
135  */
136  unsigned int addBond(Bond *bond, bool takeOwnership = false) {
137  return ROMol::addBond(bond, takeOwnership);
138  }
139 
140  //! starts a Bond and sets its beginAtomIdx
141  /*!
142  \return a pointer to the new bond
143 
144  The caller should set a bookmark to the returned Bond in order
145  to be able to later complete it:
146 
147  \verbatim
148  Bond *pBond = mol->createPartialBond(1);
149  mol->setBondBookmark(pBond,666);
150  ... do some other stuff ...
151  mol->finishPartialBond(2,666,Bond::SINGLE);
152  mol->clearBondBookmark(666,pBond);
153  \endverbatim
154 
155  or, if we want to set the \c BondType initially:
156  \verbatim
157  Bond *pBond = mol->createPartialBond(1,Bond::DOUBLE);
158  mol->setBondBookmark(pBond,666);
159  ... do some other stuff ...
160  mol->finishPartialBond(2,666);
161  mol->clearBondBookmark(666,pBond);
162  \endverbatim
163 
164  the call to finishPartialBond() will take priority if you set the
165  \c BondType in both calls.
166 
167  */
168  Bond *createPartialBond(unsigned int beginAtomIdx,
170  //! finishes a partially constructed bond
171  /*!
172  \return the final number of Bonds
173 
174  See the documentation for createPartialBond() for more details
175  */
176  unsigned int finishPartialBond(unsigned int endAtomIdx, int bondBookmark,
178 
179  //! removes a bond from the molecule
180  void removeBond(unsigned int beginAtomIdx, unsigned int endAtomIdx);
181 
182  //! replaces a particular Bond
183  /*!
184  \param idx the index of the Bond to replace
185  \param bond the new bond, which will be copied.
186  \param preserveProps if true preserve the original bond property data
187  \param keepSGroups if true, keep Substance groups referencing the bond
188 
189  */
190  void replaceBond(unsigned int idx, Bond *bond, bool preserveProps = false,
191  bool keepSGroups = true);
192 
193  //@}
194 
195  //! Sets groups of atoms with relative stereochemistry
196  /*!
197  \param stereo_groups the new set of stereo groups. All will be replaced.
198 
199  Stereo groups are also called enhanced stereochemistry in the SDF/Mol3000
200  file format. stereo_groups should be std::move()ed into this function.
201  */
202  void setStereoGroups(std::vector<StereoGroup> &&stereo_groups) {
203  return ROMol::setStereoGroups(std::move(stereo_groups));
204  }
205 
206  //! removes all atoms, bonds, properties, bookmarks, etc.
207  void clear() {
208  destroy();
209  d_confs.clear();
210  ROMol::initMol(); // make sure we have a "fresh" ready to go copy
211  numBonds = 0;
212  }
213 
216  dp_delAtoms.reset();
217  dp_delBonds.reset();
218  }
220 };
221 
222 typedef boost::shared_ptr<RWMol> RWMOL_SPTR;
223 typedef std::vector<RWMOL_SPTR> RWMOL_SPTR_VECT;
224 
225 }; // namespace RDKit
226 
227 #endif
Defines the primary molecule class ROMol as well as associated typedefs.
The class for representing atoms.
Definition: Atom.h:68
class for representing a bond
Definition: Bond.h:46
BondType
the type of Bond
Definition: Bond.h:55
@ UNSPECIFIED
Definition: Bond.h:56
RWMol is a molecule class that is intended to be edited.
Definition: RWMol.h:32
void commitBatchEdit()
void removeAtom(unsigned int idx)
removes an Atom from the molecule
Bond * createPartialBond(unsigned int beginAtomIdx, Bond::BondType order=Bond::UNSPECIFIED)
starts a Bond and sets its beginAtomIdx
RWMol & operator=(const RWMol &)
void replaceAtom(unsigned int idx, Atom *atom, bool updateLabel=false, bool preserveProps=false)
adds an Atom to our collection
void removeAtom(Atom *atom)
This is an overloaded member function, provided for convenience. It differs from the above function o...
unsigned int addBond(Bond *bond, bool takeOwnership=false)
adds a Bond to our collection
Definition: RWMol.h:136
unsigned int addAtom(bool updateLabel=true)
adds an empty Atom to our collection
RWMol(const ROMol &other, bool quickCopy=false, int confId=-1)
copy constructor with a twist
Definition: RWMol.h:45
Atom * getActiveAtom()
returns a pointer to the "active" Atom
void rollbackBatchEdit()
Definition: RWMol.h:215
unsigned int addBond(unsigned int beginAtomIdx, unsigned int endAtomIdx, Bond::BondType order=Bond::UNSPECIFIED)
adds a Bond between the indicated Atoms
Atom * getLastAtom()
returns a pointer to the highest-numbered Atom
Definition: RWMol.h:96
unsigned int finishPartialBond(unsigned int endAtomIdx, int bondBookmark, Bond::BondType order=Bond::UNSPECIFIED)
finishes a partially constructed bond
unsigned int addAtom(Atom *atom, bool updateLabel=true, bool takeOwnership=false)
adds an Atom to our collection
Definition: RWMol.h:77
void beginBatchEdit()
unsigned int addBond(Atom *beginAtom, Atom *endAtom, Bond::BondType order=Bond::UNSPECIFIED)
This is an overloaded member function, provided for convenience. It differs from the above function o...
RWMol(const RWMol &other)
Definition: RWMol.h:47
void setStereoGroups(std::vector< StereoGroup > &&stereo_groups)
Sets groups of atoms with relative stereochemistry.
Definition: RWMol.h:202
void replaceBond(unsigned int idx, Bond *bond, bool preserveProps=false, bool keepSGroups=true)
replaces a particular Bond
void setActiveAtom(Atom *atom)
sets our activeAtom
void removeBond(unsigned int beginAtomIdx, unsigned int endAtomIdx)
removes a bond from the molecule
void setActiveAtom(unsigned int idx)
This is an overloaded member function, provided for convenience. It differs from the above function o...
void insertMol(const ROMol &other)
insert the atoms and bonds from other into this molecule
void clear()
removes all atoms, bonds, properties, bookmarks, etc.
Definition: RWMol.h:207
#define RDKIT_GRAPHMOL_EXPORT
Definition: export.h:209
Std stuff.
Definition: Abbreviations.h:18
std::vector< RWMOL_SPTR > RWMOL_SPTR_VECT
Definition: FileParsers.h:47
boost::shared_ptr< RWMol > RWMOL_SPTR
Definition: RWMol.h:222