Factor out function to decode 2 hex digits

[xapian.git] / xapian-core / include / xapian / enquire.h

/** @file
 * @brief API for running queries
 */
/* Copyright 1999,2000,2001 BrightStation PLC
 * Copyright 2001,2002 Ananova Ltd
 * Copyright 2002,2003,2004,2005,2006,2007,2008,2009,2011,2012,2013,2014,2015,2016 Olly Betts
 * Copyright 2009 Lemur Consulting Ltd
 * Copyright 2011 Action Without Borders
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
 * USA
 */

#ifndef XAPIAN_INCLUDED_ENQUIRE_H
#define XAPIAN_INCLUDED_ENQUIRE_H

#if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
# error Never use <xapian/enquire.h> directly; include <xapian.h> instead.
#endif

#include "xapian/deprecated.h"
#include <string>

#include <xapian/attributes.h>
#include <xapian/eset.h>
#include <xapian/intrusive_ptr.h>
#include <xapian/mset.h>
#include <xapian/stem.h>
#include <xapian/types.h>
#include <xapian/termiterator.h>
#include <xapian/visibility.h>

namespace Xapian {

class Database;
class Document;
class ErrorHandler;
class ExpandDecider;
class KeyMaker;
class MatchSpy;
class Query;
class Weight;

/** A relevance set (R-Set).
 *  This is the set of documents which are marked as relevant, for use
 *  in modifying the term weights, and in performing query expansion.
 */
class XAPIAN_VISIBILITY_DEFAULT RSet {
    public:
        /// Class holding details of RSet
        class Internal;

        /// @private @internal Reference counted internals.
        Xapian::Internal::intrusive_ptr<Internal> internal;

        /// Copy constructor
        RSet(const RSet &rset);

        /// Assignment operator
        void operator=(const RSet &rset);

#ifdef XAPIAN_MOVE_SEMANTICS
        /// Move constructor.
        RSet(RSet && o);

        /// Move assignment operator.
        RSet & operator=(RSet && o);
#endif

        /// Default constructor
        RSet();

        /// Destructor
        ~RSet();

        /** The number of documents in this R-Set */
        Xapian::doccount size() const;

        /** Test if this R-Set is empty */
        bool empty() const;

        /// Add a document to the relevance set.
        void add_document(Xapian::docid did);

        /// Add a document to the relevance set.
        void add_document(const Xapian::MSetIterator & i) { add_document(*i); }

        /// Remove a document from the relevance set.
        void remove_document(Xapian::docid did);

        /// Remove a document from the relevance set.
        void remove_document(const Xapian::MSetIterator & i) { remove_document(*i); }

        /// Test if a given document in the relevance set.
        bool contains(Xapian::docid did) const;

        /// Test if a given document in the relevance set.
        bool contains(const Xapian::MSetIterator & i) const { return contains(*i); }

        /// Return a string describing this object.
        std::string get_description() const;
};

/** Base class for matcher decision functor.
 */
class XAPIAN_VISIBILITY_DEFAULT MatchDecider {
        /// Don't allow assignment.
        void operator=(const MatchDecider &);

        /// Don't allow copying.
        MatchDecider(const MatchDecider &);

    public:
        /// Default constructor
        MatchDecider() { }

        /** Decide whether we want this document to be in the MSet.
         *
         *  @param doc  The document to test.
         *
         *  @return true if the document is acceptable, or false if the document
         *  should be excluded from the MSet.
         */
        virtual bool operator()(const Xapian::Document &doc) const = 0;

        /// Destructor.
        virtual ~MatchDecider();
};

/** This class provides an interface to the information retrieval
 *  system for the purpose of searching.
 *
 *  Databases are usually opened lazily, so exceptions may not be
 *  thrown where you would expect them to be.  You should catch
 *  Xapian::Error exceptions when calling any method in Xapian::Enquire.
 *
 *  @exception Xapian::InvalidArgumentError will be thrown if an invalid
 *  argument is supplied, for example, an unknown database type.
 */
class XAPIAN_VISIBILITY_DEFAULT Enquire {
    public:
        /// Copying is allowed (and is cheap).
        Enquire(const Enquire & other);

