query.h

Go to the documentation of this file.

 
/* Copyright (C) 2011-2026 Olly Betts
 * Copyright (C) 2008 Richard Boulton
 *
 * 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, see
 * <https://www.gnu.org/licenses/>.
 */
 
#ifndef XAPIAN_INCLUDED_QUERY_H
#define XAPIAN_INCLUDED_QUERY_H
 
#if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
# error Never use <xapian/query.h> directly; include <xapian.h> instead.
#endif
 
#include <string>
#include <string_view>
 
#include <xapian/attributes.h>
#include <xapian/intrusive_ptr.h>
#include <xapian/postingiterator.h>
#include <xapian/registry.h>
#include <xapian/termiterator.h>
#include <xapian/types.h>
#include <xapian/visibility.h>
 
namespace Xapian {
 
class PostingSource;
 
class XAPIAN_VISIBILITY_DEFAULT Query {
  public:
    class Internal;
    Xapian::Internal::intrusive_ptr<Internal> internal;
 
    static const Xapian::Query MatchNothing;
 
    static const Xapian::Query MatchAll;
 
    enum op {
        OP_AND = 0,
 
        OP_OR = 1,
 
        OP_AND_NOT = 2,
 
        OP_XOR = 3,
 
        OP_AND_MAYBE = 4,
 
        OP_FILTER = 5,
 
        OP_NEAR = 6,
 
        OP_PHRASE = 7,
 
        OP_VALUE_RANGE = 8,
 
        OP_SCALE_WEIGHT = 9,
 
        OP_ELITE_SET = 10,
 
        OP_VALUE_GE = 11,
 
        OP_VALUE_LE = 12,
 
        OP_SYNONYM = 13,
 
        OP_MAX = 14,
 
        OP_WILDCARD = 15,
 
        OP_EDIT_DISTANCE = 16,
 
        OP_INVALID = 99,
 
        LEAF_TERM = 100,
 
        LEAF_POSTING_SOURCE,
 
        LEAF_MATCH_ALL,
 
        LEAF_MATCH_NOTHING
    };
 
    enum {
        WILDCARD_LIMIT_ERROR = 0x00,
        WILDCARD_LIMIT_FIRST = 0x01,
        WILDCARD_LIMIT_MOST_FREQUENT = 0x02,
 
        WILDCARD_LIMIT_MASK_ = 0x03,
 
        WILDCARD_PATTERN_MULTI = 0x10,
 
        WILDCARD_PATTERN_SINGLE = 0x20,
 
        WILDCARD_PATTERN_GLOB = WILDCARD_PATTERN_MULTI|WILDCARD_PATTERN_SINGLE
    };
 
    Query() noexcept { }
 
    ~Query() { }
 
    Query(const Query & o) : internal(o.internal) { }
 
    Query & operator=(const Query & o) { internal = o.internal; return *this; }
 
    Query(Query &&) = default;
 
    Query & operator=(Query &&) = default;
 
    Query(const std::string& term,
          Xapian::termcount wqf = 1,
          Xapian::termpos pos = 0)
        : Query(std::string_view(term), wqf, pos)
    { }
 
    Query(const char* term,
          Xapian::termcount wqf = 1,
          Xapian::termpos pos = 0)
        : Query(std::string_view(term), wqf, pos)
    { }
 
    Query(std::string_view term,
          Xapian::termcount wqf = 1,
          Xapian::termpos pos = 0);
 
    explicit Query(Xapian::PostingSource * source);
 
    Query(double factor, const Xapian::Query & subquery);
 
    Query(op op_, const Xapian::Query & subquery, double factor);
 
    Query(op op_, const Xapian::Query & a, const Xapian::Query & b)
    {
        init(op_, 2);
        bool positional = (op_ == OP_NEAR || op_ == OP_PHRASE);
        add_subquery(positional, a);
        add_subquery(positional, b);
        done();
    }
 
    template<typename S1, typename S2,
        typename
        std::enable_if<std::is_constructible<std::string_view, S1>::value &&
                       std::is_constructible<std::string_view, S2>::value,
                       bool>::type = true>
    Query(op op_, S1 a, S2 b)
    {
        init(op_, 2);
        add_subquery(false, std::string_view(a));
        add_subquery(false, std::string_view(b));
        done();
    }
 
    Query(op op_, Xapian::valueno slot, std::string_view range_limit);
 
    Query(op op_, Xapian::valueno slot,
          std::string_view range_lower, std::string_view range_upper);
 
    Query(op op_,
          std::string_view pattern,
          Xapian::termcount max_expansion = 0,
          int flags = WILDCARD_LIMIT_ERROR,
          op combiner = OP_SYNONYM);
 
    Query(op op_,
          std::string_view pattern,
          Xapian::termcount max_expansion,
          int flags,
          op combiner,
          unsigned edit_distance,
          size_t min_prefix_len = 0);
 
