# include/xapian/enquire.h

Go to the documentation of this file.

    00001
    00004 /* Copyright 1999,2000,2001 BrightStation PLC
    00005  * Copyright 2001,2002 Ananova Ltd
    00006  * Copyright 2002,2003,2004,2005,2006,2007 Olly Betts
    00007  *
    00008  * This program is free software; you can redistribute it and/or
    00009  * modify it under the terms of the GNU General Public License as
    00010  * published by the Free Software Foundation; either version 2 of the
    00011  * License, or (at your option) any later version.
    00012  *
    00013  * This program is distributed in the hope that it will be useful,
    00014  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    00015  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    00016  * GNU General Public License for more details.
    00017  *
    00018  * You should have received a copy of the GNU General Public License
    00019  * along with this program; if not, write to the Free Software
    00020  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
    00021  * USA
    00022  */
    00023
    00024 #ifndef XAPIAN_INCLUDED_ENQUIRE_H
    00025 #define XAPIAN_INCLUDED_ENQUIRE_H
    00026
    00027 #include <string>
    00028
    00029 #include <xapian/base.h>
    00030 #include <xapian/deprecated.h>
    00031 #include <xapian/sorter.h>
    00032 #include <xapian/types.h>
    00033 #include <xapian/termiterator.h>
    00034 #include <xapian/visibility.h>
    00035
    00036 namespace Xapian {
    00037
    00038 class Database;
    00039 class Document;
    00040 class ErrorHandler;
    00041 class ExpandDecider;
    00042 class MSetIterator;
    00043 class Query;
    00044 class Weight;
    00045
    00049 class XAPIAN_VISIBILITY_DEFAULT MSet {
    00050     public:
    00051         class Internal;
    00053         Xapian::Internal::RefCntPtr<Internal> internal;
    00054
    00056         explicit MSet(MSet::Internal * internal_);
    00057
    00059         MSet();
    00060
    00062         ~MSet();
    00063
    00065         MSet(const MSet & other);
    00066
    00068         void operator=(const MSet &other);
    00069
    00085         void fetch(const MSetIterator &begin, const MSetIterator &end) const;
    00086
    00089         void fetch(const MSetIterator &item) const;
    00090
    00093         void fetch() const;
    00094
    00099         Xapian::percent convert_to_percent(Xapian::weight wt) const;
    00100
    00102         Xapian::percent convert_to_percent(const MSetIterator &it) const;
    00103
    00111         Xapian::doccount get_termfreq(const std::string &tname) const;
    00112
    00120         Xapian::weight get_termweight(const std::string &tname) const;
    00121
    00129         Xapian::doccount get_firstitem() const;
    00130
    00140         Xapian::doccount get_matches_lower_bound() const;
    00141
    00154         Xapian::doccount get_matches_estimated() const;
    00155
    00165         Xapian::doccount get_matches_upper_bound() const;
    00166
    00172         Xapian::weight get_max_possible() const;
    00173
    00187         Xapian::weight get_max_attained() const;
    00188
    00190         Xapian::doccount size() const;
    00191
    00193         Xapian::doccount max_size() const { return size(); }
    00194
    00196         bool empty() const;
    00197
    00199         void swap(MSet & other);
    00200
    00202         MSetIterator begin() const;
    00203
    00205         MSetIterator end() const;
    00206
    00208         MSetIterator back() const;
    00209
    00219         MSetIterator operator[](Xapian::doccount i) const;
    00220
    00222
    00223         typedef MSetIterator value_type; // FIXME: not assignable...
    00224         typedef MSetIterator iterator;
    00225         typedef MSetIterator const_iterator;
    00226         typedef MSetIterator & reference; // Hmm
    00227         typedef MSetIterator & const_reference;
    00228         typedef MSetIterator * pointer; // Hmm
    00229         typedef Xapian::doccount_diff difference_type;
    00230         typedef Xapian::doccount size_type;
    00232
    00234         std::string get_description() const;
    00235 };
    00236
    00240 class XAPIAN_VISIBILITY_DEFAULT MSetIterator {
    00241     private:
    00242         friend class MSet;
    00243         friend bool operator==(const MSetIterator &a, const MSetIterator &b);
    00244         friend bool operator!=(const MSetIterator &a, const MSetIterator &b);
    00245
    00246         MSetIterator(Xapian::doccount index_, const MSet & mset_)
    00247             : index(index_), mset(mset_) { }
    00248
    00249         Xapian::doccount index;
    00250         MSet mset;
    00251
    00252     public:
    00256         MSetIterator() : index(0), mset() { }
    00257
    00258         ~MSetIterator() { }
    00259
    00261         MSetIterator(const MSetIterator &other) {
    00262             index = other.index;
    00263             mset = other.mset;
    00264         }
    00265
    00267         void operator=(const MSetIterator &other) {
    00268             index = other.index;
    00269             mset = other.mset;
    00270         }
    00271
    00273         MSetIterator & operator++() {
    00274             ++index;
    00275             return *this;
    00276         }
    00277
    00279         MSetIterator operator++(int) {
    00280             MSetIterator tmp = *this;
    00281             ++index;
    00282             return tmp;
    00283         }
    00284
    00286         MSetIterator & operator--() {
    00287             --index;
    00288             return *this;
    00289         }
    00290
    00292         MSetIterator operator--(int) {
    00293             MSetIterator tmp = *this;
    00294             --index;
    00295             return tmp;
    00296         }
    00297
    00299         Xapian::docid operator*() const;
    00300
    00317         Xapian::Document get_document() const;
    00318
    00325         Xapian::doccount get_rank() const {
    00326             return mset.get_firstitem() + index;
    00327         }
    00328
    00330         Xapian::weight get_weight() const;
    00331
    00334         std::string get_collapse_key() const;
    00335
    00352         Xapian::doccount get_collapse_count() const;
    00353
    00359         Xapian::percent get_percent() const;
    00360
    00362         std::string get_description() const;
    00363
    00365
    00366         typedef std::bidirectional_iterator_tag iterator_category; // FIXME: could enhance to be a randomaccess_iterator
    00367         typedef Xapian::docid value_type;
    00368         typedef Xapian::doccount_diff difference_type;
    00369         typedef Xapian::docid * pointer;
    00370         typedef Xapian::docid & reference;
    00372 };
    00373
    00374 inline bool operator==(const MSetIterator &a, const MSetIterator &b)
    00375 {
    00376     return (a.index == b.index);
    00377 }
    00378
    00379 inline bool operator!=(const MSetIterator &a, const MSetIterator &b)
    00380 {
    00381     return (a.index != b.index);
    00382 }
    00383
    00384 class ESetIterator;
    00385
    00390 class XAPIAN_VISIBILITY_DEFAULT ESet {
    00391     public:
    00392         class Internal;
    00394         Xapian::Internal::RefCntPtr<Internal> internal;
    00395
    00397         ESet();
    00398
    00400         ~ESet();
    00401
    00403         ESet(const ESet & other);
    00404
    00406         void operator=(const ESet &other);
    00407
    00412         Xapian::termcount get_ebound() const;
    00413
    00415         Xapian::termcount size() const;
    00416
    00418         Xapian::termcount max_size() const { return size(); }
    00419
    00421         bool empty() const;
    00422
    00424         void swap(ESet & other);
    00425
    00427         ESetIterator begin() const;
    00428
    00430         ESetIterator end() const;
    00431
    00433         ESetIterator back() const;
    00434
    00436         ESetIterator operator[](Xapian::termcount i) const;
    00437
    00439         std::string get_description() const;
    00440 };
    00441
    00443 class XAPIAN_VISIBILITY_DEFAULT ESetIterator {
    00444     private:
    00445         friend class ESet;
    00446         friend bool operator==(const ESetIterator &a, const ESetIterator &b);
    00447         friend bool operator!=(const ESetIterator &a, const ESetIterator &b);
    00448
    00449         ESetIterator(Xapian::termcount index_, const ESet & eset_)
    00450             : index(index_), eset(eset_) { }
    00451
    00452         Xapian::termcount index;
    00453         ESet eset;
    00454
    00455     public:
    00459         ESetIterator() : index(0), eset() { }
    00460
    00461         ~ESetIterator() { }
    00462
    00464         ESetIterator(const ESetIterator &other) {
    00465             index = other.index;
    00466             eset = other.eset;
    00467         }
    00468
    00470         void operator=(const ESetIterator &other) {
    00471             index = other.index;
    00472             eset = other.eset;
    00473         }
    00474
    00476         ESetIterator & operator++() {
    00477             ++index;
    00478             return *this;
    00479         }
    00480
    00482         ESetIterator operator++(int) {
    00483             ESetIterator tmp = *this;
    00484             ++index;
    00485             return tmp;
    00486         }
    00487
    00489         ESetIterator & operator--() {
    00490             --index;
    00491             return *this;
    00492         }
    00493
    00495         ESetIterator operator--(int) {
    00496             ESetIterator tmp = *this;
    00497             --index;
    00498             return tmp;
    00499         }
    00500
    00502         const std::string & operator *() const;
    00503
    00505         Xapian::weight get_weight() const;
    00506
    00508         std::string get_description() const;
    00509
    00511
    00512         typedef std::bidirectional_iterator_tag iterator_category; // FIXME: go for randomaccess_iterator!
    00513         typedef std::string value_type;
    00514         typedef Xapian::termcount_diff difference_type;
    00515         typedef std::string * pointer;
    00516         typedef std::string & reference;
    00518 };
    00519
    00520 inline bool operator==(const ESetIterator &a, const ESetIterator &b)
    00521 {
    00522     return (a.index == b.index);
    00523 }
    00524
    00525 inline bool operator!=(const ESetIterator &a, const ESetIterator &b)
    00526 {
    00527     return (a.index != b.index);
    00528 }
    00529
    00534 class XAPIAN_VISIBILITY_DEFAULT RSet {
    00535     public:
    00537         class Internal;
    00538
    00540         Xapian::Internal::RefCntPtr<Internal> internal;
    00541
    00543         RSet(const RSet &rset);
    00544
    00546         void operator=(const RSet &rset);
    00547
    00549         RSet();
    00550
    00552         ~RSet();
    00553
    00555         Xapian::doccount size() const;
    00556
    00558         bool empty() const;
    00559
    00561         void add_document(Xapian::docid did);
    00562
    00564         void add_document(const Xapian::MSetIterator & i) { add_document(*i); }
    00565
    00567         void remove_document(Xapian::docid did);
    00568
    00570         void remove_document(const Xapian::MSetIterator & i) { remove_document(*i); }
    00571
    00573         bool contains(Xapian::docid did) const;
    00574
    00576         bool contains(const Xapian::MSetIterator & i) const { return contains(*i); }
    00577
    00579         std::string get_description() const;
    00580 };
    00581
    00584 class XAPIAN_VISIBILITY_DEFAULT MatchDecider {
    00585     public:
    00591         virtual bool operator()(const Xapian::Document &doc) const = 0;
    00592
    00594         virtual ~MatchDecider();
    00595 };
    00596
    00607 class XAPIAN_VISIBILITY_DEFAULT Enquire {
    00608     public:
    00610         Enquire(const Enquire & other);
    00611
    00613         void operator=(const Enquire & other);
    00614
    00615         class Internal;
    00617         Xapian::Internal::RefCntPtr<Internal> internal;
    00618
    00643         explicit Enquire(const Database &database, ErrorHandler * errorhandler_ = 0);
    00644
    00647         ~Enquire();
    00648
    00655         void set_query(const Xapian::Query & query, Xapian::termcount qlen = 0);
    00656
    00663         const Xapian::Query & get_query() const;
    00664
    00671         void set_weighting_scheme(const Weight &weight_);
    00672
    00699         void set_collapse_key(Xapian::valueno collapse_key);
    00700
    00701         typedef enum {
    00702             ASCENDING = 1,
    00703             DESCENDING = 0,
    00704             DONT_CARE = 2
    00705         } docid_order;
    00706
    00730         void set_docid_order(docid_order order);
    00731
    00750         void set_cutoff(Xapian::percent percent_cutoff, Xapian::weight weight_cutoff = 0);
    00751
    00756         void set_sort_by_relevance();
    00757
    00770         void set_sort_by_value(Xapian::valueno sort_key, bool ascending = true);
    00771
    00780         void set_sort_by_key(Xapian::Sorter * sorter, bool ascending = true);
    00781
    00795         void set_sort_by_value_then_relevance(Xapian::valueno sort_key,
    00796                                               bool ascending = true);
    00797
    00807         void set_sort_by_key_then_relevance(Xapian::Sorter * sorter,
    00808                                             bool ascending = true);
    00809
    00829         void set_sort_by_relevance_then_value(Xapian::valueno sort_key,
    00830                                               bool ascending = true);
    00831
    00848         void set_sort_by_relevance_then_key(Xapian::Sorter * sorter,
    00849                                             bool ascending = true);
    00850
    00883         MSet get_mset(Xapian::doccount first, Xapian::doccount maxitems,
    00884                       Xapian::doccount checkatleast = 0,
    00885                       const RSet * omrset = 0,
    00886                       const MatchDecider * mdecider = 0) const;
    00887         MSet get_mset(Xapian::doccount first, Xapian::doccount maxitems,
    00888                       Xapian::doccount checkatleast,
    00889                       const RSet * omrset,
    00890                       const MatchDecider * mdecider,
    00891                       const MatchDecider * matchspy) const;
    00892         MSet get_mset(Xapian::doccount first, Xapian::doccount maxitems,
    00893                       const RSet * omrset,
    00894                       const MatchDecider * mdecider = 0) const {
    00895             return get_mset(first, maxitems, 0, omrset, mdecider);
    00896         }
    00897
    00898         static const int INCLUDE_QUERY_TERMS = 1;
    00899         static const int USE_EXACT_TERMFREQ = 2;
    00900 #ifndef _MSC_VER
    00902         XAPIAN_DEPRECATED(static const int include_query_terms) = 1;
    00904         XAPIAN_DEPRECATED(static const int use_exact_termfreq) = 2;
    00905 #else
    00906         // Work around MSVC stupidity (you get a warning for deprecating a
    00907         // declaration).
    00908         static const int include_query_terms = 1;
    00909         static const int use_exact_termfreq = 2;
    00910 #pragma deprecated("Xapian::Enquire::include_query_terms", "Xapian::Enquire::use_exact_termfreq")
    00911 #endif
    00912
    00935         ESet get_eset(Xapian::termcount maxitems,
    00936                         const RSet & omrset,
    00937                         int flags = 0,
    00938                         double k = 1.0,
    00939                         const Xapian::ExpandDecider * edecider = 0) const;
    00940
    00954         inline ESet get_eset(Xapian::termcount maxitems, const RSet & omrset,
    00955                                const Xapian::ExpandDecider * edecider) const {
    00956             return get_eset(maxitems, omrset, 0, 1.0, edecider);
    00957         }
    00958
    00987         TermIterator get_matching_terms_begin(Xapian::docid did) const;
    00988
    00990         TermIterator get_matching_terms_end(Xapian::docid /*did*/) const {
    00991             return TermIterator(NULL);
    00992         }
    00993
    01016         TermIterator get_matching_terms_begin(const MSetIterator &it) const;
    01017
    01019         TermIterator get_matching_terms_end(const MSetIterator &/*it*/) const {
    01020             return TermIterator(NULL);
    01021         }
    01022
    01035         XAPIAN_DEPRECATED(
    01036         void register_match_decider(const std::string &name,
    01037                                     const MatchDecider *mdecider = NULL));
    01038
    01040         std::string get_description() const;
    01041 };
    01042
    01043 }
    01044
    01045 class RemoteServer;
    01046 class ScaleWeight;
    01047
    01048 namespace Xapian {
    01049
    01051 class XAPIAN_VISIBILITY_DEFAULT Weight {
    01052     friend class Enquire; // So Enquire can clone us
    01053     friend class ::RemoteServer; // So RemoteServer can clone us - FIXME
    01054     friend class ::ScaleWeight;
    01055     public:
    01056         class Internal;
    01057     protected:
    01058         Weight(const Weight &);
    01059     private:
    01060         void operator=(Weight &);
    01061
    01071         virtual Weight * clone() const = 0;
    01072
    01073     protected:
    01074         const Internal * internal; // Weight::Internal == Stats
    01075         Xapian::doclength querysize;
    01076         Xapian::termcount wqf;
    01077         std::string tname;
    01078
    01079     public:
    01080         // FIXME:1.1: initialise internal to NULL here
    01081         Weight() { }
    01082         virtual ~Weight();
    01083
    01096         Weight * create(const Internal * internal_, Xapian::doclength querysize_,
    01097                         Xapian::termcount wqf_, const std::string & tname_) const;
    01098
    01103         virtual std::string name() const = 0;
    01104
    01106         virtual std::string serialise() const = 0;
    01107
    01109         virtual Weight * unserialise(const std::string &s) const = 0;
    01110
    01118         virtual Xapian::weight get_sumpart(Xapian::termcount wdf,
    01119                                       Xapian::doclength len) const = 0;
    01120
    01126         virtual Xapian::weight get_maxpart() const = 0;
    01127
    01136         virtual Xapian::weight get_sumextra(Xapian::doclength len) const = 0;
    01137
    01141         virtual Xapian::weight get_maxextra() const = 0;
    01142
    01144         virtual bool get_sumpart_needs_doclength() const; /* { return true; } */
    01145 };
    01146
    01148 class XAPIAN_VISIBILITY_DEFAULT BoolWeight : public Weight {
    01149     public:
    01150         BoolWeight * clone() const;
    01151         BoolWeight() { }
    01152         ~BoolWeight();
    01153         std::string name() const;
    01154         std::string serialise() const;
    01155         BoolWeight * unserialise(const std::string & s) const;
    01156         Xapian::weight get_sumpart(Xapian::termcount wdf, Xapian::doclength len) const;
    01157         Xapian::weight get_maxpart() const;
    01158
    01159         Xapian::weight get_sumextra(Xapian::doclength len) const;
    01160         Xapian::weight get_maxextra() const;
    01161
    01162         bool get_sumpart_needs_doclength() const;
    01163 };
    01164
    01177 class XAPIAN_VISIBILITY_DEFAULT BM25Weight : public Weight {
    01178     private:
    01179         mutable Xapian::weight termweight;
    01180         mutable Xapian::doclength lenpart;
    01181
    01182         double k1, k2, k3, b;
    01183         Xapian::doclength min_normlen;
    01184
    01185         mutable bool weight_calculated;
    01186
    01187         void calc_termweight() const;
    01188
    01189     public:
    01208         BM25Weight(double k1_, double k2_, double k3_, double b_,
    01209                    double min_normlen_)
    01210                 : k1(k1_), k2(k2_), k3(k3_), b(b_), min_normlen(min_normlen_),
    01211                   weight_calculated(false)
    01212         {
    01213             if (k1 < 0) k1 = 0;
    01214             if (k2 < 0) k2 = 0;
    01215             if (k3 < 0) k3 = 0;
    01216             if (b < 0) b = 0; else if (b > 1) b = 1;
    01217         }
    01218         BM25Weight() : k1(1), k2(0), k3(1), b(0.5), min_normlen(0.5),
    01219                        weight_calculated(false) { }
    01220
    01221         BM25Weight * clone() const;
    01222         ~BM25Weight() { }
    01223         std::string name() const;
    01224         std::string serialise() const;
    01225         BM25Weight * unserialise(const std::string & s) const;
    01226         Xapian::weight get_sumpart(Xapian::termcount wdf, Xapian::doclength len) const;
    01227         Xapian::weight get_maxpart() const;
    01228
    01229         Xapian::weight get_sumextra(Xapian::doclength len) const;
    01230         Xapian::weight get_maxextra() const;
    01231
    01232         bool get_sumpart_needs_doclength() const;
    01233 };
    01234
    01252 class XAPIAN_VISIBILITY_DEFAULT TradWeight : public Weight {
    01253     private:
    01254         mutable Xapian::weight termweight;
    01255         mutable Xapian::doclength lenpart;
    01256
    01257         double param_k;
    01258
    01259         mutable bool weight_calculated;
    01260
    01261         void calc_termweight() const;
    01262
    01263     public:
    01271         explicit TradWeight(double k) : param_k(k), weight_calculated(false) {
    01272             if (param_k < 0) param_k = 0;
    01273         }
    01274
    01275         TradWeight() : param_k(1.0), weight_calculated(false) { }
    01276
    01277         TradWeight * clone() const;
    01278         ~TradWeight() { }
    01279         std::string name() const;
    01280         std::string serialise() const;
    01281         TradWeight * unserialise(const std::string & s) const;
    01282
    01283         Xapian::weight get_sumpart(Xapian::termcount wdf, Xapian::doclength len) const;
    01284         Xapian::weight get_maxpart() const;
    01285
    01286         Xapian::weight get_sumextra(Xapian::doclength len) const;
    01287         Xapian::weight get_maxextra() const;
    01288
    01289         bool get_sumpart_needs_doclength() const;
    01290 };
    01291
    01292 }
    01293
    01294 #endif /* XAPIAN_INCLUDED_ENQUIRE_H */