Brought API up to compliance with recent SAM Format Spec (v1.4-r962)

[bamtools.git] / src / api / SamSequenceDictionary.cpp

diff --git a/src/api/SamSequenceDictionary.cpp b/src/api/SamSequenceDictionary.cpp
index 3249bd4162d846c174a8889546531e62f0a32e47..3e5240df386099cc5199fe0d3d173d5374b22303 100644 (file)
--- a/src/api/SamSequenceDictionary.cpp
+++ b/src/api/SamSequenceDictionary.cpp
@@ -3,7 +3,7 @@
 // Marth Lab, Department of Biology, Boston College
 // All rights reserved.
 // ---------------------------------------------------------------------------
 // Marth Lab, Department of Biology, Boston College
 // All rights reserved.
 // ---------------------------------------------------------------------------

-// Last modified: 20 March 2011 (DB)
+// Last modified: 18 April 2011 (DB)

 // ---------------------------------------------------------------------------
 // Provides methods for operating on a collection of SamSequence entries.
 // *************************************************************************
 // ---------------------------------------------------------------------------
 // Provides methods for operating on a collection of SamSequence entries.
 // *************************************************************************


@@ -40,11 +40,14 @@ SamSequenceDictionary::~SamSequenceDictionary(void) { }
 /*! \fn void SamSequenceDictionary::Add(const SamSequence& sequence)
     \brief Adds a sequence to the dictionary.
 
 /*! \fn void SamSequenceDictionary::Add(const SamSequence& sequence)
     \brief Adds a sequence to the dictionary.
 

-    Duplicate entries are discarded.
+    Duplicate entries are silently discarded.

 
     \param sequence entry to be added
 */
 void SamSequenceDictionary::Add(const SamSequence& sequence) {
 
     \param sequence entry to be added
 */
 void SamSequenceDictionary::Add(const SamSequence& sequence) {

+
+    // TODO: report error on attempted duplicate?
+

     if ( IsEmpty() || !Contains(sequence) )
         m_data.push_back(sequence);
 }
     if ( IsEmpty() || !Contains(sequence) )
         m_data.push_back(sequence);
 }


