1 // ***************************************************************************
2 // SamSequenceDictionary.cpp (c) 2010 Derek Barnett
3 // Marth Lab, Department of Biology, Boston College
4 // All rights reserved.
5 // ---------------------------------------------------------------------------
6 // Last modified: 20 March 2011 (DB)
7 // ---------------------------------------------------------------------------
8 // Provides methods for operating on a collection of SamSequence entries.
9 // *************************************************************************
11 #include <api/SamSequenceDictionary.h>
12 using namespace BamTools;
17 /*! \class BamTools::SamSequenceDictionary
18 \brief Container of SamSequence entries.
20 Provides methods for operating on a collection of SamSequence entries.
23 /*! \fn SamSequenceDictionary::SamSequenceDictionary(void)
26 SamSequenceDictionary::SamSequenceDictionary(void) { }
28 /*! \fn SamSequenceDictionary::SamSequenceDictionary(const SamSequenceDictionary& other)
29 \brief copy constructor
31 SamSequenceDictionary::SamSequenceDictionary(const SamSequenceDictionary& other)
32 : m_data(other.m_data)
35 /*! \fn SamSequenceDictionary::~SamSequenceDictionary(void)
38 SamSequenceDictionary::~SamSequenceDictionary(void) { }
40 /*! \fn void SamSequenceDictionary::Add(const SamSequence& sequence)
41 \brief Adds a sequence to the dictionary.
43 Duplicate entries are discarded.
45 \param sequence entry to be added
47 void SamSequenceDictionary::Add(const SamSequence& sequence) {
48 if ( IsEmpty() || !Contains(sequence) )
49 m_data.push_back(sequence);
52 /*! \fn void SamSequenceDictionary::Add(const std::string& name, const int& length)
53 \brief Adds a sequence to the dictionary.
55 This is an overloaded function.
57 \param name name of sequence entry to be added
58 \param length length of sequence entry to be added
61 void SamSequenceDictionary::Add(const std::string& name, const int& length) {
62 Add( SamSequence(name, length) );
65 /*! \fn void SamSequenceDictionary::Add(const std::vector<SamSequence>& sequences)
66 \brief Adds multiple sequences to the dictionary.
68 This is an overloaded function.
70 \param sequences entries to be added
73 void SamSequenceDictionary::Add(const std::vector<SamSequence>& sequences) {
74 vector<SamSequence>::const_iterator seqIter = sequences.begin();
75 vector<SamSequence>::const_iterator seqEnd = sequences.end();
76 for ( ; seqIter!= seqEnd; ++seqIter )
80 /*! \fn void SamSequenceDictionary::Add(const std::map<std::string, int>& sequenceMap)
81 \brief Adds multiple sequences to the dictionary.
83 This is an overloaded function.
85 \param sequenceMap map of sequence entries (name => length) to be added
88 void SamSequenceDictionary::Add(const std::map<std::string, int>& sequenceMap) {
89 map<string, int>::const_iterator seqIter = sequenceMap.begin();
90 map<string, int>::const_iterator seqEnd = sequenceMap.end();
91 for ( ; seqIter != seqEnd; ++seqIter ) {
92 const string& name = (*seqIter).first;
93 const int& length = (*seqIter).second;
94 Add( SamSequence(name, length) );
98 /*! \fn SamSequenceIterator SamSequenceDictionary::Begin(void)
99 \return an STL iterator pointing to the first sequence
100 \sa ConstBegin(), End()
102 SamSequenceIterator SamSequenceDictionary::Begin(void) {
103 return m_data.begin();
106 /*! \fn SamSequenceConstIterator SamSequenceDictionary::Begin(void) const
108 This is an overloaded function.
110 \return a const STL iterator pointing to the first sequence
111 \sa ConstBegin(), End()
113 SamSequenceConstIterator SamSequenceDictionary::Begin(void) const {
114 return m_data.begin();
117 /*! \fn void SamSequenceDictionary::Clear(void)
118 \brief Clears all sequence entries.
120 void SamSequenceDictionary::Clear(void) {
124 /*! \fn SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const
125 \return a const STL iterator pointing to the first sequence
126 \sa Begin(), ConstEnd()
128 SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const {
129 return m_data.begin();
132 /*! \fn SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const
133 \return a const STL iterator pointing to the imaginary entry after the last sequence
134 \sa End(), ConstBegin()
136 SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const {
140 /*! \fn bool SamSequenceDictionary::Contains(const std::string& sequenceName) const
141 \brief Returns true if dictionary contains sequence.
142 \param sequenceName search for sequence matching this name
143 \return \c true if dictionary contains a sequence with this name
145 bool SamSequenceDictionary::Contains(const std::string& sequenceName) const {
146 return ( IndexOf(sequenceName) != (int)m_data.size() );
149 /*! \fn bool SamSequenceDictionary::Contains(const SamSequence& sequence) const
150 \brief Returns true if dictionary contains sequence.
151 \param sequence search for this sequence
152 \return \c true if dictionary contains sequence
154 bool SamSequenceDictionary::Contains(const SamSequence& sequence) const {
155 return ( IndexOf(sequence) != (int)m_data.size() );
158 /*! \fn SamSequenceIterator SamSequenceDictionary::End(void)
159 \return an STL iterator pointing to the imaginary entry after the last sequence
160 \sa Begin(), ConstEnd()
162 SamSequenceIterator SamSequenceDictionary::End(void) {
166 /*! \fn SamSequenceConstIterator SamSequenceDictionary::End(void) const
168 This is an overloaded function.
170 \return a const STL iterator pointing to the imaginary entry after the last sequence
171 \sa Begin(), ConstEnd()
173 SamSequenceConstIterator SamSequenceDictionary::End(void) const {
177 /*! \fn int SamSequenceDictionary::IndexOf(const SamSequence& sequence) const
180 Uses operator==(SamSequence, SamSequence)
182 \return index of sequence if found. Otherwise, returns vector::size() (invalid index).
184 int SamSequenceDictionary::IndexOf(const SamSequence& sequence) const {
185 SamSequenceConstIterator begin = ConstBegin();
186 SamSequenceConstIterator iter = begin;
187 SamSequenceConstIterator end = ConstEnd();
188 for ( ; iter != end; ++iter ) {
189 const SamSequence& currentSeq = (*iter);
190 if ( currentSeq == sequence )
193 return distance( begin, iter );
196 /*! \fn int SamSequenceDictionary::IndexOf(const std::string& name) const
199 Use comparison of SamSequence::Name to \a name
201 \return index of sequence if found. Otherwise, returns vector::size() (invalid index).
203 int SamSequenceDictionary::IndexOf(const std::string& name) const {
204 SamSequenceConstIterator begin = ConstBegin();
205 SamSequenceConstIterator iter = begin;
206 SamSequenceConstIterator end = ConstEnd();
207 for ( ; iter != end; ++iter ) {
208 const SamSequence& currentSeq = (*iter);
209 if ( currentSeq.Name == name )
212 return distance( begin, iter );
215 /*! \fn bool SamSequenceDictionary::IsEmpty(void) const
216 \brief Returns \c true if dictionary contains no sequences
219 bool SamSequenceDictionary::IsEmpty(void) const {
220 return m_data.empty();
223 /*! \fn void SamSequenceDictionary::Remove(const SamSequence& sequence)
224 \brief Removes sequence from dictionary, if found.
225 \param sequence sequence to remove
227 void SamSequenceDictionary::Remove(const SamSequence& sequence) {
228 if ( Contains(sequence) )
229 m_data.erase( m_data.begin() + IndexOf(sequence) );
232 /*! \fn void SamSequenceDictionary::Remove(const std::string& sequenceName)
233 \brief Removes sequence from dictionary, if found.
235 \param sequenceName name of sequence to remove
238 void SamSequenceDictionary::Remove(const std::string& sequenceName) {
239 if ( Contains(sequenceName) )
240 m_data.erase( m_data.begin() + IndexOf(sequenceName) );
243 /*! \fn void SamSequenceDictionary::Remove(const std::vector<SamSequence>& sequences)
244 \brief Removes multiple sequences from dictionary.
246 This is an overloaded function.
248 \param sequences sequences to remove
251 void SamSequenceDictionary::Remove(const std::vector<SamSequence>& sequences) {
252 vector<SamSequence>::const_iterator rgIter = sequences.begin();
253 vector<SamSequence>::const_iterator rgEnd = sequences.end();
254 for ( ; rgIter!= rgEnd; ++rgIter )
258 /*! \fn void SamSequenceDictionary::Remove(const std::vector<std::string>& sequenceNames)
259 \brief Removes multiple sequences from dictionary.
261 This is an overloaded function.
263 \param sequenceNames names of the sequences to remove
266 void SamSequenceDictionary::Remove(const std::vector<std::string>& sequenceNames) {
267 vector<string>::const_iterator rgIter = sequenceNames.begin();
268 vector<string>::const_iterator rgEnd = sequenceNames.end();
269 for ( ; rgIter!= rgEnd; ++rgIter )
273 /*! \fn int SamSequenceDictionary::Size(void) const
274 \brief Returns number of sequences in dictionary.
277 int SamSequenceDictionary::Size(void) const {
278 return m_data.size();
281 /*! \fn SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName)
282 \brief Retrieves the modifiable SamSequence that matches \a sequenceName.
284 NOTE - If the dictionary contains no sequence matching this name, this function inserts
285 a new one with this name, and returns a reference to it.
287 If you want to avoid this insertion behavior, check the result of Contains() before
290 \param sequenceName name of sequence to retrieve
291 \return a modifiable reference to the SamSequence associated with the name
293 SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName) {
295 // look up sequence ID
296 int index = IndexOf(sequenceName);
298 // if found, return sequence at index
299 if ( index != (int)m_data.size() )
300 return m_data[index];
302 // otherwise, append new sequence and return reference
304 m_data.push_back( SamSequence(sequenceName, 0) );
305 return m_data.back();