1 // ***************************************************************************
2 // SamReadGroupDictionary.cpp (c) 2010 Derek Barnett
3 // Marth Lab, Department of Biology, Boston College
4 // ---------------------------------------------------------------------------
5 // Last modified: 16 October 2011 (DB)
6 // ---------------------------------------------------------------------------
7 // Provides methods for operating on a collection of SamReadGroup entries.
8 // ***************************************************************************
10 #include "api/SamReadGroupDictionary.h"
11 using namespace BamTools;
16 /*! \class BamTools::SamReadGroupDictionary
17 \brief Container of SamReadGroup entries.
19 Provides methods for operating on a collection of SamReadGroup entries.
22 /*! \fn SamReadGroupDictionary::SamReadGroupDictionary(void)
25 SamReadGroupDictionary::SamReadGroupDictionary(void) { }
27 /*! \fn SamReadGroupDictionary::SamReadGroupDictionary(const SamReadGroupDictionary& other)
28 \brief copy constructor
30 SamReadGroupDictionary::SamReadGroupDictionary(const SamReadGroupDictionary& other)
31 : m_data(other.m_data)
32 , m_lookupData(other.m_lookupData)
35 /*! \fn SamReadGroupDictionary::~SamReadGroupDictionary(void)
38 SamReadGroupDictionary::~SamReadGroupDictionary(void) { }
40 /*! \fn void SamReadGroupDictionary::Add(const SamReadGroup& readGroup)
41 \brief Appends a read group to the dictionary.
43 Duplicate entries are silently discarded.
45 \param[in] readGroup entry to be added
47 void SamReadGroupDictionary::Add(const SamReadGroup& readGroup) {
48 if ( IsEmpty() || !Contains(readGroup) ) {
49 m_data.push_back(readGroup);
50 m_lookupData[readGroup.ID] = m_data.size() - 1;
54 /*! \fn void SamReadGroupDictionary::Add(const std::string& readGroupId)
55 \brief Appends a read group to the dictionary.
57 This is an overloaded function.
59 \param[in] readGroupId ID of read group to be added
62 void SamReadGroupDictionary::Add(const std::string& readGroupId) {
63 Add( SamReadGroup(readGroupId) );
66 /*! \fn void SamReadGroupDictionary::Add(const SamReadGroupDictionary& readGroups)
67 \brief Appends another read group dictionary to this one.
69 This is an overloaded function.
71 \param[in] readGroups entries to be added
74 void SamReadGroupDictionary::Add(const SamReadGroupDictionary& readGroups) {
75 SamReadGroupConstIterator rgIter = readGroups.ConstBegin();
76 SamReadGroupConstIterator rgEnd = readGroups.ConstEnd();
77 for ( ; rgIter != rgEnd; ++rgIter )
81 /*! \fn void SamReadGroupDictionary::Add(const std::vector<SamReadGroup>& readGroups)
82 \brief Appends multiple read groups to the dictionary.
84 This is an overloaded function.
86 \param[in] readGroups entries to be added
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 )
96 /*! \fn void SamReadGroupDictionary::Add(const std::vector<std::string>& readGroupIds)
97 \brief Appends multiple read groups to the dictionary.
99 This is an overloaded function.
101 \param[in] readGroupIds IDs of read groups to be added
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 )
111 /*! \fn SamReadGroupIterator SamReadGroupDictionary::Begin(void)
112 \return an STL iterator pointing to the first read group
113 \sa ConstBegin(), End()
115 SamReadGroupIterator SamReadGroupDictionary::Begin(void) {
116 return m_data.begin();
119 /*! \fn SamReadGroupConstIterator SamReadGroupDictionary::Begin(void) const
120 \return an STL const_iterator pointing to the first read group
122 This is an overloaded function.
124 \sa ConstBegin(), End()
126 SamReadGroupConstIterator SamReadGroupDictionary::Begin(void) const {
127 return m_data.begin();
130 /*! \fn void SamReadGroupDictionary::Clear(void)
131 \brief Clears all read group entries.
133 void SamReadGroupDictionary::Clear(void) {
135 m_lookupData.clear();
138 /*! \fn SamReadGroupConstIterator SamReadGroupDictionary::ConstBegin(void) const
139 \return an STL const_iterator pointing to the first read group
140 \sa Begin(), ConstEnd()
142 SamReadGroupConstIterator SamReadGroupDictionary::ConstBegin(void) const {
143 return m_data.begin();
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()
150 SamReadGroupConstIterator SamReadGroupDictionary::ConstEnd(void) const {
154 /*! \fn bool SamReadGroupDictionary::Contains(const std::string& readGroupId) const
155 \brief Returns true if dictionary contains read group.
157 \param[in] readGroupId search for read group matching this ID
158 \return \c true if dictionary contains a read group with this ID
160 bool SamReadGroupDictionary::Contains(const std::string& readGroupId) const {
161 return ( m_lookupData.find(readGroupId) != m_lookupData.end() );
164 /*! \fn bool SamReadGroupDictionary::Contains(const SamReadGroup& readGroup) const
165 \brief Returns true if dictionary contains read group (matching on ID).
167 This is an overloaded function.
169 \param[in] readGroup search for this read group
170 \return \c true if dictionary contains read group (matching on ID).
172 bool SamReadGroupDictionary::Contains(const SamReadGroup& readGroup) const {
173 return Contains(readGroup.ID);
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()
180 SamReadGroupIterator SamReadGroupDictionary::End(void) {
184 /*! \fn SamReadGroupConstIterator SamReadGroupDictionary::End(void) const
185 \return an STL const_iterator pointing to the imaginary entry after the last read group
187 This is an overloaded function.
189 \sa Begin(), ConstEnd()
191 SamReadGroupConstIterator SamReadGroupDictionary::End(void) const {
195 /*! \fn bool SamReadGroupDictionary::IsEmpty(void) const
196 \brief Returns \c true if dictionary contains no read groups
199 bool SamReadGroupDictionary::IsEmpty(void) const {
200 return m_data.empty();
203 /*! \fn void SamReadGroupDictionary::Remove(const SamReadGroup& readGroup)
204 \brief Removes read group from dictionary, if found (matching on ID).
206 This is an overloaded function.
208 \param[in] readGroup read group to remove (matches on ID)
210 void SamReadGroupDictionary::Remove(const SamReadGroup& readGroup) {
211 Remove(readGroup.ID);
214 /*! \fn void SamReadGroupDictionary::Remove(const std::string& readGroupId)
215 \brief Removes read group from dictionary, if found.
217 \param[in] readGroupId ID of read group to remove
220 void SamReadGroupDictionary::Remove(const std::string& readGroupId) {
222 // skip if empty dictionary or if ID unknown
223 if ( IsEmpty() || !Contains(readGroupId) )
226 // update 'lookup index' for every entry after @readGroupId
227 const size_t indexToRemove = m_lookupData[readGroupId];
228 const size_t numEntries = m_data.size();
229 for ( size_t i = indexToRemove+1; i < numEntries; ++i ) {
230 const SamReadGroup& rg = m_data.at(i);
231 --m_lookupData[rg.ID];
234 // erase entry from containers
235 m_data.erase( Begin() + indexToRemove );
236 m_lookupData.erase(readGroupId);
239 /*! \fn void SamReadGroupDictionary::Remove(const std::vector<SamReadGroup>& readGroups)
240 \brief Removes multiple read groups from dictionary (matching on ID).
242 This is an overloaded function.
244 \param[in] readGroups read groups to remove
247 void SamReadGroupDictionary::Remove(const std::vector<SamReadGroup>& readGroups) {
248 vector<SamReadGroup>::const_iterator rgIter = readGroups.begin();
249 vector<SamReadGroup>::const_iterator rgEnd = readGroups.end();
250 for ( ; rgIter!= rgEnd; ++rgIter )
254 /*! \fn void SamReadGroupDictionary::Remove(const std::vector<std::string>& readGroupIds)
255 \brief Removes multiple read groups from dictionary.
257 This is an overloaded function.
259 \param[in] readGroupIds IDs of the read groups to remove
262 void SamReadGroupDictionary::Remove(const std::vector<std::string>& readGroupIds) {
263 vector<string>::const_iterator rgIter = readGroupIds.begin();
264 vector<string>::const_iterator rgEnd = readGroupIds.end();
265 for ( ; rgIter!= rgEnd; ++rgIter )
269 /*! \fn int SamReadGroupDictionary::Size(void) const
270 \brief Returns number of read groups in dictionary.
273 int SamReadGroupDictionary::Size(void) const {
274 return m_data.size();
277 /*! \fn SamReadGroup& SamReadGroupDictionary::operator[](const std::string& readGroupId)
278 \brief Retrieves the modifiable SamReadGroup that matches \a readGroupId.
280 \note If the dictionary contains no read group matching this ID, this function inserts
281 a new one with this ID, and returns a reference to it. If you want to avoid this insertion
282 behavior, check the result of Contains() before using this operator.
284 \param[in] readGroupId ID of read group to retrieve
285 \return a modifiable reference to the SamReadGroup associated with the ID
287 SamReadGroup& SamReadGroupDictionary::operator[](const std::string& readGroupId) {
289 if ( !Contains(readGroupId) ) {
290 SamReadGroup rg(readGroupId);
291 m_data.push_back(rg);
292 m_lookupData[readGroupId] = m_data.size() - 1;
295 const size_t index = m_lookupData[readGroupId];
296 return m_data.at(index);