        /// Assignment is allowed (and is cheap).
        void operator=(const Enquire & other);

#ifdef XAPIAN_MOVE_SEMANTICS
        /// Move constructor.
        Enquire(Enquire&& o);

        /// Move assignment operator.
        Enquire& operator=(Enquire&& o);
#endif

        class Internal;
        /// @private @internal Reference counted internals.
        Xapian::Internal::intrusive_ptr<Internal> internal;

        /** Create a Xapian::Enquire object.
         *
         *  This specification cannot be changed once the Xapian::Enquire is
         *  opened: you must create a new Xapian::Enquire object to access a
         *  different database, or set of databases.
         *
         *  The database supplied must have been initialised (ie, must not be
         *  the result of calling the Database::Database() constructor).  If
         *  you need to handle a situation where you have no databases
         *  gracefully, a database created with DB_BACKEND_INMEMORY can be
         *  passed here to provide a completely empty database.
         *
         *  @param database Specification of the database or databases to
         *         use.
         *
         *  @exception Xapian::InvalidArgumentError will be thrown if an
         *  empty Database object is supplied.
         */
        explicit Enquire(const Database &database);

        /** Create a Xapian::Enquire object.
         *
         *  This specification cannot be changed once the Xapian::Enquire is
         *  opened: you must create a new Xapian::Enquire object to access a
         *  different database, or set of databases.
         *
         *  The database supplied must have been initialised (ie, must not be
         *  the result of calling the Database::Database() constructor).  If
         *  you need to handle a situation where you have no databases
         *  gracefully, a database created with DB_BACKEND_INMEMORY can be
         *  passed here to provide a completely empty database.
         *
         *  @param database Specification of the database or databases to
         *         use.
         *  @param errorhandler_  This parameter is deprecated (since Xapian
         *         1.3.1), and as of 1.3.5 it's ignored completely.
         *
         *  @exception Xapian::InvalidArgumentError will be thrown if an
         *  empty Database object is supplied.
         */
        XAPIAN_DEPRECATED_EX(Enquire(const Database &database, ErrorHandler * errorhandler_));

        /** Close the Xapian::Enquire object.
         */
        ~Enquire();

        /** Set the query to run.
         *
         *  @param query  the new query to run.
         *  @param qlen   the query length to use in weight calculations -
         *      by default the sum of the wqf of all terms is used.
         */
        void set_query(const Xapian::Query & query, Xapian::termcount qlen = 0);

        /** Get the current query.
         *
         *  If called before set_query(), this will return a default
         *  initialised Query object.
         */
        const Xapian::Query & get_query() const;

        /** Add a matchspy.
         *
         *  This matchspy will be called with some of the documents which match
         *  the query, during the match process.  Exactly which of the matching
         *  documents are passed to it depends on exactly when certain
         *  optimisations occur during the match process, but it can be
         *  controlled to some extent by setting the @a checkatleast parameter
         *  to @a get_mset().
         *
         *  In particular, if there are enough matching documents, at least the
         *  number specified by @a checkatleast will be passed to the matchspy.
         *  This means that you can force the matchspy to be shown all matching
         *  documents by setting @a checkatleast to the number of documents in
         *  the database.
         *
         *  @param spy       The MatchSpy subclass to add.  The caller must
         *                   ensure that this remains valid while the Enquire
         *                   object remains active, or until @a
         *                   clear_matchspies() is called.
         */
        void add_matchspy(MatchSpy * spy);

        /** Remove all the matchspies.
         */
        void clear_matchspies();

