src/api/SamSequenceDictionary.cpp

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