index.h

Go to the documentation of this file.

/*************************************************************
 **
 ** @file index/index.h
 **
 ** Copyright (C) 2012  Xpace, LLC.  All rights reserved
 **
 ** www.xpace.net
 **
 **************************************************************/

#ifndef XPACE_INDEX_H
#define XPACE_INDEX_H

#include "base/types.h"
#include "base/sharedimpl.h"
#include "base/config.h"
#include "util/file.h"
#include "index/reflist/reflist.h"

namespace Xpace
{
  /// An index
  class XPACE_EXPORT Index 
  {
  public :
    enum { MAX_TERM_SIZE = 8192 };

    static const char* FIELD_TAG;    ///< Configuration tag for an indexed field
    static const char* PARSED_TAG;   ///< Configuration tag for a parsed index

    /// create an empty index 
    /// @param config use this configuration
    explicit Index
      (const Configuration& config);        

    /// read an index
    /// @param config use this configuration
    /// @param indexFile read from this file
    /// @param oRoot file position of index root
    /// @param refCount number of refs in the index's universe
    Index
      (const Configuration& config,
       File* indexFile,
       File::Position oRoot,
       uint64 refCount = 0);

    /// @return true iff the index is empty
    bool operator!
      ()
      const;
    
    /// @return true iff the index has term counts
    bool hasCounts
      ()
      const;

    /// @return Index's name
    String getName
      ()
      const;

    /// @return Index's configuration
    String getConfig
      ()
      const;

    /// sort this index; could take a while
    /// status callback
    struct sortStatus
    {
      virtual ~sortStatus
        () 
      {
      };

      sortStatus
        () :
          interval(0)
      {
      };

      /// @return true to continue, false to stop
      virtual bool operator()
        ()
      { 
        return true; 
      };
      uint64 interval;   ///< call operator() this often
    };
    /// @param st status callback
    bool makeSorted
      (sortStatus* st = 0);

    /// write this index; could take a while
    /// status callback
    struct WriteStatus
    {
      virtual ~WriteStatus
        () 
      { 
      };

      /// @param term the term being written
      /// @param offset file offset to wich we're writing
      /// @return interval (in bytes) to continue, 0 to stop
      virtual uint operator()
        (uint64 termNum,
         String term,
         File::Position offset)
      = 0;
    };
    /// @param file write to this file (at current position)
    /// @param st status callback
    /// @return file position of index root
    File::Position write
      (File* file,
       WriteStatus* st = 0);

    /// merge a list of indexes
    /// @param file merge to this file
    /// @param list merge these indexes
    /// @return file position of index root
    static
    File::Position merge
      (File* file,
       std::vector<Index>& list);

    /// index term iterator
    class XPACE_EXPORT Iter
    {
    public :
      /// @retval the count of docs containing the term (if index has counts)
      /// @return a string representation (from a Collator) of this index term
      String getTerm
        (uint64* count = 0)
        const;

      /// @return the list of references for this index term
      RefListCursor getRefList
        ()
        const;

      /// @return the list of all references for all index terms in the interval [*this, end)
      /// @param (one past) the end of the interval
      RefListCursor getRefList
        (const Iter& end)
        const;

      /// @return true if the iterator is past the end of the index's term list
      bool operator!
        ()
        const;

      /// @param delta move the iterator this far in the index list
      /// @param relative if true move from current position, else move from start
      /// @return true if move successful, false (and don't move) if not
      bool move
        (int64 delta,
         bool relative = true);
      /// the distance between two iterators
      /// @param rhs the other iterator
      /// @return the distance
      int64 diff
        (const Iter& rhs)
        const;

      /// @return the position of the iterator
      uint64 getPos
        ()
        const;

    private :
      DECLARE_IMPL(Iter)
      friend class Index;
      friend class RLC_Index;
    };

    /// @return the number of terms in the index
    uint64 getTermCount
      ()
      const;

    /// @return Iter corresponding to the first term in the Index
    Iter begin
      ()
      const;

    /// find a key in the index
    /// @param key find this String
    /// @param found fillin true if key is found
    /// @return Iter corresponding to the key, next Iter if not found
    Iter begin
      (const String& key,
       bool* found = 0)
      const;

    /// @param key find this int64
    /// @retval found fillin true if key is found
    /// @return Iter corresponding to the key, next Iter if not found
    Iter begin
      (int64 key,
       bool* found = 0)
      const;

    /// @param key find this Key
    /// @retval found fillin true if key is found
    /// @return Iter corresponding to the key, next Iter if not found
    Iter begin
      (const BytesRef& key,
       bool* found = 0)
      const;

    /// search for a key, adding if it's not there