        /** Set the weighting scheme to use for queries.
         *
         *  @param weight_  the new weighting scheme.  If no weighting scheme
         *                  is specified, the default is BM25 with the
         *                  default parameters.
         */
        void set_weighting_scheme(const Weight &weight_);

        /** Set the weighting scheme to use for expansion.
         *
         *  If you don't call this method, the default is as if you'd used:
         *
         *  get_expansion_scheme("trad");
         *
         *  @param eweightname_  A string in lowercase specifying the name of
         *                       the scheme to be used. The following schemes
         *                       are currently available:
         *                       "bo1" : The Bo1 scheme for query expansion.
         *                       "trad" : The TradWeight scheme for query expansion.
         *  @param expand_k_ The parameter required for TradWeight query expansion.
         *                   A default value of 1.0 is used if none is specified.
         */
        void set_expansion_scheme(const std::string &eweightname_,
                                  double expand_k_ = 1.0) const;

        /** Set the collapse key to use for queries.
         *
         *  @param collapse_key  value number to collapse on - at most one MSet
         *      entry with each particular value will be returned
         *      (default is Xapian::BAD_VALUENO which means no collapsing).
         *
         *  @param collapse_max  Max number of items with the same key to leave
         *                       after collapsing (default 1).
         *
         *      The MSet returned by get_mset() will have only the "best"
         *      (at most) @a collapse_max entries with each particular
         *      value of @a collapse_key ("best" being highest ranked - i.e.
         *      highest weight or highest sorting key).
         *
         *      An example use might be to create a value for each document
         *      containing an MD5 hash of the document contents.  Then
         *      duplicate documents from different sources can be eliminated at
         *      search time by collapsing with @a collapse_max = 1 (it's better
         *      to eliminate duplicates at index time, but this may not be
         *      always be possible - for example the search may be over more
         *      than one Xapian database).
         *
         *      Another use is to group matches in a particular category (e.g.
         *      you might collapse a mailing list search on the Subject: so
         *      that there's only one result per discussion thread).  In this
         *      case you can use get_collapse_count() to give the user some
         *      idea how many other results there are.  And if you index the
         *      Subject: as a boolean term as well as putting it in a value,
         *      you can offer a link to a non-collapsed search restricted to
         *      that thread using a boolean filter.
         */
        void set_collapse_key(Xapian::valueno collapse_key,
                              Xapian::doccount collapse_max = 1);

        /** Ordering of docids.
         *
         *  Parameter to Enquire::set_docid_order().
         */
        typedef enum {
            /** docids sort in ascending order (default) */
            ASCENDING = 1,
            /** docids sort in descending order. */
            DESCENDING = 0,
            /** docids sort in whatever order is most efficient for the
             *  backend. */
            DONT_CARE = 2
        } docid_order;

        /** Set sort order for document IDs.
         *
         *  This order only has an effect on documents which would otherwise
         *  have equal rank.  When ordering by relevance without a sort key,
         *  this means documents with equal weight.  For a boolean match
         *  with no sort key, this means all documents.  And if a sort key
         *  is used, this means documents with the same sort key (and also equal
         *  weight if ordering on relevance before or after the sort key).
         *
         * @param order  This can be:
         * - Xapian::Enquire::ASCENDING
         *      docids sort in ascending order (default)
         * - Xapian::Enquire::DESCENDING
         *      docids sort in descending order
         * - Xapian::Enquire::DONT_CARE
         *      docids sort in whatever order is most efficient for the backend
         *
         *  Note: If you add documents in strict date order, then a boolean
         *  search - i.e. set_weighting_scheme(Xapian::BoolWeight()) - with
         *  set_docid_order(Xapian::Enquire::DESCENDING) is an efficient
         *  way to perform "sort by date, newest first", and with
         *  set_docid_order(Xapian::Enquire::ASCENDING) a very efficient way
         *  to perform "sort by date, oldest first".
         */
        void set_docid_order(docid_order order);

