Added GetConstSamHeader() to BamReader

 * Allows for more efficient (read-only) access to SamHeader data

diff --git a/src/api/BamReader.cpp b/src/api/BamReader.cpp
index ae2adec94e498dadc97115807ab0d52dbe178804..0728d962141b559c6f8ce7d69a9721c9c02a7a52 100644 (file)
--- a/src/api/BamReader.cpp
+++ b/src/api/BamReader.cpp
@@ -2,7 +2,7 @@
 // BamReader.cpp (c) 2009 Derek Barnett, Michael Str�mberg
 // Marth Lab, Department of Biology, Boston College
 // ---------------------------------------------------------------------------
-// Last modified: 25 October 2011 (DB)
+// Last modified: 18 November 2012 (DB)
 // ---------------------------------------------------------------------------
 // Provides read access to BAM files.
 // ***************************************************************************
@@ -61,6 +61,22 @@ bool BamReader::CreateIndex(const BamIndex::IndexType& type) {
     return d->CreateIndex(type);
 }
 
+/*! \fn const SamHeader& BamReader::GetConstSamHeader(void) const
+    \brief Returns const reference to SAM header data.
+
+    Allows for read-only queries of SAM header data.
+
+    If you do not need to modify the SAM header, use this method to avoid the
+    potentially expensive copy used by GetHeader().
+
+    \note
+    \returns const reference to header data object
+    \sa GetHeader(), GetHeaderText()
+*/
+const SamHeader& BamReader::GetConstSamHeader(void) const {
+    return d->GetConstSamHeader();
+}
+
 /*! \fn std::string BamReader::GetErrorString(void) const
     \brief Returns a human-readable description of the last error that occurred
 
@@ -90,7 +106,8 @@ const std::string BamReader::GetFilename(void) const {
 /*! \fn SamHeader BamReader::GetHeader(void) const
     \brief Returns SAM header data.
 
-    Header data is wrapped in a SamHeader object that can be conveniently queried & modified.
+    Header data is wrapped in a SamHeader object that can be conveniently queried and/or modified.
+    If you only need read access, consider using GetConstSamHeader() instead.
 
     \note Modifying the retrieved SamHeader object does NOT affect the
     current BAM file. This file has been opened in a read-only mode.
@@ -98,7 +115,7 @@ const std::string BamReader::GetFilename(void) const {
     BamWriter to generate a new BAM file with the appropriate header information.
 
     \returns header data object
-    \sa GetHeaderText()
+    \sa GetConstSamHeader(), GetHeaderText()
 */
 SamHeader BamReader::GetHeader(void) const {
     return d->GetSamHeader();

diff --git a/src/api/BamReader.h b/src/api/BamReader.h
index fb9064d9994d08a4c2afe177b2ca205c1841da4c..cf8639e2dd8a9dc410a469d14def49cda57730ed 100644 (file)
--- a/src/api/BamReader.h
+++ b/src/api/BamReader.h
@@ -2,7 +2,7 @@
 // BamReader.h (c) 2009 Derek Barnett, Michael Str�mberg\r
 // Marth Lab, Department of Biology, Boston College\r
 // ---------------------------------------------------------------------------\r
-// Last modified: 10 October 2011 (DB)\r
+// Last modified: 18 November 2012 (DB)\r
 // ---------------------------------------------------------------------------\r
 // Provides read access to BAM files.\r
 // ***************************************************************************\r
@@ -69,7 +69,9 @@ class API_EXPORT BamReader {
         // access header data\r
         // ----------------------\r
 \r
-        // returns SAM header data\r
+        // returns a read-only reference to SAM header data\r
+        const SamHeader& BamReader::GetConstSamHeader(void) const;\r
+        // returns an editable copy of SAM header data\r
         SamHeader GetHeader(void) const;\r
         // returns SAM header data, as SAM-formatted text\r
         std::string GetHeaderText(void) const;\r

diff --git a/src/api/internal/bam/BamHeader_p.cpp b/src/api/internal/bam/BamHeader_p.cpp
index 02c0a25b8fd5cc773c8ee6cb35714de6197b1a17..aa3cdf7145ecd99949a658b353dddc8e8561670b 100644 (file)
--- a/src/api/internal/bam/BamHeader_p.cpp
+++ b/src/api/internal/bam/BamHeader_p.cpp
@@ -2,7 +2,7 @@
 // BamHeader_p.cpp (c) 2010 Derek Barnett
 // Marth Lab, Department of Biology, Boston College
 // ---------------------------------------------------------------------------
-// Last modified: 25 October 2011 (DB)
+// Last modified: 18 November 2012 (DB)
 // ---------------------------------------------------------------------------
 // Provides the basic functionality for handling BAM headers.
 // ***************************************************************************
@@ -109,6 +109,11 @@ void BamHeader::ReadHeaderText(BgzfStream* stream, const uint32_t& length) {
     free(headerText);
 }
 
+// returns const-reference to SamHeader data object
+const SamHeader& BamHeader::ToConstSamHeader(void) const {
+    return m_header;
+}
+
 // returns *copy* of SamHeader data object
 SamHeader BamHeader::ToSamHeader(void) const {
     return m_header;

diff --git a/src/api/internal/bam/BamHeader_p.h b/src/api/internal/bam/BamHeader_p.h
index 499ad96deaa15571c5235d946ecf2fe20bb8ad6d..22851d8f46c6c22dec1a7a81d55ea83d3a360ab5 100644 (file)
--- a/src/api/internal/bam/BamHeader_p.h
+++ b/src/api/internal/bam/BamHeader_p.h
@@ -2,7 +2,7 @@
 // BamHeader_p.h (c) 2010 Derek Barnett
 // Marth Lab, Department of Biology, Boston College
 // ---------------------------------------------------------------------------
-// Last modified: 10 October 2011 (DB)
+// Last modified: 18 November 2012 (DB)
 // ---------------------------------------------------------------------------
 // Provides the basic functionality for handling BAM headers.
 // ***************************************************************************
@@ -44,6 +44,8 @@ class BamHeader {
         // load BAM header ('magic number' and SAM header text) from BGZF stream
         // returns true if all OK
         void Load(BgzfStream* stream);
+        // returns (read-only) reference to SamHeader data object
+        const SamHeader& ToConstSamHeader(void) const;
         // returns (editable) copy of SamHeader data object
         SamHeader ToSamHeader(void) const;
         // returns SAM-formatted string of header data

diff --git a/src/api/internal/bam/BamReader_p.cpp b/src/api/internal/bam/BamReader_p.cpp
index 24e54fd08278b9f6b757322d78e2a6aa80986246..737d59800a36d8f7a2e787ad64ec94684f1ce2a1 100644 (file)
--- a/src/api/internal/bam/BamReader_p.cpp
+++ b/src/api/internal/bam/BamReader_p.cpp
@@ -2,7 +2,7 @@
 // BamReader_p.cpp (c) 2009 Derek Barnett
 // Marth Lab, Department of Biology, Boston College
 // ---------------------------------------------------------------------------
-// Last modified: 28 November 2011 (DB)
+// Last modified: 18 November 2012 (DB)
 // ---------------------------------------------------------------------------
 // Provides the basic functionality for reading BAM files
 // ***************************************************************************
@@ -94,6 +94,10 @@ const string BamReaderPrivate::Filename(void) const {
     return m_filename;
 }
 
+const SamHeader& BamReaderPrivate::GetConstSamHeader(void) const {
+    return m_header.ToConstSamHeader();
+}
+
 string BamReaderPrivate::GetErrorString(void) const {
     return m_errorString;
 }

diff --git a/src/api/internal/bam/BamReader_p.h b/src/api/internal/bam/BamReader_p.h
index e8db646e28034eaf20095b31a1fda2b3cd30a8a2..a49ad2a57003500ba74302f2274a70a6a87a31dd 100644 (file)
--- a/src/api/internal/bam/BamReader_p.h
+++ b/src/api/internal/bam/BamReader_p.h
@@ -2,7 +2,7 @@
 // BamReader_p.h (c) 2010 Derek Barnett
 // Marth Lab, Department of Biology, Boston College
 // ---------------------------------------------------------------------------
-// Last modified: 25 October 2011 (DB)
+// Last modified: 18 November 2012 (DB)
 // ---------------------------------------------------------------------------
 // Provides the basic functionality for reading BAM files
 // ***************************************************************************
@@ -56,6 +56,7 @@ class BamReaderPrivate {
 
         // access auxiliary data
         std::string GetHeaderText(void) const;
+        const SamHeader& GetConstSamHeader(void) const;
         SamHeader GetSamHeader(void) const;
         int GetReferenceCount(void) const;
         const RefVector& GetReferenceData(void) const;