src/api/SamReadGroupDictionary.cpp

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