include/xapian/enquire.h

Go to the documentation of this file.

/* Copyright 1999,2000,2001 BrightStation PLC
 * Copyright 2001,2002 Ananova Ltd
 * Copyright 2002,2003,2004,2005,2006,2007,2009 Olly Betts
 *
 * 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

#include <string>

#include <xapian/base.h>
#include <xapian/deprecated.h>
#include <xapian/sorter.h>
#include <xapian/types.h>
#include <xapian/termiterator.h>
#include <xapian/visibility.h>

namespace Xapian {

class Database;
class Document;
class ErrorHandler;
class ExpandDecider;
class MSetIterator;
class Query;
class Weight;

class XAPIAN_VISIBILITY_DEFAULT MSet {
    public:
        class Internal;
        Xapian::Internal::RefCntPtr<Internal> internal;

        explicit MSet(MSet::Internal * internal_);

        MSet();

        ~MSet();

        MSet(const MSet & other);

        void operator=(const MSet &other);

        void fetch(const MSetIterator &begin, const MSetIterator &end) const;

        void fetch(const MSetIterator &item) const;

        void fetch() const;

        Xapian::percent convert_to_percent(Xapian::weight wt) const;

        Xapian::percent convert_to_percent(const MSetIterator &it) const;

        Xapian::doccount get_termfreq(const std::string &tname) const;

        Xapian::weight get_termweight(const std::string &tname) const;

        Xapian::doccount get_firstitem() const;

        Xapian::doccount get_matches_lower_bound() const;

        Xapian::doccount get_matches_estimated() const;

        Xapian::doccount get_matches_upper_bound() const;

        Xapian::weight get_max_possible() const;

        Xapian::weight get_max_attained() const;

        Xapian::doccount size() const;

        Xapian::doccount max_size() const { return size(); }

        bool empty() const;

        void swap(MSet & other);

        MSetIterator begin() const;

        MSetIterator end() const;

        MSetIterator back() const;

        MSetIterator operator[](Xapian::doccount i) const;


        typedef MSetIterator value_type; // FIXME: not assignable...
        typedef MSetIterator iterator;
        typedef MSetIterator const_iterator;
        typedef MSetIterator & reference; // Hmm
        typedef MSetIterator & const_reference;
        typedef MSetIterator * pointer; // Hmm
        typedef Xapian::doccount_diff difference_type;
        typedef Xapian::doccount size_type;

        std::string get_description() const;
};

class XAPIAN_VISIBILITY_DEFAULT MSetIterator {
    private:
        friend class MSet;
        friend bool operator==(const MSetIterator &a, const MSetIterator &b);
        friend bool operator!=(const MSetIterator &a, const MSetIterator &b);

        MSetIterator(Xapian::doccount index_, const MSet & mset_)
            : index(index_), mset(mset_) { }

        Xapian::doccount index;
        MSet mset;

    public:
        MSetIterator() : index(0), mset() { }

        ~MSetIterator() { }

        MSetIterator(const MSetIterator &other) {
            index = other.index;
            mset = other.mset;
        }

        void operator=(const MSetIterator &other) {
            index = other.index;
            mset = other.mset;
        }

        MSetIterator & operator++() {
            ++index;
            return *this;
        }

        MSetIterator operator++(int) {
            MSetIterator tmp = *this;
            ++index;
            return tmp;
        }

        MSetIterator & operator--() {
            --index;
            return *this;
        }

        MSetIterator operator--(int) {
            MSetIterator tmp = *this;
            --index;
            return tmp;
        }

        Xapian::docid operator*() const;

        Xapian::Document get_document() const;

        Xapian::doccount get_rank() const {
            return mset.get_firstitem() + index;
        }

        Xapian::weight get_weight() const;

        std::string get_collapse_key() const;

        Xapian::doccount get_collapse_count() const;

        Xapian::percent get_percent() const;

        std::string get_description() const;


        typedef std::bidirectional_iterator_tag iterator_category; // FIXME: could enhance to be a randomaccess_iterator
        typedef Xapian::docid value_type;
        typedef Xapian::doccount_diff difference_type;
        typedef Xapian::docid * pointer;
        typedef Xapian::docid & reference;
};

inline bool operator==(const MSetIterator &a, const MSetIterator &b)
{
    return (a.index == b.index);
}

inline bool operator!=(const MSetIterator &a, const MSetIterator &b)
{
    return (a.index != b.index);
}

class ESetIterator;

class XAPIAN_VISIBILITY_DEFAULT ESet {
    public:
        class Internal;
        Xapian::Internal::RefCntPtr<Internal> internal;

        ESet();

        ~ESet();

        ESet(const ESet & other);

        void operator=(const ESet &other);

        Xapian::termcount get_ebound() const;

        Xapian::termcount size() const;

        Xapian::termcount max_size() const { return size(); }

        bool empty() const;

        void swap(ESet & other);

        ESetIterator begin() const;

        ESetIterator end() const;

        ESetIterator back() const;

        ESetIterator operator[](Xapian::termcount i) const;

        std::string get_description() const;
};

class XAPIAN_VISIBILITY_DEFAULT ESetIterator {
    private:
        friend class ESet;
        friend bool operator==(const ESetIterator &a, const ESetIterator &b);
        friend bool operator!=(const ESetIterator &a, const ESetIterator &b);

        ESetIterator(Xapian::termcount index_, const ESet & eset_)
            : index(index_), eset(eset_) { }

        Xapian::termcount index;
        ESet eset;

    public:
        ESetIterator() : index(0), eset() { }

        ~ESetIterator() { }

        ESetIterator(const ESetIterator &other) {
            index = other.index;
            eset = other.eset;
        }

        void operator=(const ESetIterator &other) {
            index = other.index;
            eset = other.eset;
        }

        ESetIterator & operator++() {
            ++index;
            return *this;
        }

        ESetIterator operator++(int) {
            ESetIterator tmp = *this;
            ++index;
            return tmp;
        }

        ESetIterator & operator--() {
            --index;
            return *this;
        }

        ESetIterator operator--(int) {
            ESetIterator tmp = *this;
            --index;
            return tmp;
        }

        const std::string & operator *() const;

        Xapian::weight get_weight() const;

        std::string get_description() const;


        typedef std::bidirectional_iterator_tag iterator_category; // FIXME: go for randomaccess_iterator!
        typedef std::string value_type;
        typedef Xapian::termcount_diff difference_type;
        typedef std::string * pointer;
        typedef std::string & reference;
};

inline bool operator==(const ESetIterator &a, const ESetIterator &b)
{
    return (a.index == b.index);
}

inline bool operator!=(const ESetIterator &a, const ESetIterator &b)
{
    return (a.index != b.index);
}

class XAPIAN_VISIBILITY_DEFAULT RSet {
    public:
        class Internal;

        Xapian::Internal::RefCntPtr<Internal> internal;

        RSet(const RSet &rset);

        void operator=(const RSet &rset);

        RSet();

        ~RSet();

        Xapian::doccount size() const;

        bool empty() const;

        void add_document(Xapian::docid did);

        void add_document(const Xapian::MSetIterator & i) { add_document(*i); }

        void remove_document(Xapian::docid did);

        void remove_document(const Xapian::MSetIterator & i) { remove_document(*i); }

        bool contains(Xapian::docid did) const;

        bool contains(const Xapian::MSetIterator & i) const { return contains(*i); }

        std::string get_description() const;
};

class XAPIAN_VISIBILITY_DEFAULT MatchDecider {
    public:
        virtual bool operator()(const Xapian::Document &doc) const = 0;

        virtual ~MatchDecider();
};

class XAPIAN_VISIBILITY_DEFAULT Enquire {
    public:
        Enquire(const Enquire & other);

        void operator=(const Enquire & other);

        class Internal;
        Xapian::Internal::RefCntPtr<Internal> internal;

        explicit Enquire(const Database &database, ErrorHandler * errorhandler_ = 0);

        ~Enquire();

        void set_query(const Xapian::Query & query, Xapian::termcount qlen = 0);

        const Xapian::Query & get_query() const;

        void set_weighting_scheme(const Weight &weight_);

        void set_collapse_key(Xapian::valueno collapse_key);

        typedef enum {
            ASCENDING = 1,
            DESCENDING = 0,
            DONT_CARE = 2
        } docid_order;

        void set_docid_order(docid_order order);

        void set_cutoff(Xapian::percent percent_cutoff, Xapian::weight weight_cutoff = 0);

        void set_sort_by_relevance();

        void set_sort_by_value(Xapian::valueno sort_key, bool reverse = true);

        void set_sort_by_key(Xapian::Sorter * sorter, bool reverse = true);

        void set_sort_by_value_then_relevance(Xapian::valueno sort_key,
                                              bool reverse = true);

        void set_sort_by_key_then_relevance(Xapian::Sorter * sorter,
                                            bool reverse = true);

        void set_sort_by_relevance_then_value(Xapian::valueno sort_key,
                                              bool reverse = true);

        void set_sort_by_relevance_then_key(Xapian::Sorter * sorter,
                                            bool reverse = true);

        MSet get_mset(Xapian::doccount first, Xapian::doccount maxitems,
                      Xapian::doccount checkatleast = 0,
                      const RSet * omrset = 0,
                      const MatchDecider * mdecider = 0) const;
        MSet get_mset(Xapian::doccount first, Xapian::doccount maxitems,
                      Xapian::doccount checkatleast,
                      const RSet * omrset,
                      const MatchDecider * mdecider,
                      const MatchDecider * matchspy) const;
        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);
        }

        static const int INCLUDE_QUERY_TERMS = 1;
        static const int USE_EXACT_TERMFREQ = 2;
#ifndef _MSC_VER
        XAPIAN_DEPRECATED(static const int include_query_terms) = 1;
        XAPIAN_DEPRECATED(static const int use_exact_termfreq) = 2;
#else
        // Work around MSVC stupidity (you get a warning for deprecating a
        // declaration).
        static const int include_query_terms = 1;
        static const int use_exact_termfreq = 2;
#pragma deprecated("Xapian::Enquire::include_query_terms", "Xapian::Enquire::use_exact_termfreq")
#endif

        ESet get_eset(Xapian::termcount maxitems,
                        const RSet & omrset,
                        int flags = 0,
                        double k = 1.0,
                        const Xapian::ExpandDecider * edecider = 0) const;

        inline ESet get_eset(Xapian::termcount maxitems, const RSet & omrset,
                               const Xapian::ExpandDecider * edecider) const {
            return get_eset(maxitems, omrset, 0, 1.0, edecider);
        }

        TermIterator get_matching_terms_begin(Xapian::docid did) const;

        TermIterator get_matching_terms_end(Xapian::docid /*did*/) const {
            return TermIterator(NULL);
        }

        TermIterator get_matching_terms_begin(const MSetIterator &it) const;

        TermIterator get_matching_terms_end(const MSetIterator &/*it*/) const {
            return TermIterator(NULL);
        }

        XAPIAN_DEPRECATED(
        void register_match_decider(const std::string &name,
                                    const MatchDecider *mdecider = NULL));

        std::string get_description() const;
};

}

