src/api/SamReadGroupDictionary.cpp

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