        /** Set the percentage and/or weight cutoffs.
         *
         * @param percent_cutoff Minimum percentage score for returned
         *      documents. If a document has a lower percentage score than this,
         *      it will not appear in the MSet.  If your intention is to return
         *      only matches which contain all the terms in the query, then
         *      it's more efficient to use Xapian::Query::OP_AND instead of
         *      Xapian::Query::OP_OR in the query than to use set_cutoff(100).
         *      (default 0 => no percentage cut-off).
         * @param weight_cutoff Minimum weight for a document to be returned.
         *      If a document has a lower score that this, it will not appear
         *      in the MSet.  It is usually only possible to choose an
         *      appropriate weight for cutoff based on the results of a
         *      previous run of the same query; this is thus mainly useful for
         *      alerting operations.  The other potential use is with a user
         *      specified weighting scheme.
         *      (default 0 => no weight cut-off).
         */
        void set_cutoff(int percent_cutoff, double weight_cutoff = 0);

        /** Set the sorting to be by relevance only.
         *
         *  This is the default.
         */
        void set_sort_by_relevance();

        /** Set the sorting to be by value only.
         *
         *  Note that sorting by values uses a string comparison, so to use
         *  this to sort by a numeric value you'll need to store the numeric
         *  values in a manner which sorts appropriately.  For example, you
         *  could use Xapian::sortable_serialise() (which works for floating
         *  point numbers as well as integers), or store numbers padded with
         *  leading zeros or spaces, or with the number of digits prepended.
         *
         * @param sort_key  value number to sort on.
         *
         * @param reverse   If true, reverses the sort order.
         */
        void set_sort_by_value(Xapian::valueno sort_key, bool reverse);

        /** Set the sorting to be by key generated from values only.
         *
         * @param sorter    The functor to use for generating keys.
         *
         * @param reverse   If true, reverses the sort order.
         */
        void set_sort_by_key(Xapian::KeyMaker * sorter, bool reverse);

        /** Set the sorting to be by value, then by relevance for documents
         *  with the same value.
         *
         *  Note that sorting by values uses a string comparison, so to use
         *  this to sort by a numeric value you'll need to store the numeric
         *  values in a manner which sorts appropriately.  For example, you
         *  could use Xapian::sortable_serialise() (which works for floating
         *  point numbers as well as integers), or store numbers padded with
         *  leading zeros or spaces, or with the number of digits prepended.
         *
         * @param sort_key  value number to sort on.
         *
         * @param reverse   If true, reverses the sort order.
         */
        void set_sort_by_value_then_relevance(Xapian::valueno sort_key,
                                              bool reverse);

        /** Set the sorting to be by keys generated from values, then by
         *  relevance for documents with identical keys.
         *
         * @param sorter    The functor to use for generating keys.
         *
         * @param reverse   If true, reverses the sort order.
         */
        void set_sort_by_key_then_relevance(Xapian::KeyMaker * sorter,
                                            bool reverse);

        /** Set the sorting to be by relevance then value.
         *
         *  Note that sorting by values uses a string comparison, so to use
         *  this to sort by a numeric value you'll need to store the numeric
         *  values in a manner which sorts appropriately.  For example, you
         *  could use Xapian::sortable_serialise() (which works for floating
         *  point numbers as well as integers), or store numbers padded with
         *  leading zeros or spaces, or with the number of digits prepended.
         *
         *  Note that with the default BM25 weighting scheme parameters,
         *  non-identical documents will rarely have the same weight, so
         *  this setting will give very similar results to
         *  set_sort_by_relevance().  It becomes more useful with particular
         *  BM25 parameter settings (e.g. BM25Weight(1,0,1,0,0)) or custom
         *  weighting schemes.
         *
         * @param sort_key  value number to sort on.
         *
         * @param reverse   If true, reverses the sort order of sort_key.
         *                  Beware that in 1.2.16 and earlier, the sense
         *                  of this parameter was incorrectly inverted
         *                  and inconsistent with the other set_sort_by_...
         *                  methods.  This was fixed in 1.2.17, so make that
         *                  version a minimum requirement if this detail
         *                  matters to your application.
         */
        void set_sort_by_relevance_then_value(Xapian::valueno sort_key,
                                              bool reverse);

