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,2008,2009,2011 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

#include <string>

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

namespace Xapian {

class Database;
class Document;
class ErrorHandler;
class ExpandDecider;
class MatchSpy;
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::doccount get_uncollapsed_matches_lower_bound() const;

        Xapian::doccount get_uncollapsed_matches_estimated() const;

        Xapian::doccount get_uncollapsed_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(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(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 add_matchspy(MatchSpy * spy);

        void clear_matchspies();

        void set_weighting_scheme(const Weight &weight_);

        void set_collapse_key(Xapian::valueno collapse_key,
                              Xapian::doccount collapse_max = 1);

        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);

        XAPIAN_DEPRECATED(void set_sort_by_value(Xapian::valueno sort_key));

        void set_sort_by_key(Xapian::KeyMaker * sorter, bool reverse);

        XAPIAN_DEPRECATED(void set_sort_by_key(Xapian::KeyMaker * sorter));

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

        XAPIAN_DEPRECATED(void set_sort_by_value_then_relevance(Xapian::valueno sort_key));

        void set_sort_by_key_then_relevance(Xapian::KeyMaker * sorter,
                                            bool reverse);

        XAPIAN_DEPRECATED(void set_sort_by_key_then_relevance(Xapian::KeyMaker * sorter));

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

        XAPIAN_DEPRECATED(void set_sort_by_relevance_then_value(Xapian::valueno sort_key));

        void set_sort_by_relevance_then_key(Xapian::KeyMaker * sorter,
                                            bool reverse);

        XAPIAN_DEPRECATED(void set_sort_by_relevance_then_key(Xapian::KeyMaker * sorter));

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

        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);
        }

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

        TermIterator get_matching_terms_begin(Xapian::docid did) const;

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

        TermIterator get_matching_terms_begin(const MSetIterator &it) const;

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

        std::string get_description() const;
};

// Deprecated forms:

inline void
Enquire::set_sort_by_value(Xapian::valueno sort_key)
{
    return set_sort_by_value(sort_key, true);
}

inline void
Enquire::set_sort_by_key(Xapian::KeyMaker * sorter)
{
    return set_sort_by_key(sorter, true);
}

inline void
Enquire::set_sort_by_value_then_relevance(Xapian::valueno sort_key)
{
    return set_sort_by_value_then_relevance(sort_key, true);
}

inline void
Enquire::set_sort_by_key_then_relevance(Xapian::KeyMaker * sorter)
{
    return set_sort_by_key_then_relevance(sorter, true);
}

inline void
Enquire::set_sort_by_relevance_then_value(Xapian::valueno sort_key)
{
    return set_sort_by_relevance_then_value(sort_key, true);
}

inline void
Enquire::set_sort_by_relevance_then_key(Xapian::KeyMaker * sorter)
{
    return set_sort_by_relevance_then_key(sorter, true);
}

}

#endif /* XAPIAN_INCLUDED_ENQUIRE_H */

---