source: trunk/yat/omic/DNA.h @ 2377

#ifndef theplu_yat_omic_dna
#define theplu_yat_omic_dna

/*
  $Id: DNA.h 2377 2010-12-20 20:49:34Z peter $

  Copyright (C) 2010 Peter Johansson

  This file is part of the yat library, http://dev.thep.lu.se/yat

  The yat library is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 3 of the
  License, or (at your option) any later version.

  The yat library 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
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with yat. If not, see <http://www.gnu.org/licenses/>.
*/

#include <boost/operators.hpp>

#include <iosfwd>
#include <map>
#include <string>
#include <vector>

namespace theplu {
namespace yat {
namespace omic {

  /**
     Class for DNA e.g. A, C, G, or T. Nucleotides can be overloaded
     e.g. 'A' | 'G' == 'R'. Null object (opposite to 'N') is denoted
     by space, ' '.

     <table>
     <tr><td>A</td><td>A</td></tr>
     <tr><td>T</td><td>T</td></tr>
     <tr><td>G</td><td>G</td></tr>
     <tr><td>C</td><td>C</td></tr>
     <tr><td>R</td><td>G or A</td></tr>
     <tr><td>Y</td><td>T or C</td></tr>
     <tr><td>M</td><td>A or C</td></tr>
     <tr><td>K</td><td>G or T</td></tr>
     <tr><td>S</td><td>G or C</td></tr>
     <tr><td>W</td><td>A or T</td></tr>
     <tr><td>H</td><td>A or C or T</td></tr>
     <tr><td>B</td><td>G or T or C</td></tr>
     <tr><td>V</td><td>G or C or A</td></tr>
     <tr><td>D</td><td>G or T or A</td></tr>
     <tr><td>N</td><td>A or C or T or G</td></tr>
     <tr><td>' '</td><td>none</td></tr>
     </table>

     \since New in yat 0.7
   */
  class DNA : boost::operators<DNA>
  {
  public:
    /**
       \brief Default Constructor

       Equivalent to DNA(' ').
     */
    DNA(void);

    /**
       \brief Copy Constructor
     */
    DNA(const DNA&);

    /**
       \param c must be one of the following 16 characters, A, C, G,
       T, M, R, W, S, Y, K, B, D, H, V, N, or ' '.

       \throw std::invalid_argument if \a c is not one of 16 allowed
       characters
     */
    explicit DNA(char c);

    /**
       Calculates complement, i.e., 'A' becomes 'T' and 'G' becomes
       'C' etc. In case of combination the returned DNA will be the
       combination of all complements, i.e., 'R' becomes 'Y.

       \return Complementary base
     */
    DNA complement(void) const;

    /**
       \return DNA as a character
     */
    char get(void) const;

    /**
       Modifies lhs and keeps those bases present on both sides, i.e.,
       if lhs, for example, is 'R' and rhs is 'M' the overlap is 'A'
       so resulting lhs will be an 'A'.

       As DNA is inherits boost::operators<DNA> corresponding
       operator&(const DNA&, const DNA&) is also available.
     */
    DNA& operator&=(const DNA& rhs);

    /**
       Modifies lhs to a combination of bases present on either side.
       If, for example, lhs is 'A' and rhs is 'C', resuting lhs will
       be 'M'.

       As DNA is inherits boost::operators<DNA> corresponding
       operator|(const DNA&, const DNA&) is also available.
     */
    DNA& operator|=(const DNA& rhs);

    /**
       Modifies lhs to a combination of bases that are present on one
       side (not both). If, for example, lhs is 'M' and rhs is 'A',
       resulting lhs will be 'C'.

       As DNA is inherits boost::operators<DNA> corresponding
       operator^(const DNA&, const DNA&) is also available.
     */
    DNA& operator^=(const DNA& rhs);

  private:
    unsigned short code_;
    static std::map<char, unsigned short> char2code_;
    static std::vector<char> code2char_;

    void init(void) const;

    friend bool operator==(const DNA&, const DNA&);
};  

  /**
     \relates DNA

     \return a string of combinations of A, C, G, and T.

     \since New in yat 0.7
   */
  std::string expand(const DNA&);

  /**
     \relates DNA

     \return true if bases are the same, i.e., equivalent to
     lhs.get()==rhs.get()

     As DNA is inherits boost::operators<DNA> corresponding
     operator!=(const DNA&, const DNA&) is also available.

     \since New in yat 0.7
   */
  bool operator==(const DNA& lhs, const DNA& rhs);

  /**
     Outputs the DNA to os. Equivalent to os << dna.get().

     \relates DNA

     \since New in yat 0.7
   */
  std::ostream& operator<<(std::ostream& os, const DNA& dna);
}}}
#endif