class RemoteServer;
class ScaleWeight;

namespace Xapian {

class XAPIAN_VISIBILITY_DEFAULT Weight {
    friend class Enquire; // So Enquire can clone us
    friend class ::RemoteServer; // So RemoteServer can clone us - FIXME
    friend class ::ScaleWeight;
    public:
        class Internal;
    protected:
        Weight(const Weight &);
    private:
        void operator=(Weight &);

        virtual Weight * clone() const = 0;

    protected:
        const Internal * internal; // Weight::Internal == Stats
        Xapian::doclength querysize;
        Xapian::termcount wqf;
        std::string tname;

    public:
        // FIXME:1.1: initialise internal to NULL here
        Weight() { }
        virtual ~Weight();

        Weight * create(const Internal * internal_, Xapian::doclength querysize_,
                        Xapian::termcount wqf_, const std::string & tname_) const;

        virtual std::string name() const = 0;

        virtual std::string serialise() const = 0;

        virtual Weight * unserialise(const std::string &s) const = 0;

        virtual Xapian::weight get_sumpart(Xapian::termcount wdf,
                                      Xapian::doclength len) const = 0;

        virtual Xapian::weight get_maxpart() const = 0;

        virtual Xapian::weight get_sumextra(Xapian::doclength len) const = 0;

