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