src/api/SamReadGroupDictionary.cpp

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