        virtual Xapian::weight get_maxextra() const = 0;

        virtual bool get_sumpart_needs_doclength() const; /* { return true; } */
};

class XAPIAN_VISIBILITY_DEFAULT BoolWeight : public Weight {
    public:
        BoolWeight * clone() const;
        BoolWeight() { }
        ~BoolWeight();
        std::string name() const;
        std::string serialise() const;
        BoolWeight * unserialise(const std::string & s) const;
        Xapian::weight get_sumpart(Xapian::termcount wdf, Xapian::doclength len) const;
        Xapian::weight get_maxpart() const;

        Xapian::weight get_sumextra(Xapian::doclength len) const;
        Xapian::weight get_maxextra() const;

        bool get_sumpart_needs_doclength() const;
};

class XAPIAN_VISIBILITY_DEFAULT BM25Weight : public Weight {
    private:
        mutable Xapian::weight termweight;
        mutable Xapian::doclength lenpart;

        double k1, k2, k3, b;
        Xapian::doclength min_normlen;

        mutable bool weight_calculated;

        void calc_termweight() const;

    public:
        BM25Weight(double k1_, double k2_, double k3_, double b_,
                   double min_normlen_)
                : k1(k1_), k2(k2_), k3(k3_), b(b_), min_normlen(min_normlen_),
                  weight_calculated(false)
        {
            if (k1 < 0) k1 = 0;
            if (k2 < 0) k2 = 0;
            if (k3 < 0) k3 = 0;
            if (b < 0) b = 0; else if (b > 1) b = 1;
        }
        BM25Weight() : k1(1), k2(0), k3(1), b(0.5), min_normlen(0.5),
                       weight_calculated(false) { }