    template<typename I,
        typename std::enable_if<
            std::is_convertible<typename std::iterator_traits<I>::value_type,
                                Xapian::Query>::value ||
            std::is_convertible<typename std::iterator_traits<I>::value_type,
                                Xapian::Query*>::value ||
            std::is_convertible<typename std::iterator_traits<I>::value_type,
                                std::string_view>::value,
            bool>::type = true,
        typename iterator_category =
            typename std::iterator_traits<I>::iterator_category>
    Query(op op_, I begin, I end, Xapian::termcount window = 0)
    {
        if (begin != end) {
            init(op_, window, begin, end, iterator_category());
            bool positional = (op_ == OP_NEAR || op_ == OP_PHRASE);
            for (I i = begin; i != end; ++i) {
                add_subquery(positional, *i);
            }
            done();
        }
    }
 
#ifdef SWIG
    // SWIG's %template doesn't seem to handle a templated ctor so we
    // provide this fake specialised form of the above prototype.
    Query(op op_, XapianSWIGQueryItor qbegin, XapianSWIGQueryItor qend,
          Xapian::termcount parameter = 0);
 
# ifdef SWIGJAVA
    Query(op op_, XapianSWIGStrItor qbegin, XapianSWIGStrItor qend,
          Xapian::termcount parameter = 0);
# endif
#endif
 
    const TermIterator get_terms_begin() const;
 
    const TermIterator get_terms_end() const noexcept {
        return TermIterator();
    }
 
    const TermIterator get_unique_terms_begin() const;
 
    const TermIterator get_unique_terms_end() const noexcept {
        return TermIterator();
    }
 
    Xapian::termcount get_length() const noexcept XAPIAN_PURE_FUNCTION;
 
    bool empty() const noexcept {
        return !internal;
    }
 
    std::string serialise() const;
 
    static const Query unserialise(std::string_view serialised,
                                   const Registry & reg = Registry());
 
    op get_type() const noexcept XAPIAN_PURE_FUNCTION;
 
    size_t get_num_subqueries() const noexcept XAPIAN_PURE_FUNCTION;
 
    Xapian::termcount get_leaf_wqf() const;
 
    Xapian::termpos get_leaf_pos() const;
 
    const Query get_subquery(size_t n) const;
 
    std::string get_description() const;
 
    const Query operator&=(const Query & o);
 
    const Query operator|=(const Query & o);
 
    const Query operator^=(const Query & o);
 
    const Query operator*=(double factor) {
        return (*this = Query(factor, *this));
    }
 
    const Query operator/=(double factor) {
        return (*this = Query(1.0 / factor, *this));
    }
 
    explicit Query(Internal * internal_) : internal(internal_) { }
 
    explicit Query(Query::op op_) {
        init(op_, 0);
        if (op_ != Query::OP_INVALID) done();
    }
 
  private:
    void init(Query::op op_, size_t n_subqueries, Xapian::termcount window = 0);
 
    template<typename I>
    void init(Query::op op_, Xapian::termcount window,
              const I & begin, const I & end, std::random_access_iterator_tag)
    {
        init(op_, end - begin, window);
    }
 
    template<typename I>
    void init(Query::op op_, Xapian::termcount window,
              const I &, const I &, std::input_iterator_tag)
    {
        init(op_, 0, window);
    }
 
    void add_subquery(bool positional, const Xapian::Query & subquery);
 
    void add_subquery(bool, const std::string& subquery) {
        add_subquery(false, Xapian::Query(subquery));
    }
 
    void add_subquery(bool, const char* subquery) {
        add_subquery(false, Xapian::Query(subquery));
    }
 
    void add_subquery(bool, std::string_view subquery) {
        add_subquery(false, Xapian::Query(subquery));
    }
 
    void add_subquery(bool positional, const Xapian::Query * subquery) {
        // FIXME: subquery NULL?
        add_subquery(positional, *subquery);
    }
 
    void done();
};
 
inline const Query
operator&(const Query & a, const Query & b)
{
    return Query(Query::OP_AND, a, b);
}
 
inline const Query
operator|(const Query & a, const Query & b)
{
    return Query(Query::OP_OR, a, b);
}
 
inline const Query
operator^(const Query & a, const Query & b)
{
    return Query(Query::OP_XOR, a, b);
}
 
inline const Query
operator*(double factor, const Query & q)
{
    return Query(factor, q);
}
 
inline const Query
operator*(const Query & q, double factor)
{
    return Query(factor, q);
}
 
inline const Query
operator/(const Query & q, double factor)
{
    return Query(1.0 / factor, q);
}
 
class InvertedQuery_ {
    const Query & query;
 
    void operator=(const InvertedQuery_ &);
 
    explicit InvertedQuery_(const Query & query_) : query(query_) { }
 
  public:
    // GCC 4.2 seems to needs a copy ctor.
    InvertedQuery_(const InvertedQuery_ & o) : query(o.query) { }
 
    operator Query() const {
        return Query(Query::OP_AND_NOT, Query(std::string_view{}), query);
    }
 
    friend const InvertedQuery_ operator~(const Query &q);
 
    friend const Query operator&(const Query & a, const InvertedQuery_ & b);
 
