merge master 2.3.0

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

diff --git a/src/api/BamReader.cpp b/src/api/BamReader.cpp
index ae2adec94e498dadc97115807ab0d52dbe178804..c4f043221b5d85765488406647cf681a2ec8ba7e 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: 29 July 2013 (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();
@@ -154,8 +171,8 @@ bool BamReader::GetNextAlignment(BamAlignment& alignment) {
 
     However, this method does NOT populate the alignment's string data fields
     (read name, bases, qualities, tags, filename). This provides a boost in speed
-    when these fields are not required for every alignment. These fields can be
-    populated 'lazily' (as needed) by calling BamAlignment::BuildCharData() later.
+    when these fields are not required for every alignment. These fields, excluding filename,
+    can be populated 'lazily' (as needed) by calling BamAlignment::BuildCharData() later.
 
     \param[out] alignment destination for alignment record data
     \returns \c true if a valid alignment was found