1 // ***************************************************************************
2 // SamSequenceDictionary.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 SamSequence entries.
8 // *************************************************************************
10 #include <api/SamSequenceDictionary.h>
11 using namespace BamTools;
16 /*! \class BamTools::SamSequenceDictionary
17 \brief Container of SamSequence entries.
19 Provides methods for operating on a collection of SamSequence entries.
22 /*! \fn SamSequenceDictionary::SamSequenceDictionary(void)
25 SamSequenceDictionary::SamSequenceDictionary(void) { }
27 /*! \fn SamSequenceDictionary::SamSequenceDictionary(const SamSequenceDictionary& other)
28 \brief copy constructor
30 SamSequenceDictionary::SamSequenceDictionary(const SamSequenceDictionary& other)
31 : m_data(other.m_data)
34 /*! \fn SamSequenceDictionary::~SamSequenceDictionary(void)
37 SamSequenceDictionary::~SamSequenceDictionary(void) { }
39 /*! \fn void SamSequenceDictionary::Add(const SamSequence& sequence)
40 \brief Adds a sequence to the dictionary.
42 Duplicate entries are silently discarded.
44 \param sequence entry to be added
46 void SamSequenceDictionary::Add(const SamSequence& sequence) {
48 // TODO: report error on attempted duplicate?
50 if ( IsEmpty() || !Contains(sequence) )
51 m_data.push_back(sequence);
54 /*! \fn void SamSequenceDictionary::Add(const std::string& name, const int& length)
55 \brief Adds a sequence to the dictionary.
57 This is an overloaded function.
59 \param name name of sequence entry to be added
60 \param length length of sequence entry to be added
63 void SamSequenceDictionary::Add(const std::string& name, const int& length) {
64 Add( SamSequence(name, length) );
67 void SamSequenceDictionary::Add(const SamSequenceDictionary& sequences) {
68 SamSequenceConstIterator seqIter = sequences.ConstBegin();
69 SamSequenceConstIterator seqEnd = sequences.ConstEnd();
70 for ( ; seqIter != seqEnd; ++seqIter )
74 /*! \fn void SamSequenceDictionary::Add(const std::vector<SamSequence>& sequences)
75 \brief Adds multiple sequences to the dictionary.
77 This is an overloaded function.
79 \param sequences entries to be added
82 void SamSequenceDictionary::Add(const std::vector<SamSequence>& sequences) {
83 vector<SamSequence>::const_iterator seqIter = sequences.begin();
84 vector<SamSequence>::const_iterator seqEnd = sequences.end();
85 for ( ; seqIter!= seqEnd; ++seqIter )
89 /*! \fn void SamSequenceDictionary::Add(const std::map<std::string, int>& sequenceMap)
90 \brief Adds multiple sequences to the dictionary.
92 This is an overloaded function.
94 \param sequenceMap map of sequence entries (name => length) to be added
97 void SamSequenceDictionary::Add(const std::map<std::string, int>& sequenceMap) {
98 map<string, int>::const_iterator seqIter = sequenceMap.begin();
99 map<string, int>::const_iterator seqEnd = sequenceMap.end();
100 for ( ; seqIter != seqEnd; ++seqIter ) {
101 const string& name = (*seqIter).first;
102 const int& length = (*seqIter).second;
103 Add( SamSequence(name, length) );
107 /*! \fn SamSequenceIterator SamSequenceDictionary::Begin(void)
108 \return an STL iterator pointing to the first sequence
109 \sa ConstBegin(), End()
111 SamSequenceIterator SamSequenceDictionary::Begin(void) {
112 return m_data.begin();
115 /*! \fn SamSequenceConstIterator SamSequenceDictionary::Begin(void) const
116 \return an STL const_iterator pointing to the first sequence
118 This is an overloaded function.
120 \sa ConstBegin(), End()
122 SamSequenceConstIterator SamSequenceDictionary::Begin(void) const {
123 return m_data.begin();
126 /*! \fn void SamSequenceDictionary::Clear(void)
127 \brief Clears all sequence entries.
129 void SamSequenceDictionary::Clear(void) {
133 /*! \fn SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const
134 \return an STL const_iterator pointing to the first sequence
135 \sa Begin(), ConstEnd()
137 SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const {
138 return m_data.begin();
141 /*! \fn SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const
142 \return an STL const_iterator pointing to the imaginary entry after the last sequence
143 \sa End(), ConstBegin()
145 SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const {
149 /*! \fn bool SamSequenceDictionary::Contains(const std::string& sequenceName) const
150 \brief Returns true if dictionary contains sequence.
151 \param sequenceName search for sequence matching this name
152 \return \c true if dictionary contains a sequence with this name
154 bool SamSequenceDictionary::Contains(const std::string& sequenceName) const {
155 return ( IndexOf(sequenceName) != (int)m_data.size() );
158 /*! \fn bool SamSequenceDictionary::Contains(const SamSequence& sequence) const
159 \brief Returns true if dictionary contains sequence (matches on name).
161 This is an overloaded function.
163 \param sequence search for this sequence
164 \return \c true if dictionary contains sequence (matching on name)
166 bool SamSequenceDictionary::Contains(const SamSequence& sequence) const {
167 return ( IndexOf(sequence.Name) != (int)m_data.size() );
170 /*! \fn SamSequenceIterator SamSequenceDictionary::End(void)
171 \return an STL iterator pointing to the imaginary entry after the last sequence
172 \sa Begin(), ConstEnd()
174 SamSequenceIterator SamSequenceDictionary::End(void) {
178 /*! \fn SamSequenceConstIterator SamSequenceDictionary::End(void) const
179 \return an STL const_iterator pointing to the imaginary entry after the last sequence
181 This is an overloaded function.
183 \sa Begin(), ConstEnd()
185 SamSequenceConstIterator SamSequenceDictionary::End(void) const {
189 /*! \fn int SamSequenceDictionary::IndexOf(const std::string& name) const
191 \return index of sequence if found (matching on name). Otherwise, returns vector::size() (invalid index).
193 int SamSequenceDictionary::IndexOf(const std::string& name) const {
194 SamSequenceConstIterator begin = ConstBegin();
195 SamSequenceConstIterator iter = begin;
196 SamSequenceConstIterator end = ConstEnd();
197 for ( ; iter != end; ++iter ) {
198 const SamSequence& currentSeq = (*iter);
199 if ( currentSeq.Name == name )
202 return distance( begin, iter );
205 /*! \fn bool SamSequenceDictionary::IsEmpty(void) const
206 \brief Returns \c true if dictionary contains no sequences
209 bool SamSequenceDictionary::IsEmpty(void) const {
210 return m_data.empty();
213 /*! \fn void SamSequenceDictionary::Remove(const SamSequence& sequence)
214 \brief Removes sequence from dictionary, if found (matches on name).
216 This is an overloaded function.
218 \param sequence SamSequence to remove (matching on name)
220 void SamSequenceDictionary::Remove(const SamSequence& sequence) {
221 Remove( sequence.Name );
224 /*! \fn void SamSequenceDictionary::Remove(const std::string& sequenceName)
225 \brief Removes sequence from dictionary, if found.
227 \param sequenceName name of sequence to remove
230 void SamSequenceDictionary::Remove(const std::string& sequenceName) {
231 if ( Contains(sequenceName) )
232 m_data.erase( m_data.begin() + IndexOf(sequenceName) );
235 /*! \fn void SamSequenceDictionary::Remove(const std::vector<SamSequence>& sequences)
236 \brief Removes multiple sequences from dictionary.
238 This is an overloaded function.
240 \param sequences sequences to remove
243 void SamSequenceDictionary::Remove(const std::vector<SamSequence>& sequences) {
244 vector<SamSequence>::const_iterator rgIter = sequences.begin();
245 vector<SamSequence>::const_iterator rgEnd = sequences.end();
246 for ( ; rgIter!= rgEnd; ++rgIter )
250 /*! \fn void SamSequenceDictionary::Remove(const std::vector<std::string>& sequenceNames)
251 \brief Removes multiple sequences from dictionary.
253 This is an overloaded function.
255 \param sequenceNames names of the sequences to remove
258 void SamSequenceDictionary::Remove(const std::vector<std::string>& sequenceNames) {
259 vector<string>::const_iterator rgIter = sequenceNames.begin();
260 vector<string>::const_iterator rgEnd = sequenceNames.end();
261 for ( ; rgIter!= rgEnd; ++rgIter )
265 /*! \fn int SamSequenceDictionary::Size(void) const
266 \brief Returns number of sequences in dictionary.
269 int SamSequenceDictionary::Size(void) const {
270 return m_data.size();
273 /*! \fn SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName)
274 \brief Retrieves the modifiable SamSequence that matches \a sequenceName.
276 NOTE - If the dictionary contains no sequence matching this name, this function inserts
277 a new one with this name (length:0), and returns a reference to it.
279 If you want to avoid this insertion behavior, check the result of Contains() before
282 \param sequenceName name of sequence to retrieve
283 \return a modifiable reference to the SamSequence associated with the name
285 SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName) {
287 // look up sequence ID
288 int index = IndexOf(sequenceName);
290 // if found, return sequence at index
291 if ( index != (int)m_data.size() )
292 return m_data[index];
294 // otherwise, append new sequence and return reference
296 m_data.push_back( SamSequence(sequenceName, 0) );
297 return m_data.back();