RDKit
Open-source cheminformatics and machine learning.
Bond.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2014 Greg Landrum and Rational Discovery LLC
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 #ifndef _RD_BOND_H
11 #define _RD_BOND_H
12 
13 // std stuff
14 #include <iostream>
15 
16 // Ours
17 // FIX: grn...
18 #include <Query/QueryObjects.h>
19 #include <RDGeneral/types.h>
20 #include <GraphMol/details.h>
21 #include <boost/foreach.hpp>
22 
23 namespace RDKit {
24 class ROMol;
25 class RWMol;
26 class Atom;
27 typedef boost::shared_ptr<Atom> ATOM_SPTR;
28 
29 //! class for representing a bond
30 /*!
31 
32  <b>Notes:</b>
33  - many of the methods of Atom require that the Atom be associated
34  with a molecule (an ROMol).
35  - each Bond maintains a Dict of \c properties:
36  - Each \c property is keyed by name and can store an
37  arbitrary type.
38  - \c Properties can be marked as \c calculated, in which case
39  they will be cleared when the \c clearComputedProps() method
40  is called.
41  - Because they have no impact upon chemistry, all \c property
42  operations are \c const, this allows extra flexibility for
43  clients who need to store extra data on Bond objects.
44 
45 */
46 class Bond {
47  friend class RWMol;
48  friend class ROMol;
49 
50  public:
51  typedef boost::shared_ptr<Bond> BOND_SPTR;
52  // FIX: grn...
54 
55  //! the type of Bond
56  typedef enum {
73  DATIVEONE, //!< one-electron dative (e.g. from a C in a Cp ring to a metal)
74  DATIVE, //!< standard two-electron dative
75  DATIVEL, //!< standard two-electron dative
76  DATIVER, //!< standard two-electron dative
78  ZERO //!< Zero-order bond (from
79  // http://pubs.acs.org/doi/abs/10.1021/ci200488k)
80  } BondType;
81 
82  //! the bond's direction (for chirality)
83  typedef enum {
84  NONE = 0, //!< no special style
85  BEGINWEDGE, //!< wedged: narrow at begin
86  BEGINDASH, //!< dashed: narrow at begin
87  // FIX: this may not really be adequate
88  ENDDOWNRIGHT, //!< for cis/trans
89  ENDUPRIGHT, //!< ditto
90  EITHERDOUBLE, //!< a "crossed" double bond
91  UNKNOWN, //!< intentionally unspecified stereochemistry
92  } BondDir;
93 
94  //! the nature of the bond's stereochem (for cis/trans)
95  typedef enum { // stereochemistry of double bonds
96  STEREONONE = 0, // no special style
97  STEREOANY, // intentionally unspecified
98  // -- Put any true specifications about this point so
99  // that we can do comparisons like if(bond->getStereo()>Bond::STEREOANY)
100  STEREOZ, // Z double bond
101  STEREOE, // E double bond
102  } BondStereo;
103 
104  Bond();
105  //! construct with a particular BondType
106  explicit Bond(BondType bT);
107  Bond(const Bond &other);
108  virtual ~Bond();
109  Bond &operator=(const Bond &other);
110 
111  //! returns a copy
112  /*!
113  <b>Note:</b> the caller is responsible for <tt>delete</tt>ing
114  the returned pointer.
115  */
116  virtual Bond *copy() const;
117 
118  //! returns our \c bondType
119  BondType getBondType() const { return static_cast<BondType>(d_bondType); };
120  //! sets our \c bondType
121  void setBondType(BondType bT) { d_bondType = bT; };
122  //! \brief returns our \c bondType as a double
123  //! (e.g. SINGLE->1.0, AROMATIC->1.5, etc.)
124  double getBondTypeAsDouble() const;
125 
126  //! returns our contribution to the explicit valence of an Atom
127  /*!
128  <b>Notes:</b>
129  - requires an owning molecule
130  */
131  double getValenceContrib(const Atom *at) const;
132  // \overload
133  double getValenceContrib(ATOM_SPTR at) const;
134 
135  //! sets our \c isAromatic flag
136  void setIsAromatic(bool what) { df_isAromatic = what; };
137  //! returns the status of our \c isAromatic flag
138  bool getIsAromatic() const { return df_isAromatic; };
139 
140  //! sets our \c isConjugated flag
141  void setIsConjugated(bool what) { df_isConjugated = what; };
142  //! returns the status of our \c isConjugated flag
143  bool getIsConjugated() const { return df_isConjugated; };
144 
145  //! returns a reference to the ROMol that owns this Bond
146  ROMol &getOwningMol() const { return *dp_mol; };
147  //! sets our owning molecule
148  void setOwningMol(ROMol *other);
149  //! sets our owning molecule
150  void setOwningMol(ROMol &other) { setOwningMol(&other); };
151 
152  //! returns our index within the ROMol
153  /*!
154  <b>Notes:</b>
155  - this makes no sense if we do not have an owning molecule
156 
157  */
158  unsigned int getIdx() const { return d_index; };
159  //! sets our index within the ROMol
160  /*!
161  <b>Notes:</b>
162  - this makes no sense if we do not have an owning molecule
163  - the index should be <tt>< this->getOwningMol()->getNumBonds()</tt>
164  */
165  void setIdx(unsigned int index) { d_index = index; };
166 
167  //! returns the index of our begin Atom
168  /*!
169  <b>Notes:</b>
170  - this makes no sense if we do not have an owning molecule
171  */
172  unsigned int getBeginAtomIdx() const { return d_beginAtomIdx; };
173 
174  //! returns the index of our end Atom
175  /*!
176  <b>Notes:</b>
177  - this makes no sense if we do not have an owning molecule
178  */
179  unsigned int getEndAtomIdx() const { return d_endAtomIdx; };
180 
181  //! given the index of one Atom, returns the index of the other
182  /*!
183  <b>Notes:</b>
184  - this makes no sense if we do not have an owning molecule
185  */
186  unsigned int getOtherAtomIdx(unsigned int thisIdx) const;
187 
188  //! sets the index of our begin Atom
189  /*!
190  <b>Notes:</b>
191  - requires an owning molecule
192  */
193  void setBeginAtomIdx(unsigned int what);
194  //! sets the index of our end Atom
195  /*!
196  <b>Notes:</b>
197  - requires an owning molecule
198  */
199  void setEndAtomIdx(unsigned int what);
200 
201  //! sets our begin Atom
202  /*!
203  <b>Notes:</b>
204  - requires an owning molecule
205  */
206  void setBeginAtom(Atom *at);
207  //! \overload
208  void setBeginAtom(ATOM_SPTR at);
209  //! sets our end Atom
210  /*!
211  <b>Notes:</b>
212  - requires an owning molecule
213  */
214  void setEndAtom(Atom *at);
215  //! \overload
216  void setEndAtom(ATOM_SPTR at);
217 
218  //! returns a pointer to our begin Atom
219  /*!
220  <b>Notes:</b>
221  - requires an owning molecule
222  */
223  Atom *getBeginAtom() const;
224  //! returns a pointer to our end Atom
225  /*!
226  <b>Notes:</b>
227  - requires an owning molecule
228  */
229  Atom *getEndAtom() const;
230  //! returns a pointer to the other Atom
231  /*!
232  <b>Notes:</b>
233  - requires an owning molecule
234  */
235  Atom *getOtherAtom(Atom const *what) const;
236 
237  // ------------------------------------
238  // Please see the note in Atom.h for some explanation
239  // of these methods
240  // ------------------------------------
241 
242  // This method can be used to distinguish query bonds from standard bonds
243  virtual bool hasQuery() const { return false; };
244 
245  // FIX: the const crap here is all mucked up.
246  //! NOT CALLABLE
247  virtual void setQuery(QUERYBOND_QUERY *what);
248  //! NOT CALLABLE
249  virtual QUERYBOND_QUERY *getQuery() const;
250 
251  //! NOT CALLABLE
252  virtual void expandQuery(
253  QUERYBOND_QUERY *what,
255  bool maintainOrder = true);
256 
257  //! returns whether or not we match the argument
258  /*!
259  <b>Notes:</b>
260  - for Bond objects, "match" means that either one of the Bonds
261  has \c bondType Bond::UNSPECIFIED or both Bonds have the
262  same \c bondType.
263  */
264  virtual bool Match(Bond const *what) const;
265  //! \overload
266  virtual bool Match(const Bond::BOND_SPTR what) const;
267 
268  //! sets our direction
269  void setBondDir(BondDir what) { d_dirTag = what; };
270  //! returns our direction
271  BondDir getBondDir() const { return static_cast<BondDir>(d_dirTag); };
272 
273  //! sets our stereo code
274  void setStereo(BondStereo what) { d_stereo = what; };
275  //! returns our stereo code
276  BondStereo getStereo() const { return static_cast<BondStereo>(d_stereo); };
277 
278  //! returns the indices of our stereo atoms
279  const INT_VECT &getStereoAtoms() const {
280  if (!dp_stereoAtoms) {
281  const_cast<Bond *>(this)->dp_stereoAtoms = new INT_VECT();
282  }
283  return *dp_stereoAtoms;
284  };
285  //! \overload
287  if (!dp_stereoAtoms) dp_stereoAtoms = new INT_VECT();
288  return *dp_stereoAtoms;
289  };
290 
291  // ------------------------------------
292  // Local Property Dict functionality
293  // FIX: at some point this stuff should go in a mixin class
294  // ------------------------------------
295  //! returns a list with the names of our \c properties
296  STR_VECT getPropList() const { return dp_props->keys(); }
297 
298  //! sets a \c property value
299  /*!
300  \param key the name under which the \c property should be stored.
301  If a \c property is already stored under this name, it will be
302  replaced.
303  \param val the value to be stored
304  \param computed (optional) allows the \c property to be flagged
305  \c computed.
306  */
307  template <typename T>
308  void setProp(const char *key, T val, bool computed = false) const {
309  // if(!dp_props) dp_props = new Dict();
310  std::string what(key);
311  setProp(what, val, computed);
312  }
313  //! \overload
314  template <typename T>
315  void setProp(const std::string &key, T val, bool computed = false) const {
316  // setProp(key.c_str(),val);
317  if (computed) {
318  STR_VECT compLst;
320  if (std::find(compLst.begin(), compLst.end(), key) == compLst.end()) {
321  compLst.push_back(key);
323  }
324  }
325  dp_props->setVal(key, val);
326  }
327 
328  //! allows retrieval of a particular property value
329  /*!
330 
331  \param key the name under which the \c property should be stored.
332  If a \c property is already stored under this name, it will be
333  replaced.
334  \param res a reference to the storage location for the value.
335 
336  <b>Notes:</b>
337  - if no \c property with name \c key exists, a KeyErrorException will be
338  thrown.
339  - the \c boost::lexical_cast machinery is used to attempt type
340  conversions.
341  If this fails, a \c boost::bad_lexical_cast exception will be thrown.
342 
343  */
344  template <typename T>
345  void getProp(const char *key, T &res) const {
346  PRECONDITION(dp_props, "getProp called on empty property dict");
347  dp_props->getVal(key, res);
348  }
349  //! \overload
350  template <typename T>
351  void getProp(const std::string &key, T &res) const {
352  PRECONDITION(dp_props, "getProp called on empty property dict");
353  dp_props->getVal(key, res);
354  }
355 
356  //! \Overload
357  template <typename T>
358  T getProp(const char *key) const {
359  return dp_props->getVal<T>(key);
360  }
361  //! \overload
362  template <typename T>
363  T getProp(const std::string &key) const {
364  return dp_props->getVal<T>(key);
365  }
366 
367  //! returns whether or not we have a \c property with name \c key
368  //! and assigns the value if we do
369 
370  template <typename T>
371  bool getPropIfPresent(const char *key, T &res) const {
372  return dp_props->getValIfPresent(key, res);
373  }
374  //! \overload
375  template <typename T>
376  bool getPropIfPresent(const std::string &key, T &res) const {
377  return dp_props->getValIfPresent(key, res);
378  }
379 
380  //! returns whether or not we have a \c property with name \c key
381  bool hasProp(const char *key) const {
382  if (!dp_props) return false;
383  return dp_props->hasVal(key);
384  };
385  //! \overload
386  bool hasProp(const std::string &key) const {
387  if (!dp_props) return false;
388  return dp_props->hasVal(key);
389  };
390 
391  //! clears the value of a \c property
392  /*!
393  <b>Notes:</b>
394  - if no \c property with name \c key exists, a KeyErrorException
395  will be thrown.
396  - if the \c property is marked as \c computed, it will also be removed
397  from our list of \c computedProperties
398  */
399  void clearProp(const char *key) const {
400  std::string what(key);
401  clearProp(what);
402  };
403  //! \overload
404  void clearProp(const std::string &key) const {
405  STR_VECT compLst;
407  STR_VECT_I svi = std::find(compLst.begin(), compLst.end(), key);
408  if (svi != compLst.end()) {
409  compLst.erase(svi);
411  }
412  }
413  dp_props->clearVal(key);
414  }
415 
416  //! clears all of our \c computed \c properties
417  void clearComputedProps() const {
418  STR_VECT compLst;
420  BOOST_FOREACH (const std::string &sv, compLst) { dp_props->clearVal(sv); }
421  compLst.clear();
423  }
424  }
425 
426  //! calculates any of our lazy \c properties
427  /*!
428  <b>Notes:</b>
429  - requires an owning molecule
430  */
431  void updatePropertyCache(bool strict = true) { (void)strict; }
432 
433  protected:
434  //! sets our owning molecule
435  // void setOwningMol(ROMol *other);
436  //! sets our owning molecule
437  // void setOwningMol(ROMol &other) {setOwningMol(&other);};
440  boost::uint8_t d_bondType;
441  boost::uint8_t d_dirTag;
442  boost::uint8_t d_stereo;
448 
449  void initBond();
450 };
451 };
452 
453 //! allows Bond objects to be dumped to streams
454 extern std::ostream &operator<<(std::ostream &target, const RDKit::Bond &b);
455 
456 #endif
void initBond()
void setBeginAtomIdx(unsigned int what)
sets the index of our begin Atom
boost::uint8_t d_stereo
Definition: Bond.h:442
void setVal(const std::string &what, T &val)
Sets the value associated with a key.
Definition: Dict.h:169
BondStereo getStereo() const
returns our stereo code
Definition: Bond.h:276
virtual Bond * copy() const
returns a copy
STR_VECT getPropList() const
returns a list with the names of our properties
Definition: Bond.h:296
ROMol & getOwningMol() const
returns a reference to the ROMol that owns this Bond
Definition: Bond.h:146
double getBondTypeAsDouble() const
returns our bondType as a double (e.g. SINGLE->1.0, AROMATIC->1.5, etc.)
std::ostream & operator<<(std::ostream &target, const RDKit::Bond &b)
allows Bond objects to be dumped to streams
Atom * getEndAtom() const
returns a pointer to our end Atom
CompositeQueryType
Definition: QueryObjects.h:35
RWMol is a molecule class that is intended to be edited.
Definition: RWMol.h:30
bool hasVal(const char *what) const
Returns whether or not the dictionary contains a particular key.
Definition: Dict.h:48
virtual bool hasQuery() const
Definition: Bond.h:243
bool hasProp(const std::string &key) const
Definition: Bond.h:386
bool df_isAromatic
sets our owning molecule
Definition: Bond.h:438
void clearComputedProps() const
clears all of our computed properties
Definition: Bond.h:417
Queries::Query< int, Bond const *, true > QUERYBOND_QUERY
Definition: Bond.h:53
boost::shared_ptr< Atom > ATOM_SPTR
Definition: Bond.h:26
ROMol * dp_mol
Definition: Bond.h:445
virtual QUERYBOND_QUERY * getQuery() const
NOT CALLABLE.
void setProp(const char *key, T val, bool computed=false) const
sets a property value
Definition: Bond.h:308
BondStereo
the nature of the bond&#39;s stereochem (for cis/trans)
Definition: Bond.h:95
void getProp(const std::string &key, T &res) const
Definition: Bond.h:351
void clearProp(const char *key) const
clears the value of a property
Definition: Bond.h:399
void setIsConjugated(bool what)
sets our isConjugated flag
Definition: Bond.h:141
BondType
the type of Bond
Definition: Bond.h:56
void setBondType(BondType bT)
sets our bondType
Definition: Bond.h:121
bool getValIfPresent(const std::string &what, T &res) const
Potentially gets the value associated with a particular key returns true on success/false on failure...
Definition: Dict.h:134
ROMol is a molecule class that is intended to have a fixed topology.
Definition: ROMol.h:102
bool getPropIfPresent(const char *key, T &res) const
Definition: Bond.h:371
intentionally unspecified stereochemistry
Definition: Bond.h:91
standard two-electron dative
Definition: Bond.h:76
BondDir getBondDir() const
returns our direction
Definition: Bond.h:271
void getVal(const std::string &what, T &res) const
Gets the value associated with a particular key.
Definition: Dict.h:84
void clearVal(const std::string &what)
Clears the value associated with a particular key, removing the key from the dictionary.
Definition: Dict.h:195
void setIdx(unsigned int index)
sets our index within the ROMol
Definition: Bond.h:165
void setProp(const std::string &key, T val, bool computed=false) const
Definition: Bond.h:315
bool getIsAromatic() const
returns the status of our isAromatic flag
Definition: Bond.h:138
INT_VECT * dp_stereoAtoms
Definition: Bond.h:447
virtual void expandQuery(QUERYBOND_QUERY *what, Queries::CompositeQueryType how=Queries::COMPOSITE_AND, bool maintainOrder=true)
NOT CALLABLE.
bool getIsConjugated() const
returns the status of our isConjugated flag
Definition: Bond.h:143
Atom * getBeginAtom() const
returns a pointer to our begin Atom
std::vector< int > INT_VECT
Definition: types.h:146
double getValenceContrib(const Atom *at) const
returns our contribution to the explicit valence of an Atom
T getProp(const std::string &key) const
Definition: Bond.h:363
void setIsAromatic(bool what)
sets our isAromatic flag
Definition: Bond.h:136
T getProp(const char *key) const
Definition: Bond.h:358
bool hasProp(const char *key) const
returns whether or not we have a property with name key
Definition: Bond.h:381
boost::uint8_t d_bondType
Definition: Bond.h:440
unsigned int getOtherAtomIdx(unsigned int thisIdx) const
given the index of one Atom, returns the index of the other
unsigned int getEndAtomIdx() const
returns the index of our end Atom
Definition: Bond.h:179
Includes a bunch of functionality for handling Atom and Bond queries.
Definition: Atom.h:28
STR_VECT keys() const
Returns the set of keys in the dictionary.
Definition: Dict.h:61
void updatePropertyCache(bool strict=true)
calculates any of our lazy properties
Definition: Bond.h:431
const std::string computedPropName
Definition: types.h:25
INT_VECT & getStereoAtoms()
Definition: Bond.h:286
atomindex_t d_index
Definition: Bond.h:443
void setStereo(BondStereo what)
sets our stereo code
Definition: Bond.h:274
standard two-electron dative
Definition: Bond.h:74
bool df_isConjugated
Definition: Bond.h:439
class for representing a bond
Definition: Bond.h:46
void setOwningMol(ROMol *other)
sets our owning molecule
Zero-order bond (from.
Definition: Bond.h:78
standard two-electron dative
Definition: Bond.h:75
void setBeginAtom(Atom *at)
sets our begin Atom
BondDir
the bond&#39;s direction (for chirality)
Definition: Bond.h:83
atomindex_t d_beginAtomIdx
Definition: Bond.h:444
void setEndAtomIdx(unsigned int what)
sets the index of our end Atom
virtual ~Bond()
Atom * getOtherAtom(Atom const *what) const
returns a pointer to the other Atom
unsigned int getBeginAtomIdx() const
returns the index of our begin Atom
Definition: Bond.h:172
void setOwningMol(ROMol &other)
sets our owning molecule
Definition: Bond.h:150
one-electron dative (e.g. from a C in a Cp ring to a metal)
Definition: Bond.h:73
boost::uint8_t d_dirTag
Definition: Bond.h:441
#define PRECONDITION(expr, mess)
Definition: Invariant.h:103
boost::uint16_t atomindex_t
Definition: details.h:13
no special style
Definition: Bond.h:84
wedged: narrow at begin
Definition: Bond.h:85
a "crossed" double bond
Definition: Bond.h:90
BondType getBondType() const
returns our bondType
Definition: Bond.h:119
Bond & operator=(const Bond &other)
boost::shared_ptr< Bond > BOND_SPTR
Definition: Bond.h:51
Dict * dp_props
Definition: Bond.h:446
Pulls in all the query types.
std::vector< std::string >::iterator STR_VECT_I
Definition: types.h:168
void setEndAtom(Atom *at)
sets our end Atom
const INT_VECT & getStereoAtoms() const
returns the indices of our stereo atoms
Definition: Bond.h:279
virtual bool Match(Bond const *what) const
returns whether or not we match the argument
void setBondDir(BondDir what)
sets our direction
Definition: Bond.h:269
Base class for all queries.
Definition: Query.h:45
void getProp(const char *key, T &res) const
allows retrieval of a particular property value
Definition: Bond.h:345
dashed: narrow at begin
Definition: Bond.h:86
unsigned int getIdx() const
returns our index within the ROMol
Definition: Bond.h:158
The Dict class can be used to store objects of arbitrary type keyed by strings.
Definition: Dict.h:33
void clearProp(const std::string &key) const
Definition: Bond.h:404
The class for representing atoms.
Definition: Atom.h:67
atomindex_t d_endAtomIdx
Definition: Bond.h:444
std::vector< std::string > STR_VECT
Definition: Dict.h:26
virtual void setQuery(QUERYBOND_QUERY *what)
NOT CALLABLE.
bool getPropIfPresent(const std::string &key, T &res) const
Definition: Bond.h:376
for cis/trans
Definition: Bond.h:88