        BM25Weight * clone() const;
        ~BM25Weight() { }
        std::string name() const;
        std::string serialise() const;
        BM25Weight * unserialise(const std::string & s) const;
        Xapian::weight get_sumpart(Xapian::termcount wdf, Xapian::doclength len) const;
        Xapian::weight get_maxpart() const;

        Xapian::weight get_sumextra(Xapian::doclength len) const;
        Xapian::weight get_maxextra() const;

        bool get_sumpart_needs_doclength() const;
};

class XAPIAN_VISIBILITY_DEFAULT TradWeight : public Weight {
    private:
        mutable Xapian::weight termweight;
        mutable Xapian::doclength lenpart;

        double param_k;

        mutable bool weight_calculated;

        void calc_termweight() const;

    public:
        explicit TradWeight(double k) : param_k(k), weight_calculated(false) {
            if (param_k < 0) param_k = 0;
        }

        TradWeight() : param_k(1.0), weight_calculated(false) { }

        TradWeight * clone() const;
        ~TradWeight() { }
        std::string name() const;
        std::string serialise() const;
        TradWeight * unserialise(const std::string & s) const;

        Xapian::weight get_sumpart(Xapian::termcount wdf, Xapian::doclength len) const;
        Xapian::weight get_maxpart() const;

        Xapian::weight get_sumextra(Xapian::doclength len) const;
        Xapian::weight get_maxextra() const;

        bool get_sumpart_needs_doclength() const;
};

}

#endif /* XAPIAN_INCLUDED_ENQUIRE_H */

---