From: Derek Barnett Date: Mon, 19 Nov 2012 04:48:59 +0000 (-0500) Subject: Added GetConstSamHeader() to BamReader X-Git-Url: https://git.donarmstrong.com/?p=bamtools.git;a=commitdiff_plain;h=d1c8508ec5cbeafd6a1e5af4756059ccf168216f 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 ae2adec..0728d96 100644 --- 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 fb9064d..cf8639e 100644 --- a/src/api/BamReader.h +++ b/src/api/BamReader.h @@ -2,7 +2,7 @@ // BamReader.h (c) 2009 Derek Barnett, Michael Str�mberg // Marth Lab, Department of Biology, Boston College // --------------------------------------------------------------------------- -// Last modified: 10 October 2011 (DB) +// Last modified: 18 November 2012 (DB) // --------------------------------------------------------------------------- // Provides read access to BAM files. // *************************************************************************** @@ -69,7 +69,9 @@ class API_EXPORT BamReader { // access header data // ---------------------- - // returns SAM header data + // returns a read-only reference to SAM header data + const SamHeader& BamReader::GetConstSamHeader(void) const; + // returns an editable copy of SAM header data SamHeader GetHeader(void) const; // returns SAM header data, as SAM-formatted text std::string GetHeaderText(void) const; diff --git a/src/api/internal/bam/BamHeader_p.cpp b/src/api/internal/bam/BamHeader_p.cpp index 02c0a25..aa3cdf7 100644 --- 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 499ad96..22851d8 100644 --- 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 24e54fd..737d598 100644 --- 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 e8db646..a49ad2a 100644 --- 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;