        /** Set the sorting to be by relevance, then by keys generated from
         *  values.
         *
         *  Note that with the default BM25 weighting scheme parameters,
         *  non-identical documents will rarely have the same weight, so
         *  this setting will give very similar results to
         *  set_sort_by_relevance().  It becomes more useful with particular
         *  BM25 parameter settings (e.g. BM25Weight(1,0,1,0,0)) or custom
         *  weighting schemes.
         *
         * @param sorter    The functor to use for generating keys.
         *
         * @param reverse   If true, reverses the sort order of the generated
         *                  keys.  Beware that in 1.2.16 and earlier, the sense
         *                  of this parameter was incorrectly inverted
         *                  and inconsistent with the other set_sort_by_...
         *                  methods.  This was fixed in 1.2.17, so make that
         *                  version a minimum requirement if this detail
         *                  matters to your application.
         */
        void set_sort_by_relevance_then_key(Xapian::KeyMaker * sorter,
                                            bool reverse);

        /** Set a time limit for the match.
         *
         *  Matches with check_at_least set high can take a long time in some
         *  cases.  You can set a time limit on this, after which check_at_least
         *  will be turned off.
         *
         *  @param time_limit  time in seconds after which to disable
         *                     check_at_least (default: 0.0 which means no
         *                     time limit)
         *
         *  Limitations:
         *
         *  This feature is currently supported on platforms which support POSIX
         *  interval timers.  Interaction with the remote backend when using
         *  multiple databases may have bugs.  There's not currently a way to
         *  force the match to end after a certain time.
         */
        void set_time_limit(double time_limit);

        /** Get (a portion of) the match set for the current query.
         *
         *  @param first     the first item in the result set to return.
         *                   A value of zero corresponds to the first item
         *                   returned being that with the highest score.
         *                   A value of 10 corresponds to the first 10 items
         *                   being ignored, and the returned items starting
         *                   at the eleventh.
         *  @param maxitems  the maximum number of items to return.  If you
         *                   want all matches, then you can pass the result
         *                   of calling get_doccount() on the Database object
         *                   (though if you are doing this so you can filter
         *                   results, you are likely to get much better
         *                   performance by using Xapian's match-time filtering
         *                   features instead).  You can pass 0 for maxitems
         *                   which will give you an empty MSet with valid
         *                   statistics (such as get_matches_estimated())
         *                   calculated without looking at any postings, which
         *                   is very quick, but means the estimates may be
         *                   more approximate and the bounds may be much
         *                   looser.
         *  @param checkatleast  the minimum number of items to check.  Because
         *                   the matcher optimises, it won't consider every
         *                   document which might match, so the total number
         *                   of matches is estimated.  Setting checkatleast
         *                   forces it to consider at least this many matches
         *                   and so allows for reliable paging links.
         *  @param omrset    the relevance set to use when performing the query.
         *  @param mdecider  a decision functor to use to decide whether a
         *                   given document should be put in the MSet.
         *
         *  @return          A Xapian::MSet object containing the results of the
         *                   query.
         *
         *  @exception Xapian::InvalidArgumentError  See class documentation.
         */
        MSet get_mset(Xapian::doccount first, Xapian::doccount maxitems,
                      Xapian::doccount checkatleast = 0,
                      const RSet * omrset = 0,
                      const MatchDecider * mdecider = 0) const;

