src/api/SamReadGroupDictionary.cpp

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