src/api/SamReadGroupDictionary.cpp

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