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