X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=src%2Fapi%2FSamReadGroupDictionary.cpp;h=e6f8a056bec3e4ea72c6c26465c318aeb6f99108;hb=8c80d760637f8df39262683cd2570f0589423d36;hp=2f0534efa9c68f52b0fc749461566d3694e6c9d0;hpb=577b6032aa3d85616047c8aba6061dd8dad20cfc;p=bamtools.git diff --git a/src/api/SamReadGroupDictionary.cpp b/src/api/SamReadGroupDictionary.cpp index 2f0534e..e6f8a05 100644 --- a/src/api/SamReadGroupDictionary.cpp +++ b/src/api/SamReadGroupDictionary.cpp @@ -3,10 +3,10 @@ // Marth Lab, Department of Biology, Boston College // All rights reserved. // --------------------------------------------------------------------------- -// Last modified: 23 December 2010 (DB) +// Last modified: 4 March 2011 (DB) // --------------------------------------------------------------------------- -// Provides container operations for collection of read group entries -// ************************************************************************* +// Provides methods for operating on a collection of SamReadGroup entries. +// *************************************************************************** #include using namespace BamTools; @@ -15,150 +15,263 @@ using namespace BamTools; #include using namespace std; -// ctor +/*! \class BamTools::SamReadGroupDictionary + \brief Container of SamReadGroup entries. + + Provides methods for operating on a collection of SamReadGroup entries. +*/ + +/*! \fn SamReadGroupDictionary::SamReadGroupDictionary(void) + \brief constructor +*/ SamReadGroupDictionary::SamReadGroupDictionary(void) { } -// copy ctor +/*! \fn SamReadGroupDictionary::SamReadGroupDictionary(const SamReadGroupDictionary& other) + \brief copy constructor +*/ SamReadGroupDictionary::SamReadGroupDictionary(const SamReadGroupDictionary& other) : m_data(other.m_data) { } -// dtor -SamReadGroupDictionary::~SamReadGroupDictionary(void) { - m_data.clear(); -} +/*! \fn SamReadGroupDictionary::~SamReadGroupDictionary(void) + \brief destructor +*/ +SamReadGroupDictionary::~SamReadGroupDictionary(void) { } + +/*! \fn void SamReadGroupDictionary::Add(const SamReadGroup& readGroup) + \brief Adds a read group to the dictionary. -// adds read group if not already in container + Duplicate entries are discarded. + + \param readGroup entry to be added +*/ void SamReadGroupDictionary::Add(const SamReadGroup& readGroup) { if ( IsEmpty() || !Contains(readGroup) ) m_data.push_back(readGroup); } -// overload to support std::string -void SamReadGroupDictionary::Add(const string& readGroupId) { +/*! \fn void SamReadGroupDictionary::Add(const std::string& readGroupId) + \brief Adds a read group to the dictionary. + + This is an overloaded function. + + \param readGroupId ID of read group to be added + \sa Add() +*/ +void SamReadGroupDictionary::Add(const std::string& readGroupId) { Add( SamReadGroup(readGroupId) ); } -// add multiple read groups -void SamReadGroupDictionary::Add(const vector& readGroups) { +/*! \fn void SamReadGroupDictionary::Add(const std::vector& readGroups) + \brief Adds multiple read groups to the dictionary. + + This is an overloaded function. + + \param readGroups entries to be added + \sa Add() +*/ +void SamReadGroupDictionary::Add(const std::vector& readGroups) { vector::const_iterator rgIter = readGroups.begin(); vector::const_iterator rgEnd = readGroups.end(); for ( ; rgIter!= rgEnd; ++rgIter ) Add(*rgIter); } -// overload to support std::string -void SamReadGroupDictionary::Add(const vector& readGroupIds) { +/*! \fn void SamReadGroupDictionary::Add(const std::vector& readGroupIds) + \brief Adds multiple read groups to the dictionary. + + This is an overloaded function. + + \param readGroupIds IDs of read groups to be added + \sa Add() +*/ +void SamReadGroupDictionary::Add(const std::vector& readGroupIds) { vector::const_iterator rgIter = readGroupIds.begin(); vector::const_iterator rgEnd = readGroupIds.end(); for ( ; rgIter!= rgEnd; ++rgIter ) Add(*rgIter); } -// returns iterator to container begin +/*! \fn SamReadGroupIterator SamReadGroupDictionary::Begin(void) + \return an STL iterator pointing to the first read group + \sa ConstBegin(), End() +*/ SamReadGroupIterator SamReadGroupDictionary::Begin(void) { return m_data.begin(); } -// returns const_iterator to container begin +/*! \fn SamReadGroupConstIterator SamReadGroupDictionary::Begin(void) const + + This is an overloaded function. + + \return a const STL iterator pointing to the first read group + \sa ConstBegin(), End() +*/ SamReadGroupConstIterator SamReadGroupDictionary::Begin(void) const { return m_data.begin(); } -// clear read group container +/*! \fn void SamReadGroupDictionary::Clear(void) + \brief Clears all read group entries. +*/ void SamReadGroupDictionary::Clear(void) { m_data.clear(); } -// explicit request for const_iterator to container begin +/*! \fn SamReadGroupConstIterator SamReadGroupDictionary::ConstBegin(void) const + \return a const STL iterator pointing to the first read group + \sa Begin(), ConstEnd() +*/ SamReadGroupConstIterator SamReadGroupDictionary::ConstBegin(void) const { return m_data.begin(); } -// explicit request for const_iterator to container end +/*! \fn SamReadGroupConstIterator SamReadGroupDictionary::ConstEnd(void) const + \return a const STL iterator pointing to the imaginary entry after the last read group + \sa ConstBegin(), End() +*/ SamReadGroupConstIterator SamReadGroupDictionary::ConstEnd(void) const { return m_data.end(); } -// returns true if container contains a read group with this ID tag -bool SamReadGroupDictionary::Contains(const string& readGroupId) const { - return ( IndexOf(readGroupId) != (int)m_data.size() ); +/*! \fn bool SamReadGroupDictionary::Contains(const std::string& readGroupId) const + \brief Returns true if dictionary contains read group. + + This is an overloaded function. + + \param readGroupId search for read group matching this ID + \return \c true if dictionary contains a read group with this ID +*/ +bool SamReadGroupDictionary::Contains(const std::string& readGroupId) const { + return Contains( SamReadGroup(readGroupId) ); } +/*! \fn bool SamReadGroupDictionary::Contains(const SamReadGroup& readGroup) const + \brief Returns true if dictionary contains read group. + \param readGroup search for this read group + \return \c true if dictionary contains read group +*/ bool SamReadGroupDictionary::Contains(const SamReadGroup& readGroup) const { return ( IndexOf(readGroup) != (int)m_data.size() ); } -// returns iterator to container end +/*! \fn SamReadGroupIterator SamReadGroupDictionary::End(void) + \return an STL iterator pointing to the imaginary entry after the last read group + \sa Begin(), ConstEnd() +*/ SamReadGroupIterator SamReadGroupDictionary::End(void) { return m_data.end(); } -// returns const_iterator to container begin +/*! \fn SamReadGroupConstIterator SamReadGroupDictionary::End(void) const + + This is an overloaded function. + + \return a const STL iterator pointing to the imaginary entry after the last read group + \sa Begin(), ConstEnd() +*/ SamReadGroupConstIterator SamReadGroupDictionary::End(void) const { return m_data.end(); } -// returns vector index of read group if found -// returns vector::size() (invalid index) if not found +/*! \fn int SamReadGroupDictionary::IndexOf(const SamReadGroup& readGroup) const + \internal + \return index of read group if found. Otherwise, returns vector::size() (invalid index). +*/ int SamReadGroupDictionary::IndexOf(const SamReadGroup& readGroup) const { SamReadGroupConstIterator begin = ConstBegin(); SamReadGroupConstIterator iter = begin; SamReadGroupConstIterator end = ConstEnd(); - for ( ; iter != end; ++iter ) - if ( *iter == readGroup ) break; + for ( ; iter != end; ++iter ) { + if ( *iter == readGroup ) + break; + } return distance( begin, iter ); } -// overload to support std::string -int SamReadGroupDictionary::IndexOf(const string& readGroupId) const { - return IndexOf( SamReadGroup(readGroupId) ); -} - -// returns true if container is empty +/*! \fn bool SamReadGroupDictionary::IsEmpty(void) const + \brief Returns \c true if dictionary contains no read groups + \sa Size() +*/ bool SamReadGroupDictionary::IsEmpty(void) const { return m_data.empty(); } -// removes read group (if it exists) +/*! \fn void SamReadGroupDictionary::Remove(const SamReadGroup& readGroup) + \brief Removes read group from dictionary, if found. + \param readGroup read group to remove +*/ void SamReadGroupDictionary::Remove(const SamReadGroup& readGroup) { if ( Contains(readGroup) ) m_data.erase( m_data.begin() + IndexOf(readGroup) ); } -// overlaod to support std::string -void SamReadGroupDictionary::Remove(const string& readGroupId) { +/*! \fn void SamReadGroupDictionary::Remove(const std::string& readGroupId) + \brief Removes read group from dictionary, if found. + + This is an overloaded function. + + \param readGroupId ID of read group to remove + \sa Remove() +*/ +void SamReadGroupDictionary::Remove(const std::string& readGroupId) { Remove( SamReadGroup(readGroupId) ); } -// remove multiple read groups -void SamReadGroupDictionary::Remove(const vector& readGroups) { +/*! \fn void SamReadGroupDictionary::Remove(const std::vector& readGroups) + \brief Removes multiple read groups from dictionary. + + This is an overloaded function. + + \param readGroups read groups to remove + \sa Remove() +*/ +void SamReadGroupDictionary::Remove(const std::vector& readGroups) { vector::const_iterator rgIter = readGroups.begin(); vector::const_iterator rgEnd = readGroups.end(); for ( ; rgIter!= rgEnd; ++rgIter ) Remove(*rgIter); } -// overload to support std::string -void SamReadGroupDictionary::Remove(const vector& readGroupIds) { +/*! \fn void SamReadGroupDictionary::Remove(const std::vector& readGroupIds) + \brief Removes multiple read groups from dictionary. + + This is an overloaded function. + + \param readGroupIds IDs of the read groups to remove + \sa Remove() +*/ +void SamReadGroupDictionary::Remove(const std::vector& readGroupIds) { vector::const_iterator rgIter = readGroupIds.begin(); vector::const_iterator rgEnd = readGroupIds.end(); for ( ; rgIter!= rgEnd; ++rgIter ) Remove(*rgIter); } -// returns size of container (number of current read groups) +/*! \fn int SamReadGroupDictionary::Size(void) const + \brief Returns number of read groups in dictionary. + \sa IsEmpty() +*/ int SamReadGroupDictionary::Size(void) const { return m_data.size(); } -// retrieves the SamReadGroup object associated with this ID -// if readGroupId is unknown, a new SamReadGroup is created with this ID -// and a reference to this new read group entry is returned (like std::map) +/*! \fn SamReadGroup& SamReadGroupDictionary::operator[](const std::string& readGroupId) + \brief Retrieves the modifiable SamReadGroup that matches \a readGroupId. + + NOTE - If the dictionary contains no read group matching this ID, this function inserts + a new one with this ID, and returns a reference to it. + + If you want to avoid this insertion behavior, check the result of Contains() before + using this operator. + + \param readGroupId ID of read group to retrieve + \return a modifiable reference to the SamReadGroup associated with the ID +*/ SamReadGroup& SamReadGroupDictionary::operator[](const std::string& readGroupId) { // look up read group ID - int index = IndexOf(readGroupId); + int index = IndexOf( SamReadGroup(readGroupId) ); // if found, return read group at index if ( index != (int)m_data.size() )