Minor formatting cleanup

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

diff --git a/src/api/BamReader.h b/src/api/BamReader.h
index 132c95b826dbe854750c883fe38d20a4a2ab4806..1160bd547fa31518aa263bef7f4ccc95ae5fb84d 100644 (file)
--- a/src/api/BamReader.h
+++ b/src/api/BamReader.h
@@ -3,7 +3,7 @@
 // Marth Lab, Department of Biology, Boston College\r
 // All rights reserved.\r
 // ---------------------------------------------------------------------------\r
-// Last modified: 18 September 2010 (DB)\r
+// Last modified: 13 October 2010 (DB)\r
 // ---------------------------------------------------------------------------\r
 // Uses BGZF routines were adapted from the bgzf.c code developed at the Broad\r
 // Institute.\r
@@ -16,6 +16,7 @@
 \r
 #include <string>\r
 #include "BamAlignment.h"\r
+#include "BamIndex.h"\r
 \r
 namespace BamTools {\r
   \r
@@ -35,15 +36,15 @@ class BamReader {
 \r
         // close BAM file\r
         void Close(void);\r
-        // returns whether index data is loaded (i.e. reader is able to Jump() or not)\r
-        bool IsIndexLoaded(void) const;\r
         // returns whether reader is open for reading or not\r
         bool IsOpen(void) const;\r
         // performs random-access jump using (reference, position) as a left-bound\r
         bool Jump(int refID, int position = 0);\r
         // opens BAM file (and optional BAM index file, if provided)\r
-        // @lookForIndex - if no indexFilename provided, look for an existing index file\r
-        // @preferStandardIndex - if true, give priority in index file searching to standard BAM index\r
+        // @lookForIndex - if no indexFilename provided, look in BAM file's directory for an existing index file\r
+       //   default behavior is to skip index file search if no index filename given\r
+        // @preferStandardIndex - if true, give priority in index file searching to standard BAM index (*.bai)\r
+       //   default behavior is to prefer the BamToolsIndex (*.bti) if both are available\r
         bool Open(const std::string& filename, \r
                   const std::string& indexFilename = "", \r
                   const bool lookForIndex = false, \r
@@ -51,8 +52,7 @@ class BamReader {
         // returns file pointer to beginning of alignments\r
         bool Rewind(void);\r
         // sets a region of interest (with left & right bound reference/position)\r
-        // attempts a Jump() to left bound as well\r
-        // returns success/failure of Jump()\r
+        // returns success/failure of seeking to left bound of region\r
         bool SetRegion(const BamRegion& region);\r
         bool SetRegion(const int& leftRefID, const int& leftBound, const int& rightRefID, const int& rightBound);\r
 \r
@@ -62,10 +62,10 @@ class BamReader {
 \r
         // retrieves next available alignment (returns success/fail)\r
         bool GetNextAlignment(BamAlignment& bAlignment);\r
-        \r
         // retrieves next available alignment core data (returns success/fail)\r
         // ** DOES NOT parse any character data (read name, bases, qualities, tag data) **\r
-        // useful for operations requiring ONLY aligner-related information (refId/position, alignment flags, CIGAR, mapQuality, etc)\r
+        // useful for operations requiring ONLY aligner-related information \r
+       // (refId/position, alignment flags, CIGAR, mapQuality, etc)\r
         bool GetNextAlignmentCore(BamAlignment& bAlignment);\r
 \r
         // ----------------------\r
@@ -91,6 +91,32 @@ class BamReader {
         // default behavior is to create the BAM standard index (".bai")\r
         // set flag to false to create the BamTools-specific index (".bti")\r
         bool CreateIndex(bool useStandardIndex = true);\r
+       // returns whether index data is available for reading \r
+       // (e.g. if true, BamReader should be able to seek to a region)\r
+       bool HasIndex(void) const;\r
+       // change the index caching behavior\r
+       // default BamReader/Index mode is LimitedIndexCaching\r
+       // @mode - can be either FullIndexCaching, LimitedIndexCaching, \r
+       //   or NoIndexCaching. See BamIndex.h for more details\r
+        void SetIndexCacheMode(const BamIndex::BamIndexCacheMode mode);\r
+       \r
+    // deprecated methods\r
+    public:\r
+       \r
+       // deprecated (but still available): prefer HasIndex() instead\r
+       //\r
+       // Deprecated purely for API semantic clarity - HasIndex() should be clearer \r
+       // than IsIndexLoaded() in light of the new caching modes that may clear the \r
+       // index data from memory, but leave the index file open for later random access \r
+       // seeks.\r
+       //\r
+       // For example, what would (IsIndexLoaded() == true) mean when cacheMode has been \r
+       // explicitly set to NoIndexCaching? This is confusing at best, misleading about \r
+       // current memory behavior at worst.\r
+       //\r
+       // returns whether index data is available \r
+       // (e.g. if true, BamReader should be able to seek to a region)\r
+        bool IsIndexLoaded(void) const;\r
         \r
     // private implementation\r
     private:\r