X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=src%2Fapi%2FSamSequenceDictionary.cpp;h=61eae2529fb8ea6a02d7f01e1e32f492f3d5d3ee;hb=25a2a1f6598b6452455da96c28a7f58fd9e7ed2d;hp=c023a39d21e313970c5d5113215b0db3eb2fca1f;hpb=ff5f2ec7c437660185a406d01739f42534105412;p=bamtools.git diff --git a/src/api/SamSequenceDictionary.cpp b/src/api/SamSequenceDictionary.cpp index c023a39..61eae25 100644 --- a/src/api/SamSequenceDictionary.cpp +++ b/src/api/SamSequenceDictionary.cpp @@ -1,144 +1,291 @@ +// *************************************************************************** +// SamSequenceDictionary.cpp (c) 2010 Derek Barnett +// Marth Lab, Department of Biology, Boston College +// --------------------------------------------------------------------------- +// Last modified: 10 October 2011 (DB) +// --------------------------------------------------------------------------- +// Provides methods for operating on a collection of SamSequence entries. +// ************************************************************************* + #include using namespace BamTools; #include using namespace std; -// ctor +/*! \class BamTools::SamSequenceDictionary + \brief Container of SamSequence entries. + + Provides methods for operating on a collection of SamSequence entries. +*/ + +/*! \fn SamSequenceDictionary::SamSequenceDictionary(void) + \brief constructor +*/ SamSequenceDictionary::SamSequenceDictionary(void) { } -// dtor -SamSequenceDictionary::~SamSequenceDictionary(void) { - m_data.clear(); -} +/*! \fn SamSequenceDictionary::SamSequenceDictionary(const SamSequenceDictionary& other) + \brief copy constructor +*/ +SamSequenceDictionary::SamSequenceDictionary(const SamSequenceDictionary& other) + : m_data(other.m_data) +{ } + +/*! \fn SamSequenceDictionary::~SamSequenceDictionary(void) + \brief destructor +*/ +SamSequenceDictionary::~SamSequenceDictionary(void) { } -// adds sequence if not already in container +/*! \fn void SamSequenceDictionary::Add(const SamSequence& sequence) + \brief Appends a sequence to the dictionary. + + Duplicate entries are silently discarded. + + \param[in] sequence entry to be added +*/ void SamSequenceDictionary::Add(const SamSequence& sequence) { if ( IsEmpty() || !Contains(sequence) ) m_data.push_back(sequence); } -// overload to support std::string -void SamSequenceDictionary::Add(const string& sequenceName) { - Add( SamSequence(sequenceName) ); +/*! \fn void SamSequenceDictionary::Add(const std::string& name, const int& length) + \brief Appends a sequence to the dictionary. + + This is an overloaded function. + + \param[in] name name of sequence entry to be added + \param[in] length length of sequence entry to be added + \sa Add() +*/ +void SamSequenceDictionary::Add(const std::string& name, const int& length) { + Add( SamSequence(name, length) ); } -// add multiple sequences -void SamSequenceDictionary::Add(const vector& sequences) { - vector::const_iterator rgIter = sequences.begin(); - vector::const_iterator rgEnd = sequences.end(); - for ( ; rgIter!= rgEnd; ++rgIter ) - Add(*rgIter); +/*! \fn void SamSequenceDictionary::Add(const SamSequenceDictionary& sequences) + \brief Appends another sequence dictionary to this one + + This is an overloaded function. + + \param[in] sequences sequence dictionary to be appended + \sa Add() +*/ +void SamSequenceDictionary::Add(const SamSequenceDictionary& sequences) { + SamSequenceConstIterator seqIter = sequences.ConstBegin(); + SamSequenceConstIterator seqEnd = sequences.ConstEnd(); + for ( ; seqIter != seqEnd; ++seqIter ) + Add(*seqIter); } -// overload to support std::string -void SamSequenceDictionary::Add(const vector& sequenceNames) { - vector::const_iterator rgIter = sequenceNames.begin(); - vector::const_iterator rgEnd = sequenceNames.end(); - for ( ; rgIter!= rgEnd; ++rgIter ) - Add(*rgIter); +/*! \fn void SamSequenceDictionary::Add(const std::vector& sequences) + \brief Appends multiple sequences to the dictionary. + + This is an overloaded function. + + \param[in] sequences entries to be added + \sa Add() +*/ +void SamSequenceDictionary::Add(const std::vector& sequences) { + vector::const_iterator seqIter = sequences.begin(); + vector::const_iterator seqEnd = sequences.end(); + for ( ; seqIter!= seqEnd; ++seqIter ) + Add(*seqIter); } -// returns iterator to container begin +/*! \fn void SamSequenceDictionary::Add(const std::map& sequenceMap) + \brief Appends multiple sequences to the dictionary. + + This is an overloaded function. + + \param[in] sequenceMap map of sequence entries (name => length) to be added + \sa Add() +*/ +void SamSequenceDictionary::Add(const std::map& sequenceMap) { + map::const_iterator seqIter = sequenceMap.begin(); + map::const_iterator seqEnd = sequenceMap.end(); + for ( ; seqIter != seqEnd; ++seqIter ) { + const string& name = (*seqIter).first; + const int& length = (*seqIter).second; + Add( SamSequence(name, length) ); + } +} + +/*! \fn SamSequenceIterator SamSequenceDictionary::Begin(void) + \return an STL iterator pointing to the first sequence + \sa ConstBegin(), End() +*/ SamSequenceIterator SamSequenceDictionary::Begin(void) { return m_data.begin(); } -// returns const_iterator to container begin +/*! \fn SamSequenceConstIterator SamSequenceDictionary::Begin(void) const + \return an STL const_iterator pointing to the first sequence + + This is an overloaded function. + + \sa ConstBegin(), End() +*/ SamSequenceConstIterator SamSequenceDictionary::Begin(void) const { return m_data.begin(); } -// clear sequence container +/*! \fn void SamSequenceDictionary::Clear(void) + \brief Clears all sequence entries. +*/ void SamSequenceDictionary::Clear(void) { m_data.clear(); } -// explicit request for const_iterator to container begin +/*! \fn SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const + \return an STL const_iterator pointing to the first sequence + \sa Begin(), ConstEnd() +*/ SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const { return m_data.begin(); } -// explicit request for const_iterator to container end +/*! \fn SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const + \return an STL const_iterator pointing to the imaginary entry after the last sequence + \sa End(), ConstBegin() +*/ SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const { return m_data.end(); } -// returns true if container contains a sequence with this ID tag -bool SamSequenceDictionary::Contains(const string& sequenceName) const { +/*! \fn bool SamSequenceDictionary::Contains(const std::string& sequenceName) const + \brief Returns true if dictionary contains sequence. + + \param[in] sequenceName search for sequence matching this name + \return \c true if dictionary contains a sequence with this name +*/ +bool SamSequenceDictionary::Contains(const std::string& sequenceName) const { return ( IndexOf(sequenceName) != (int)m_data.size() ); } -bool SamSequenceDictionary::Contains(const SamSequence& seq) const { - return ( IndexOf(seq) != (int)m_data.size() ); +/*! \fn bool SamSequenceDictionary::Contains(const SamSequence& sequence) const + \brief Returns true if dictionary contains sequence (matches on name). + + This is an overloaded function. + + \param[in] sequence search for this sequence + \return \c true if dictionary contains sequence (matching on name) +*/ +bool SamSequenceDictionary::Contains(const SamSequence& sequence) const { + return ( IndexOf(sequence.Name) != (int)m_data.size() ); } -// returns iterator to container end +/*! \fn SamSequenceIterator SamSequenceDictionary::End(void) + \return an STL iterator pointing to the imaginary entry after the last sequence + \sa Begin(), ConstEnd() +*/ SamSequenceIterator SamSequenceDictionary::End(void) { return m_data.end(); } -// returns const_iterator to container begin +/*! \fn SamSequenceConstIterator SamSequenceDictionary::End(void) const + \return an STL const_iterator pointing to the imaginary entry after the last sequence + + This is an overloaded function. + + \sa Begin(), ConstEnd() +*/ SamSequenceConstIterator SamSequenceDictionary::End(void) const { return m_data.end(); } -// returns vector index of sequence if found -// returns vector::size() (invalid index) if not found -int SamSequenceDictionary::IndexOf(const SamSequence& sequence) const { +/*! \fn int SamSequenceDictionary::IndexOf(const std::string& name) const + \internal + \return index of sequence if found (matching on name). Otherwise, returns vector::size() (invalid index). +*/ +int SamSequenceDictionary::IndexOf(const std::string& name) const { SamSequenceConstIterator begin = ConstBegin(); SamSequenceConstIterator iter = begin; SamSequenceConstIterator end = ConstEnd(); - for ( ; iter != end; ++iter ) - if ( *iter == sequence ) break; + for ( ; iter != end; ++iter ) { + const SamSequence& currentSeq = (*iter); + if ( currentSeq.Name == name ) + break; + } return distance( begin, iter ); } -// overload to support std::string -int SamSequenceDictionary::IndexOf(const string& sequenceName) const { - return IndexOf( SamSequence(sequenceName) ); -} - -// returns true if container is empty +/*! \fn bool SamSequenceDictionary::IsEmpty(void) const + \brief Returns \c true if dictionary contains no sequences + \sa Size() +*/ bool SamSequenceDictionary::IsEmpty(void) const { return m_data.empty(); } -// removes sequence (if it exists) +/*! \fn void SamSequenceDictionary::Remove(const SamSequence& sequence) + \brief Removes sequence from dictionary, if found (matches on name). + + This is an overloaded function. + + \param[in] sequence SamSequence to remove (matching on name) +*/ void SamSequenceDictionary::Remove(const SamSequence& sequence) { - if ( Contains(sequence) ) - m_data.erase( m_data.begin() + IndexOf(sequence) ); + Remove( sequence.Name ); } -// overlaod to support std::string -void SamSequenceDictionary::Remove(const string& sequenceName) { - Remove( SamSequence(sequenceName) ); +/*! \fn void SamSequenceDictionary::Remove(const std::string& sequenceName) + \brief Removes sequence from dictionary, if found. + + \param[in] sequenceName name of sequence to remove + \sa Remove() +*/ +void SamSequenceDictionary::Remove(const std::string& sequenceName) { + if ( Contains(sequenceName) ) + m_data.erase( m_data.begin() + IndexOf(sequenceName) ); } -// remove multiple sequences -void SamSequenceDictionary::Remove(const vector& sequences) { +/*! \fn void SamSequenceDictionary::Remove(const std::vector& sequences) + \brief Removes multiple sequences from dictionary. + + This is an overloaded function. + + \param[in] sequences sequences to remove + \sa Remove() +*/ +void SamSequenceDictionary::Remove(const std::vector& sequences) { vector::const_iterator rgIter = sequences.begin(); vector::const_iterator rgEnd = sequences.end(); for ( ; rgIter!= rgEnd; ++rgIter ) Remove(*rgIter); } -// overload to support std::string -void SamSequenceDictionary::Remove(const vector& sequenceNames) { +/*! \fn void SamSequenceDictionary::Remove(const std::vector& sequenceNames) + \brief Removes multiple sequences from dictionary. + + This is an overloaded function. + + \param[in] sequenceNames names of the sequences to remove + \sa Remove() +*/ +void SamSequenceDictionary::Remove(const std::vector& sequenceNames) { vector::const_iterator rgIter = sequenceNames.begin(); vector::const_iterator rgEnd = sequenceNames.end(); for ( ; rgIter!= rgEnd; ++rgIter ) Remove(*rgIter); } -// returns size of container (number of current sequences) +/*! \fn int SamSequenceDictionary::Size(void) const + \brief Returns number of sequences in dictionary. + \sa IsEmpty() +*/ int SamSequenceDictionary::Size(void) const { return m_data.size(); } -// retrieves the SamSequence object associated with this name -// if sequenceName is unknown, a new SamSequence is created with this name (and invalid length 0) -// and a reference to this new sequence entry is returned (like std::map) +/*! \fn SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName) + \brief Retrieves the modifiable SamSequence that matches \a sequenceName. + + \note If the dictionary contains no sequence matching this name, this function inserts + a new one with this name (length:0), and returns a reference to it. If you want to avoid + this insertion behavior, check the result of Contains() before using this operator. + + \param[in] sequenceName name of sequence to retrieve + \return a modifiable reference to the SamSequence associated with the name +*/ SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName) { // look up sequence ID @@ -150,10 +297,7 @@ SamSequence& SamSequenceDictionary::operator[](const std::string& sequenceName) // otherwise, append new sequence and return reference else { - SamSequence seq(sequenceName); - seq.Length = "0"; - m_data.push_back(seq); + m_data.push_back( SamSequence(sequenceName, 0) ); return m_data.back(); } } -