        /** Get (a portion of) the match set for the current query.
         *
         *  @param first     the first item in the result set to return.
         *                   A value of zero corresponds to the first item
         *                   returned being that with the highest score.
         *                   A value of 10 corresponds to the first 10 items
         *                   being ignored, and the returned items starting
         *                   at the eleventh.
         *  @param maxitems  the maximum number of items to return.  If you
         *                   want all matches, then you can pass the result
         *                   of calling get_doccount() on the Database object
         *                   (though if you are doing this so you can filter
         *                   results, you are likely to get much better
         *                   performance by using Xapian's match-time filtering
         *                   features instead).  You can pass 0 for maxitems
         *                   which will give you an empty MSet with valid
         *                   statistics (such as get_matches_estimated())
         *                   calculated without looking at any postings, which
         *                   is very quick, but means the estimates may be
         *                   more approximate and the bounds may be much
         *                   looser.
         *  @param omrset    the relevance set to use when performing the query.
         *  @param mdecider  a decision functor to use to decide whether a
         *                   given document should be put in the MSet.
         *
         *  @return          A Xapian::MSet object containing the results of the
         *                   query.
         *
         *  @exception Xapian::InvalidArgumentError  See class documentation.
         */
        MSet get_mset(Xapian::doccount first, Xapian::doccount maxitems,
                      const RSet * omrset,
                      const MatchDecider * mdecider = 0) const {
            return get_mset(first, maxitems, 0, omrset, mdecider);
        }

        /** Terms in the query may be returned by get_eset().
         *
         *  The original intended use for Enquire::get_eset() is for query
         *  expansion - suggesting terms to add to the query, generally with
         *  the aim of improving recall (i.e. finding more of the relevant
         *  documents), so by default terms already in the query won't be
         *  returned in the ESet.  For some uses you might want to consider
         *  all terms, and this flag allows you to specify that.
         */
        static const int INCLUDE_QUERY_TERMS = 1;

        /** Calculate exact term frequencies in get_eset().
         *
         *  By default, when working over multiple databases,
         *  Enquire::get_eset() uses an approximation to the termfreq to
         *  improve efficiency.  This should still return good results, but
         *  if you want to calculate the exact combined termfreq then you
         *  can use this flag.
         */
        static const int USE_EXACT_TERMFREQ = 2;

        /** Get the expand set for the given rset.
         *
         *  @param maxitems  the maximum number of items to return.
         *  @param omrset    the relevance set to use when performing
         *                   the expand operation.
         *  @param flags     zero or more of these values |-ed together:
         *                    - Xapian::Enquire::INCLUDE_QUERY_TERMS query
         *                      terms may be returned from expand
         *                    - Xapian::Enquire::USE_EXACT_TERMFREQ for multi
         *                      dbs, calculate the exact termfreq; otherwise an
         *                      approximation is used which can greatly improve
         *                      efficiency, but still returns good results.
         *  @param edecider  a decision functor to use to decide whether a
         *                   given term should be put in the ESet
         *  @param min_wt    the minimum weight for included terms
         *
         *  @return          An ESet object containing the results of the
         *                   expand.
         *
         *  @exception Xapian::InvalidArgumentError  See class documentation.
         */
        ESet get_eset(Xapian::termcount maxitems,
                      const RSet & omrset,
                      int flags = 0,
                      const Xapian::ExpandDecider * edecider = 0,
                      double min_wt = 0.0) const;

        /** Get the expand set for the given rset.
         *
         *  @param maxitems  the maximum number of items to return.
         *  @param omrset    the relevance set to use when performing
         *                   the expand operation.
         *  @param edecider  a decision functor to use to decide whether a
         *                   given term should be put in the ESet
         *
         *  @return          An ESet object containing the results of the
         *                   expand.
         *
         *  @exception Xapian::InvalidArgumentError  See class documentation.
         */
        ESet get_eset(Xapian::termcount maxitems, const RSet & omrset,
                             const Xapian::ExpandDecider * edecider) const {
            return get_eset(maxitems, omrset, 0, edecider);
        }

