src/api/SamReadGroupDictionary.cpp

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