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  RWMol(RWMol &&other) noexcept : ROMol(std::move(other)) {}
50  RWMol &operator=(RWMol &&other) noexcept {
51  ROMol::operator=(std::move(other));
52  return *this;
53  }
54 
55  //! insert the atoms and bonds from \c other into this molecule
56  void insertMol(const ROMol &other);
57 
58  //! \name Atoms
59  //! @{
60 
61  //! adds an empty Atom to our collection
62  /*!
63  \param updateLabel (optional) if this is true, the new Atom will be
64  our \c activeAtom
65 
66  \return the index of the added atom
67 
68  */
69  unsigned int addAtom(bool updateLabel = true);
70 
71  //! adds an Atom to our collection
72  /*!
73  \param atom pointer to the Atom to add
74  \param updateLabel (optional) if this is true, the new Atom will be
75  our \c activeAtom
76  \param takeOwnership (optional) if this is true, we take ownership of \c
77  atom
78  instead of copying it.
79 
80  \return the index of the added atom
81  */
82  unsigned int addAtom(Atom *atom, bool updateLabel = true,
83  bool takeOwnership = false) {
84  return ROMol::addAtom(atom, updateLabel, takeOwnership);
85  }
86 
87  //! adds an Atom to our collection
88 
89  //! replaces a particular Atom
90  /*!
91  \param idx the index of the Atom to replace
92  \param atom the new atom, which will be copied.
93  \param updateLabel (optional) if this is true, the new Atom will be
94  our \c activeAtom
95  \param preserveProps if true preserve the original atom property data
96 
97  */
98  void replaceAtom(unsigned int idx, Atom *atom, bool updateLabel = false,
99  bool preserveProps = false);
100  //! returns a pointer to the highest-numbered Atom
101  Atom *getLastAtom() { return getAtomWithIdx(getNumAtoms() - 1); }
102  //! returns a pointer to the "active" Atom
103  /*!
104  If we have an \c activeAtom, it will be returned,
105  otherwise the results of getLastAtom() will be returned.
106  */
108  //! sets our \c activeAtom
109  void setActiveAtom(Atom *atom);
110  //! \overload
111  void setActiveAtom(unsigned int idx);
112  //! removes an Atom from the molecule
113  void removeAtom(unsigned int idx);
114  //! \overload
115  void removeAtom(Atom *atom);
116 
117  //! @}
118 
119  //! \name Bonds
120  //! @{
121 
122  //! adds a Bond between the indicated Atoms
123  /*!
124  \return the number of Bonds
125  */
126  unsigned int addBond(unsigned int beginAtomIdx, unsigned int endAtomIdx,
128  //! \overload
129  unsigned int addBond(Atom *beginAtom, Atom *endAtom,
131 
132  //! adds a Bond to our collection
133  /*!
134  \param bond pointer to the Bond to add
135  \param takeOwnership (optional) if this is true, we take ownership of \c
136  bond
137  instead of copying it.
138 
139  \return the new number of bonds
140  */
141  unsigned int addBond(Bond *bond, bool takeOwnership = false) {
142  return ROMol::addBond(bond, takeOwnership);
143  }
144 
145  //! starts a Bond and sets its beginAtomIdx
146  /*!
147  \return a pointer to the new bond
148 
149  The caller should set a bookmark to the returned Bond in order
150  to be able to later complete it:
151 
152  \verbatim
153  Bond *pBond = mol->createPartialBond(1);
154  mol->setBondBookmark(pBond,666);
155  ... do some other stuff ...
156  mol->finishPartialBond(2,666,Bond::SINGLE);
157  mol->clearBondBookmark(666,pBond);
158  \endverbatim
159 
160  or, if we want to set the \c BondType initially:
161  \verbatim
162  Bond *pBond = mol->createPartialBond(1,Bond::DOUBLE);
163  mol->setBondBookmark(pBond,666);
164  ... do some other stuff ...
165  mol->finishPartialBond(2,666);
166  mol->clearBondBookmark(666,pBond);
167  \endverbatim
168 
169  the call to finishPartialBond() will take priority if you set the
170  \c BondType in both calls.
171 
172  */
173  Bond *createPartialBond(unsigned int beginAtomIdx,
175  //! finishes a partially constructed bond
176  /*!
177  \return the final number of Bonds
178 
179  See the documentation for createPartialBond() for more details
180  */
181  unsigned int finishPartialBond(unsigned int endAtomIdx, int bondBookmark,
183 
184  //! removes a bond from the molecule
185  void removeBond(unsigned int beginAtomIdx, unsigned int endAtomIdx);
186 
187  //! replaces a particular Bond
188  /*!
189  \param idx the index of the Bond to replace
190  \param bond the new bond, which will be copied.
191  \param preserveProps if true preserve the original bond property data
192  \param keepSGroups if true, keep Substance groups referencing the bond
193 
194  */
195  void replaceBond(unsigned int idx, Bond *bond, bool preserveProps = false,
196  bool keepSGroups = true);
197 
198  //! @}
199 
200  //! removes all atoms, bonds, properties, bookmarks, etc.
201  void clear() {
202  destroy();
203  d_confs.clear();
204  ROMol::initMol(); // make sure we have a "fresh" ready to go copy
205  numBonds = 0;
206  }
207 
210  dp_delAtoms.reset();
211  dp_delBonds.reset();
212  }
214 };
215 
216 typedef boost::shared_ptr<RWMol> RWMOL_SPTR;
217 typedef std::vector<RWMOL_SPTR> RWMOL_SPTR_VECT;
218 
219 }; // namespace RDKit
220 
221 #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:47
BondType
the type of Bond
Definition: Bond.h:56
@ UNSPECIFIED
Definition: Bond.h:57
ROMol & operator=(ROMol &&o) noexcept
Definition: ROMol.h:370
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:141
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:209
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:101
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:82
void beginBatchEdit()
RWMol & operator=(RWMol &&other) noexcept
Definition: RWMol.h:50
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 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
RWMol(RWMol &&other) noexcept
Definition: RWMol.h:49
void clear()
removes all atoms, bonds, properties, bookmarks, etc.
Definition: RWMol.h:201
#define RDKIT_GRAPHMOL_EXPORT
Definition: export.h:225
Std stuff.
Definition: Abbreviations.h:19
std::vector< RWMOL_SPTR > RWMOL_SPTR_VECT
Definition: FileParsers.h:48
boost::shared_ptr< RWMol > RWMOL_SPTR
Definition: RWMol.h:216