        /** Get the expand set for the given rset.
         *
         *  @param maxitems  the maximum number of items to return.
         *  @param rset      the relevance set to use when performing
         *                   the expand operation.
         *  @param flags     zero or more of these values |-ed together:
         *                    - Xapian::Enquire::INCLUDE_QUERY_TERMS query
         *                      terms may be returned from expand
         *                    - Xapian::Enquire::USE_EXACT_TERMFREQ for multi
         *                      dbs, calculate the exact termfreq; otherwise an
         *                      approximation is used which can greatly improve
         *                      efficiency, but still returns good results.
         *  @param k         the parameter k in the query expansion algorithm
         *                   (default is 1.0)
         *  @param edecider  a decision functor to use to decide whether a
         *                   given term should be put in the ESet
         *
         *  @param min_wt    the minimum weight for included terms
         *
         *  @return          An ESet object containing the results of the
         *                   expand.
         *
         *  @exception Xapian::InvalidArgumentError  See class documentation.
         */
        XAPIAN_DEPRECATED(ESet get_eset(Xapian::termcount maxitems,
                          const RSet & rset,
                          int flags,
                          double k,
                          const Xapian::ExpandDecider * edecider = NULL,
                          double min_wt = 0.0) const) {
            set_expansion_scheme("trad", k);
            return get_eset(maxitems, rset, flags, edecider, min_wt);
        }

        /** Get terms which match a given document, by document id.
         *
         *  This method returns the terms in the current query which match
         *  the given document.
         *
         *  It is possible for the document to have been removed from the
         *  database between the time it is returned in an MSet, and the
         *  time that this call is made.  If possible, you should specify
         *  an MSetIterator instead of a Xapian::docid, since this will enable
         *  database backends with suitable support to prevent this
         *  occurring.
         *
         *  Note that a query does not need to have been run in order to
         *  make this call.
         *
         *  @param did     The document id for which to retrieve the matching
         *                 terms.
         *
         *  @return        An iterator returning the terms which match the
         *                 document.  The terms will be returned (as far as this
         *                 makes any sense) in the same order as the terms
         *                 in the query.  Terms will not occur more than once,
         *                 even if they do in the query.
         *
         *  @exception Xapian::InvalidArgumentError  See class documentation.
         *  @exception Xapian::DocNotFoundError      The document specified
         *      could not be found in the database.
         */
        TermIterator get_matching_terms_begin(Xapian::docid did) const;

        /** End iterator corresponding to get_matching_terms_begin() */
        TermIterator XAPIAN_NOTHROW(get_matching_terms_end(Xapian::docid /*did*/) const) {
            return TermIterator();
        }

        /** Get terms which match a given document, by match set item.
         *
         *  This method returns the terms in the current query which match
         *  the given document.
         *
         *  If the underlying database has suitable support, using this call
         *  (rather than passing a Xapian::docid) will enable the system to
         *  ensure that the correct data is returned, and that the document
         *  has not been deleted or changed since the query was performed.
         *
         *  @param it   The iterator for which to retrieve the matching terms.
         *
         *  @return     An iterator returning the terms which match the
         *                 document.  The terms will be returned (as far as this
         *                 makes any sense) in the same order as the terms
         *                 in the query.  Terms will not occur more than once,
         *                 even if they do in the query.
         *
         *  @exception Xapian::InvalidArgumentError  See class documentation.
         *  @exception Xapian::DocNotFoundError      The document specified
         *      could not be found in the database.
         */
        TermIterator get_matching_terms_begin(const MSetIterator &it) const;

        /** End iterator corresponding to get_matching_terms_begin() */
        TermIterator XAPIAN_NOTHROW(get_matching_terms_end(const MSetIterator &/*it*/) const) {
            return TermIterator();
        }

        /// Return a string describing this object.
        std::string get_description() const;
};

}

#endif /* XAPIAN_INCLUDED_ENQUIRE_H */