    /// @param key find/add this String
    /// @param added fillin true if key was added
    /// @return Iter corresponding to the key
    Iter beginAdd
      (const String& key,
       bool* added);

    /// @param key find/add this int64
    /// @param added fillin true if key was added
    /// @return Iter corresponding to the key
    Iter beginAdd
      (int64 key,
       bool* added);

    /// @param key find/add this Key
    /// @param found fillin true if key was added
    /// @return Iter corresponding to the key
    Iter beginAdd
      (const BytesRef& key,
       bool* added);

    /// @return the iter one past the end
    Iter end
      ()
      const;

    /// @return true iff term can match a regular expression (next() must return something meaningful)
    bool regexOK
      ()
      const;

    /// @param term an index term
    /// @return the next possible term of the same length after this one 
    String next
      (const String& key)
      const;

    #ifdef XPACE_COMPARATOR_H
    std::unique_ptr<Comparator> getComparator
      ()
      const;
    #endif

    /// traverse each term, or each reference, in an interval of terms
    class Sink
    {
    public:
      virtual ~Sink
        () 
      { 
      }

      /// called for each term 
      /// @param key a string representation (from a Collator) of this index term
      /// @param count the count (if stored in the Index) of references to the key 
      /// @return true to continue, false to stop
      virtual bool term
        (const String& key,
         uint64 count)
      = 0;
      /// called for each ref
      /// @param ref the ref
      /// @return true to continue, false to stop
      virtual bool ref
        (const Ref<uint64>& /*ref*/)
      {
        return true;
      }
    };

    /// traverse each term in the range [begin, end)
    /// @param begin start here
    /// @param end end here
    /// @param act call this for each term
    /// @param refList if != 0, call act only for terms in this refList
    /// @return true if completed, false if stopped by callback
    bool forEachTerm
      (Iter& begin,
       Iter& end,
       Sink* sink,
       const RefListCursor* refList = 0)
      const;
    /// @param start start at the start'th term
    /// @param count for this many terms
    bool forEachTerm
      (uint64 start,
       uint64 count,
       Sink* sink,
       const RefListCursor* refList = 0)
      const;
    bool forEachTerm
      (Sink* sink,
       const RefListCursor* refList = 0)
      const
    {
      return forEachTerm(0, ~uint64(0), sink, refList);
    }

    /// traverse each ref in each term in the range [begin, end)
    /// @param begin start here
    /// @param end end here
    /// @param act call this for each term, and each ref
    /// @return true if completed, false if stopped by callback
    bool forEachRef
      (Iter& begin,
       Iter& end,
       Sink* act)
      const;
    /// @param start start at the start'th term
    /// @param count for this many terms
    /// @return true if completed, false if stopped by callback
    bool forEachRef
      (uint64 start,
       uint64 count,
       Sink* act)
      const;
    bool forEachRef
      (Sink* act)
      const
    {
      return forEachRef(0, ~uint64(0), act);
    }

    #ifdef XPACE_RESULT_H
    /// Get a range of terms 
    /// @param begin starting at this term
    /// @param count (at most) this many terms
    /// @param includeCounts if there are counts in the index, include them in the result
    /// @return the result, filled with the terms
    TableResult getTerms
      (uint64 begin,
       uint64 count,
       bool includeCounts)
    const;
    #endif

    #ifdef XPACE_REFLIST_H
    /// @param query a query string
    /// @param recCount for NOT searches
    /// @return a RefListCursor into the result
    RefListCursor eval
      (String query,
       uint64 recCount = 0)
      const;
    
    #ifdef QDOM_H
    /// @param query a search tree
    /// @param recCount for NOT searches
    /// @return a RefListCursor into the result
    RefListCursor eval
      (QDomNode query,
       uint64 recCount = 0)
      const;
    #endif
    #endif

  private :
    File::Position write_temp
      (File*,
       WriteStatus*);  

    DECLARE_IMPL(Index)   
  };
    
  /// Parameters for sorting
  struct XPACE_EXPORT SortContext
  {
    const Index* index;         ///< Sort using this index
     
    bool ascend;                ///< Sort ascending if true, descending if false
    bool keepDuplicates;        ///< If true, repeat recurring terms (single sort only)

    /// What to do with unindexed terms
    enum unindexedAct
    {
      unindexedDrop = 0,        ///< drop them
      unindexedfirst = 1,       ///< return them first
      unindexedLast = 2         ///< return them last
    };
    unindexedAct unindexed;  

    SortContext
      (const Index* index,
       bool ascend = true,
       bool keepDuplicates = true,
       unindexedAct unindexed = unindexedDrop);
  };
};

#endif