src/api/SamSequenceDictionary.cpp

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