    friend const Query operator&=(Query & a, const InvertedQuery_ & b);
};
 
inline const Query
operator&(const Query & a, const InvertedQuery_ & b)
{
    return Query(Query::OP_AND_NOT, a, b.query);
}
 
inline const Query
operator&=(Query & a, const InvertedQuery_ & b)
{
    return (a = Query(Query::OP_AND_NOT, a, b.query));
}
 
#ifndef DOXYGEN /* @internal doesn't seem to avoid a warning here. */
inline const InvertedQuery_
operator~(const Query &q)
{
    return InvertedQuery_(q);
}
#endif
 
namespace Internal {
class AndContext;
class OrContext;
class XorContext;
 
struct PostListAndEstimate;
class QueryOptimiser;
struct TermFreqs;
}
 
class Query::Internal : public Xapian::Internal::intrusive_base {
  public:
    Internal() noexcept { }
 
    virtual ~Internal();
 
    XAPIAN_VISIBILITY_INTERNAL
    virtual Xapian::Internal::PostListAndEstimate
    postlist(Xapian::Internal::QueryOptimiser* qopt,
             double factor,
             Xapian::Internal::TermFreqs* termfreqs) const = 0;
 
    XAPIAN_VISIBILITY_INTERNAL
    virtual bool
    postlist_sub_and_like(Xapian::Internal::AndContext& ctx,
                          Xapian::Internal::QueryOptimiser* qopt,
                          double factor,
                          Xapian::Internal::TermFreqs* termfreqs) const;
 
    XAPIAN_VISIBILITY_INTERNAL
    virtual void
    postlist_sub_bool_or_like(Xapian::Internal::OrContext& ctx,
                              Xapian::Internal::QueryOptimiser* qopt,
                              Xapian::Internal::TermFreqs* termfreqs) const;
 
    XAPIAN_VISIBILITY_INTERNAL
    virtual void
    postlist_sub_or_like(Xapian::Internal::OrContext& ctx,
                         Xapian::Internal::QueryOptimiser* qopt,
                         double factor,
                         Xapian::Internal::TermFreqs* termfreqs,
                         bool keep_zero_weight = true) const;
 
    XAPIAN_VISIBILITY_INTERNAL
    virtual void
    postlist_sub_xor(Xapian::Internal::XorContext& ctx,
                     Xapian::Internal::QueryOptimiser* qopt,
                     double factor,
                     Xapian::Internal::TermFreqs* termfreqs) const;
 
    XAPIAN_VISIBILITY_INTERNAL
    virtual termcount get_length() const noexcept XAPIAN_PURE_FUNCTION;
 
    XAPIAN_VISIBILITY_INTERNAL
    virtual void serialise(std::string & result) const = 0;
 
    XAPIAN_VISIBILITY_INTERNAL
    static Query::Internal* unserialise(const char** p, const char* end,
                                        const Registry& reg);
 
    XAPIAN_VISIBILITY_INTERNAL
    virtual Query::op get_type() const noexcept XAPIAN_PURE_FUNCTION = 0;
    XAPIAN_VISIBILITY_INTERNAL
    virtual size_t get_num_subqueries() const noexcept XAPIAN_PURE_FUNCTION;
    XAPIAN_VISIBILITY_INTERNAL
    virtual const Query get_subquery(size_t n) const;
    XAPIAN_VISIBILITY_INTERNAL
    virtual termcount get_wqf() const;
    XAPIAN_VISIBILITY_INTERNAL
    virtual termpos get_pos() const;
 
    XAPIAN_VISIBILITY_INTERNAL
    virtual std::string get_description() const = 0;
 
    // Pass argument as void* to avoid need to include <vector>.
    XAPIAN_VISIBILITY_INTERNAL
    virtual void gather_terms(void * void_terms) const;
};
 
inline const Query
Query::operator&=(const Query & o)
{
    if (o.empty()) {
        // q &= empty_query sets q to empty_query.
        *this = o;
    } else if (this != &o &&
               internal &&
               internal->_refs == 1 &&
               get_type() == OP_AND) {
        // Appending a subquery to an existing AND.
        add_subquery(false, o);
    } else {
        *this = Query(OP_AND, *this, o);
    }
    return *this;
}
 
inline const Query
Query::operator|=(const Query & o)
{
    if (o.empty()) {
        // q |= empty_query is a no-op.
    } else if (this != &o &&
               internal &&
               internal->_refs == 1 &&
               get_type() == OP_OR) {
        // Appending a subquery to an existing OR.
        add_subquery(false, o);
    } else {
        *this = Query(OP_OR, *this, o);
    }
    return *this;
}
 
inline const Query
Query::operator^=(const Query & o)
{
    if (o.empty()) {
        // q ^= empty_query is a no-op.
    } else if (internal.get() == o.internal.get()) {
        // q ^= q gives MatchNothing.
        internal = NULL;
    } else if (internal &&
               internal->_refs == 1 &&
               get_type() == OP_XOR) {
        // Appending a subquery to an existing XOR.
        add_subquery(false, o);
    } else {
        *this = Query(OP_XOR, *this, o);
    }
    return *this;
}
 
}
 
#endif // XAPIAN_INCLUDED_QUERY_H