src/api/BamIndex.h

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