src/api/BamIndex.h

   1 // ***************************************************************************
   2 // BamIndex.h (c) 2009 Derek Barnett
   3 // Marth Lab, Department of Biology, Boston College
   4 // ---------------------------------------------------------------------------
   5 // Last modified: 10 October 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
  34 class API_EXPORT BamIndex {
  35
  36     // enums
  37     public:
  38
  39         // list of supported BamIndex types
  40         enum IndexType { BAMTOOLS = 0
  41                        , STANDARD
  42                        };
  43
  44     // ctor & dtor
  45     public:
  46         BamIndex(Internal::BamReaderPrivate* reader) : m_reader(reader) { }
  47         virtual ~BamIndex(void) { }
  48
  49     // index interface
  50     public:
  51         // builds index from associated BAM file & writes out to index file
  52         virtual bool Create(void) =0;
  53
  54         // returns a human-readable description of the last error encountered
  55         std::string GetErrorString(void) { return m_errorString; }
  56
  57         // returns whether reference has alignments or no
  58         virtual bool HasAlignments(const int& referenceID) const =0;
  59
  60         // attempts to use index data to jump to @region, returns success/fail
  61         // a "successful" jump indicates no error, but not whether this region has data
  62         //   * thus, the method sets a flag to indicate whether there are alignments
  63         //     available after the jump position
  64         virtual bool Jump(const BamTools::BamRegion& region, bool* hasAlignmentsInRegion) =0;
  65
  66         // loads existing data from file into memory
  67         virtual bool Load(const std::string& filename) =0;
  68
  69         // returns the 'type' enum for derived index format
  70         virtual BamIndex::IndexType Type(void) const =0;
  71
  72     //! \cond
  73
  74     // internal methods
  75     protected:
  76         void SetErrorString(const std::string& where, const std::string& what) const {
  77             m_errorString = where + ": " + what;
  78         }
  79
  80     // data members
  81     protected:
  82         Internal::BamReaderPrivate* m_reader; // copy, not owned
  83         mutable std::string m_errorString;
  84
  85     //! \endcond
  86 };
  87
  88 } // namespace BamTools
  89
  90 #endif // BAM_INDEX_H