src/api/SamSequenceDictionary.cpp

   1 // ***************************************************************************
   2 // SamSequenceDictionary.cpp (c) 2010 Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // ---------------------------------------------------------------------------
   5 // Last modified: 12 October 2011 (DB)
   6 // ---------------------------------------------------------------------------
   7 // Provides methods for operating on a collection of SamSequence entries.
   8 // *************************************************************************
   9
  10 #include "api/SamSequenceDictionary.h"
  11 using namespace BamTools;
  12
  13 #include <iostream>
  14 using namespace std;
  15
  16 /*! \class BamTools::SamSequenceDictionary
  17     \brief Container of SamSequence entries.
  18
  19     Provides methods for operating on a collection of SamSequence entries.
  20 */
  21
  22 /*! \typedef BamTools::SamSequenceIterator
  23     \brief mutable iterator for SamSequenceDictionary data
  24
  25     \note This iterator, dereferenced, points to a std::pair<std::string, SamSequence>, NOT
  26     a "plain old" SamSequence. To retrieve the sequence:
  27
  28     \code
  29         SamSequenceIterator iter;
  30         SamSequence& sq = (*iter).second // OR iter->second;
  31     \endcode
  32 */
  33
  34 /*! \typedef BamTools::SamSequenceConstIterator
  35     \brief const iterator for SamSequenceDictionary data
  36
  37     \note This iterator, dereferenced, points to a std::pair<std::string, SamSequence>, NOT
  38     a "plain old" SamSequence. To retrieve the sequence:
  39
  40     \code
  41         SamSequenceConstIterator iter;
  42         const SamSequence& sq = (*iter).second // OR iter->second;
  43     \endcode
  44 */
  45
  46 /*! \fn SamSequenceDictionary::SamSequenceDictionary(void)
  47     \brief constructor
  48 */
  49 SamSequenceDictionary::SamSequenceDictionary(void) { }
  50
  51 /*! \fn SamSequenceDictionary::SamSequenceDictionary(const SamSequenceDictionary& other)
  52     \brief copy constructor
  53 */
  54 SamSequenceDictionary::SamSequenceDictionary(const SamSequenceDictionary& other)
  55     : m_data(other.m_data)
  56 { }
  57
  58 /*! \fn SamSequenceDictionary::~SamSequenceDictionary(void)
  59     \brief destructor
  60 */
  61 SamSequenceDictionary::~SamSequenceDictionary(void) { }
  62
  63 /*! \fn void SamSequenceDictionary::Add(const SamSequence& sequence)
  64     \brief Appends a sequence to the dictionary.
  65
  66     Duplicate entries are silently discarded.
  67
  68     \param[in] sequence entry to be added
  69 */
  70 void SamSequenceDictionary::Add(const SamSequence& sequence) {
  71     if ( IsEmpty() || !Contains(sequence) )
  72         m_data[sequence.Name] = sequence;
  73 }
  74
  75 /*! \fn void SamSequenceDictionary::Add(const std::string& name, const int& length)
  76     \brief Appends a sequence to the dictionary.
  77
  78     This is an overloaded function.
  79
  80     \param[in] name name of sequence entry to be added
  81     \param[in] length length of sequence entry to be added
  82     \sa Add()
  83 */
  84 void SamSequenceDictionary::Add(const std::string& name, const int& length) {
  85     Add( SamSequence(name, length) );
  86 }
  87
  88 /*! \fn void SamSequenceDictionary::Add(const SamSequenceDictionary& sequences)
  89     \brief Appends another sequence dictionary to this one
  90
  91     This is an overloaded function.
  92
  93     \param[in] sequences sequence dictionary to be appended
  94     \sa Add()
  95 */
  96 void SamSequenceDictionary::Add(const SamSequenceDictionary& sequences) {
  97     SamSequenceConstIterator seqIter = sequences.ConstBegin();
  98     SamSequenceConstIterator seqEnd  = sequences.ConstEnd();
  99     for ( ; seqIter != seqEnd; ++seqIter )
 100         Add(seqIter->second);
 101 }
 102
 103 /*! \fn void SamSequenceDictionary::Add(const std::vector<SamSequence>& sequences)
 104     \brief Appends multiple sequences to the dictionary.
 105
 106     This is an overloaded function.
 107
 108     \param[in] sequences entries to be added
 109     \sa Add()
 110 */
 111 void SamSequenceDictionary::Add(const std::vector<SamSequence>& sequences) {
 112     vector<SamSequence>::const_iterator seqIter = sequences.begin();
 113     vector<SamSequence>::const_iterator seqEnd  = sequences.end();
 114     for ( ; seqIter!= seqEnd; ++seqIter )
 115         Add(*seqIter);
 116 }
 117
 118 /*! \fn void SamSequenceDictionary::Add(const std::map<std::string, int>& sequenceMap)
 119     \brief Appends multiple sequences to the dictionary.
 120
 121     This is an overloaded function.
 122
 123     \param[in] sequenceMap map of sequence entries (name => length) to be added
 124     \sa Add()
 125 */
 126 void SamSequenceDictionary::Add(const std::map<std::string, int>& sequenceMap) {
 127     map<string, int>::const_iterator seqIter = sequenceMap.begin();
 128     map<string, int>::const_iterator seqEnd  = sequenceMap.end();
 129     for ( ; seqIter != seqEnd; ++seqIter ) {
 130         const string& name = (*seqIter).first;
 131         const int& length = (*seqIter).second;
 132         Add( SamSequence(name, length) );
 133     }
 134 }
 135
 136 /*! \fn SamSequenceIterator SamSequenceDictionary::Begin(void)
 137     \return an STL iterator pointing to the first sequence
 138     \sa ConstBegin(), End()
 139 */
 140 SamSequenceIterator SamSequenceDictionary::Begin(void) {
 141     return m_data.begin();
 142 }
 143
 144 /*! \fn SamSequenceConstIterator SamSequenceDictionary::Begin(void) const
 145     \return an STL const_iterator pointing to the first sequence
 146
 147     This is an overloaded function.
 148
 149     \sa ConstBegin(), End()
 150 */
 151 SamSequenceConstIterator SamSequenceDictionary::Begin(void) const {
 152     return m_data.begin();
 153 }
 154
 155 /*! \fn void SamSequenceDictionary::Clear(void)
 156     \brief Clears all sequence entries.
 157 */
 158 void SamSequenceDictionary::Clear(void) {
 159     m_data.clear();
 160 }
 161
 162 /*! \fn SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const
 163     \return an STL const_iterator pointing to the first sequence
 164     \sa Begin(), ConstEnd()
 165 */
 166 SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const {
 167     return m_data.begin();
 168 }
 169
 170 /*! \fn SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const
 171     \return an STL const_iterator pointing to the imaginary entry after the last sequence
 172     \sa End(), ConstBegin()
 173 */
 174 SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const {
 175     return m_data.end();
 176 }
 177
 178 /*! \fn bool SamSequenceDictionary::Contains(const std::string& sequenceName) const
 179     \brief Returns true if dictionary contains sequence.
 180
 181     \param[in] sequenceName search for sequence matching this name
 182     \return \c true if dictionary contains a sequence with this name
 183 */
 184 bool SamSequenceDictionary::Contains(const std::string& sequenceName) const {
 185     return ( m_data.find(sequenceName) != m_data.end() );
 186 }
 187
 188 /*! \fn bool SamSequenceDictionary::Contains(const SamSequence& sequence) const
 189     \brief Returns true if dictionary contains sequence (matches on name).
 190
 191     This is an overloaded function.
 192
 193     \param[in] sequence search for this sequence
 194     \return \c true if dictionary contains sequence (matching on name)
 195 */
 196 bool SamSequenceDictionary::Contains(const SamSequence& sequence) const {
 197     return Contains(sequence.Name);
 198 }
 199
 200 /*! \fn SamSequenceIterator SamSequenceDictionary::End(void)
 201     \return an STL iterator pointing to the imaginary entry after the last sequence
 202     \sa Begin(), ConstEnd()
 203 */
 204 SamSequenceIterator SamSequenceDictionary::End(void) {
 205     return m_data.end();
 206 }
 207
 208 /*! \fn SamSequenceConstIterator SamSequenceDictionary::End(void) const
 209     \return an STL const_iterator pointing to the imaginary entry after the last sequence
 210
 211     This is an overloaded function.
 212
 213     \sa Begin(), ConstEnd()
 214 */
 215 SamSequenceConstIterator SamSequenceDictionary::End(void) const {
 216     return m_data.end();
 217 }
 218
 219 /*! \fn bool SamSequenceDictionary::IsEmpty(void) const
 220     \brief Returns \c true if dictionary contains no sequences
 221     \sa Size()
 222 */
 223 bool SamSequenceDictionary::IsEmpty(void) const {
 224     return m_data.empty();
 225 }
 226
 227 /*! \fn void SamSequenceDictionary::Remove(const SamSequence& sequence)
 228     \brief Removes sequence from dictionary, if found (matches on name).
 229
 230     This is an overloaded function.
 231
 232     \param[in] sequence SamSequence to remove (matching on name)
 233 */
 234 void SamSequenceDictionary::Remove(const SamSequence& sequence) {
 235     Remove(sequence.Name);
 236 }
 237
 238 /*! \fn void SamSequenceDictionary::Remove(const std::string& sequenceName)
 239     \brief Removes sequence from dictionary, if found.
 240
 241     \param[in] sequenceName name of sequence to remove
 242     \sa Remove()
 243 */
 244 void SamSequenceDictionary::Remove(const std::string& sequenceName) {
 245     m_data.erase(sequenceName);
 246 }
 247
 248 /*! \fn void SamSequenceDictionary::Remove(const std::vector<SamSequence>& sequences)
 249     \brief Removes multiple sequences from dictionary.
 250
 251     This is an overloaded function.
 252
 253     \param[in] sequences sequences to remove
 254     \sa Remove()
 255 */
 256 void SamSequenceDictionary::Remove(const std::vector<SamSequence>& sequences) {
 257     vector<SamSequence>::const_iterator rgIter = sequences.begin();
 258     vector<SamSequence>::const_iterator rgEnd  = sequences.end();
 259     for ( ; rgIter!= rgEnd; ++rgIter )
 260         Remove(*rgIter);
 261 }
 262
 263 /*! \fn void SamSequenceDictionary::Remove(const std::vector<std::string>& sequenceNames)
 264     \brief Removes multiple sequences from dictionary.
 265
 266     This is an overloaded function.
 267
 268     \param[in] sequenceNames names of the sequences to remove
 269     \sa Remove()
 270 */
 271 void SamSequenceDictionary::Remove(const std::vector<std::string>& sequenceNames) {
 272     vector<string>::const_iterator rgIter = sequenceNames.begin();
 273     vector<string>::const_iterator rgEnd  = sequenceNames.end();
 274     for ( ; rgIter!= rgEnd; ++rgIter )
 275         Remove(*rgIter);
 276 }
 277
 278 /*! \fn int SamSequenceDictionary::Size(void) const
 279     \brief Returns number of sequences in dictionary.
 280     \sa IsEmpty()
 281 */
 282 int SamSequenceDictionary::Size(void) const {
 283     return m_data.size();
 284 }
 285
 286 /*! \fn SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName)
 287     \brief Retrieves the modifiable SamSequence that matches \a sequenceName.
 288
 289     \note If the dictionary contains no sequence matching this name, this function inserts
 290     a new one with this name (length:0), and returns a reference to it. If you want to avoid
 291     this insertion behavior, check the result of Contains() before using this operator.
 292
 293     \param[in] sequenceName name of sequence to retrieve
 294     \return a modifiable reference to the SamSequence associated with the name
 295 */
 296 SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName) {
 297     if ( !Contains(sequenceName) )
 298         m_data[sequenceName] = SamSequence(sequenceName, 0);
 299     return m_data[sequenceName];
 300 }