@@ -104,10 +107,10 @@ SamSequenceIterator SamSequenceDictionary::Begin(void) {
 }
 
 /*! \fn SamSequenceConstIterator SamSequenceDictionary::Begin(void) const
 }
 
 /*! \fn SamSequenceConstIterator SamSequenceDictionary::Begin(void) const

+    \return an STL const_iterator pointing to the first sequence

 
     This is an overloaded function.
 
 
     This is an overloaded function.
 

-    \return a const STL iterator pointing to the first sequence

     \sa ConstBegin(), End()
 */
 SamSequenceConstIterator SamSequenceDictionary::Begin(void) const {
     \sa ConstBegin(), End()
 */
 SamSequenceConstIterator SamSequenceDictionary::Begin(void) const {


@@ -122,7 +125,7 @@ void SamSequenceDictionary::Clear(void) {
 }
 
 /*! \fn SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const
 }
 
 /*! \fn SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const

-    \return a const STL iterator pointing to the first sequence
+    \return an STL const_iterator pointing to the first sequence

     \sa Begin(), ConstEnd()
 */
 SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const {
     \sa Begin(), ConstEnd()
 */
 SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const {


@@ -130,7 +133,7 @@ SamSequenceConstIterator SamSequenceDictionary::ConstBegin(void) const {
 }
 
 /*! \fn SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const
 }
 
 /*! \fn SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const

-    \return a const STL iterator pointing to the imaginary entry after the last sequence
+    \return an STL const_iterator pointing to the imaginary entry after the last sequence

     \sa End(), ConstBegin()
 */
 SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const {
     \sa End(), ConstBegin()
 */
 SamSequenceConstIterator SamSequenceDictionary::ConstEnd(void) const {


@@ -147,12 +150,15 @@ bool SamSequenceDictionary::Contains(const std::string& sequenceName) const {
 }
 
 /*! \fn bool SamSequenceDictionary::Contains(const SamSequence& sequence) const
 }
 
 /*! \fn bool SamSequenceDictionary::Contains(const SamSequence& sequence) const

-    \brief Returns true if dictionary contains sequence.
+    \brief Returns true if dictionary contains sequence (matches on name).
+
+    This is an overloaded function.
+

     \param sequence search for this sequence
     \param sequence search for this sequence

-    \return \c true if dictionary contains sequence
+    \return \c true if dictionary contains sequence (matching on name)

 */
 bool SamSequenceDictionary::Contains(const SamSequence& sequence) const {
 */
 bool SamSequenceDictionary::Contains(const SamSequence& sequence) const {

-    return ( IndexOf(sequence) != (int)m_data.size() );
+    return ( IndexOf(sequence.Name) != (int)m_data.size() );

 }
 
 /*! \fn SamSequenceIterator SamSequenceDictionary::End(void)
 }
 
 /*! \fn SamSequenceIterator SamSequenceDictionary::End(void)


@@ -164,41 +170,19 @@ SamSequenceIterator SamSequenceDictionary::End(void) {
 }
 
 /*! \fn SamSequenceConstIterator SamSequenceDictionary::End(void) const
 }
 
 /*! \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.
 
 
     This is an overloaded function.
 

-    \return a const STL iterator pointing to the imaginary entry after the last sequence

     \sa Begin(), ConstEnd()
 */
 SamSequenceConstIterator SamSequenceDictionary::End(void) const {
     return m_data.end();
 }
 
     \sa Begin(), ConstEnd()
 */
 SamSequenceConstIterator SamSequenceDictionary::End(void) const {
     return m_data.end();
 }
 

-/*! \fn int SamSequenceDictionary::IndexOf(const SamSequence& sequence) const
-    \internal
-
-    Uses operator==(SamSequence, SamSequence)
-
-    \return index of sequence if found.  Otherwise, returns vector::size() (invalid index).
-*/
-int SamSequenceDictionary::IndexOf(const SamSequence& sequence) const {
-    SamSequenceConstIterator begin = ConstBegin();
-    SamSequenceConstIterator iter  = begin;
-    SamSequenceConstIterator end   = ConstEnd();
-    for ( ; iter != end; ++iter ) {
-        const SamSequence& currentSeq = (*iter);
-        if ( currentSeq == sequence )
-            break;
-    }
-    return distance( begin, iter );
-}
-

 /*! \fn int SamSequenceDictionary::IndexOf(const std::string& name) const
     \internal
 /*! \fn int SamSequenceDictionary::IndexOf(const std::string& name) const
     \internal

-
-    Use comparison of SamSequence::Name to \a name
-
-    \return index of sequence if found.  Otherwise, returns vector::size() (invalid index).
+    \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();
 */
 int SamSequenceDictionary::IndexOf(const std::string& name) const {
     SamSequenceConstIterator begin = ConstBegin();


@@ -221,12 +205,14 @@ bool SamSequenceDictionary::IsEmpty(void) const {
 }
 
 /*! \fn void SamSequenceDictionary::Remove(const SamSequence& sequence)
 }
 
 /*! \fn void SamSequenceDictionary::Remove(const SamSequence& sequence)

-    \brief Removes sequence from dictionary, if found.
-    \param sequence sequence to remove
+    \brief Removes sequence from dictionary, if found (matches on name).
+
+    This is an overloaded function.
+
+    \param sequence SamSequence to remove (matching on name)

 */
 void SamSequenceDictionary::Remove(const SamSequence& sequence) {
 */
 void SamSequenceDictionary::Remove(const SamSequence& sequence) {

-    if ( Contains(sequence) )
-        m_data.erase( m_data.begin() + IndexOf(sequence) );
+    Remove( sequence.Name );

 }
 
 /*! \fn void SamSequenceDictionary::Remove(const std::string& sequenceName)
 }
 
 /*! \fn void SamSequenceDictionary::Remove(const std::string& sequenceName)


@@ -282,7 +268,7 @@ int SamSequenceDictionary::Size(void) const {
     \brief Retrieves the modifiable SamSequence that matches \a sequenceName.
 
     NOTE - If the dictionary contains no sequence matching this name, this function inserts
     \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, and returns a reference to it.
+    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.
 
     If you want to avoid this insertion behavior, check the result of Contains() before
     using this operator.