src/api/BamIndex.h

   1 // ***************************************************************************
   2 // BamIndex.h (c) 2009 Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // All rights reserved.
   5 // ---------------------------------------------------------------------------
   6 // Last modified: 5 April 2011 (DB)
   7 // ---------------------------------------------------------------------------
   8 // Provides basic BAM index interface
   9 // ***************************************************************************
  10
  11 #ifndef BAM_INDEX_H
  12 #define BAM_INDEX_H
  13
  14 #include <api/api_global.h>
  15 #include <api/BamAux.h>
  16 #include <string>
  17
  18 namespace BamTools {
  19
  20 namespace Internal {
  21     class BamReaderPrivate;
  22 } // namespace Internal
  23
  24 /*! \class BamTools::BamIndex
  25     \brief Provides methods for generating & loading BAM index files.
  26
  27     This class straddles the line between public API and internal
  28     implementation detail. Most client code should never have to use this
  29     class directly.
  30
  31     It is exposed to the public API to allow advanced users to implement
  32     their own custom indexing schemes.
  33
  34     More documentation on methods & enums coming soon.
  35 */
  36
  37 class API_EXPORT BamIndex {
  38
  39     // enums
  40     public:
  41         // specify index-caching behavior
  42         enum IndexCacheMode { FullIndexCaching = 0 // store entire index file contents in memory
  43                             , LimitedIndexCaching  // store only index data for current reference
  44                             , NoIndexCaching       // do not store any index data between jumps
  45                             };
  46
  47         // list of supported BamIndex types
  48         enum IndexType { BAMTOOLS = 0
  49                        , STANDARD
  50                        };
  51
  52     // ctor & dtor
  53     public:
  54         BamIndex(Internal::BamReaderPrivate* reader) : m_reader(reader) { }
  55         virtual ~BamIndex(void) { }
  56
  57     // index interface
  58     public:
  59         // builds index from associated BAM file & writes out to index file
  60         virtual bool Create(void) =0; // creates index file from BAM file
  61         // returns whether reference has alignments or no
  62         virtual bool HasAlignments(const int& referenceID) const =0;
  63         // attempts to use index data to jump to @region, returns success/fail
  64         // a "successful" jump indicates no error, but not whether this region has data
  65         //   * thus, the method sets a flag to indicate whether there are alignments
  66         //     available after the jump position
  67         virtual bool Jump(const BamTools::BamRegion& region, bool* hasAlignmentsInRegion) =0;
  68         // loads existing data from file into memory
  69         virtual bool Load(const std::string& filename) =0;
  70         // change the index caching behavior
  71         virtual void SetCacheMode(const BamIndex::IndexCacheMode& mode) =0;
  72
  73     // data members
  74     protected:
  75         Internal::BamReaderPrivate* m_reader; // copy, not ownedprivate:
  76 };
  77
  78 } // namespace BamTools
  79
  80 #endif // BAM_INDEX_H