mset.h

Go to the documentation of this file.

 
/* Copyright (C) 2015,2016,2017,2019,2023,2024,2026 Olly Betts
 * Copyright (C) 2018 Uppinder Chugh
 *
 * 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_MSET_H
#define XAPIAN_INCLUDED_MSET_H
 
#if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
# error Never use <xapian/mset.h> directly; include <xapian.h> instead.
#endif
 
#include <iterator>
#include <string>
#include <string_view>
 
#include <xapian/attributes.h>
#include <xapian/document.h>
#include <xapian/error.h>
#include <xapian/intrusive_ptr.h>
#include <xapian/stem.h>
#include <xapian/types.h>
#include <xapian/visibility.h>
 
namespace Xapian {
 
class MSetIterator;
 
class XAPIAN_VISIBILITY_DEFAULT MSet {
    friend class MSetIterator;
 
    // Helper function for fetch() methods.
    void fetch_(Xapian::doccount first, Xapian::doccount last) const;
 
    void set_item_weight(Xapian::doccount i, double wt);
 
#if 0 // FIXME: Need work before release.
    void diversify_(Xapian::doccount k,
                    Xapian::doccount r,
                    double factor1,
                    double factor2);
#endif
 
  public:
    class Internal;
    Xapian::Internal::intrusive_ptr_nonnull<Internal> internal;
 
    MSet(const MSet & o);
 
    MSet & operator=(const MSet & o);
 
    MSet(MSet && o);
 
    MSet & operator=(MSet && o);
 
    MSet();
 
    XAPIAN_VISIBILITY_INTERNAL
    explicit MSet(Internal* internal_);
 
    ~MSet();
 
    template<typename Iterator>
    void replace_weights(Iterator first, Iterator last)
    {
        auto distance = last - first;
        // Take care to compare signed and unsigned types both safely and
        // without triggering compiler warnings.
        if (distance < 0 ||
            (sizeof(distance) <= sizeof(Xapian::doccount) ?
                Xapian::doccount(distance) != size() :
                distance != static_cast<decltype(distance)>(size()))) {
            throw Xapian::InvalidArgumentError("Number of weights assigned "
                                               "doesn't match the number of "
                                               "items");
        }
        Xapian::doccount i = 0;
        while (first != last) {
            set_item_weight(i, *first);
            ++i;
            ++first;
        }
    }
 
    void sort_by_relevance();
 
#if 0 // FIXME: Need work before release.
    void diversify(Xapian::doccount k,
                   Xapian::doccount r,
                   double lambda = 0.5,
                   double b = 5.0,
                   double sigma_sqr = 1e-3) {
        // Inline the argument value checks and the calculation of the scale
        // factor for score_2 so the compiler can optimise in the case where
        // some or all parameter values are compile-time constants.
        if (r == 0)
            throw InvalidArgumentError("r must be > 0");
        if (lambda < 0.0 || lambda > 1.0)
            throw InvalidArgumentError("lambda must be between 0 and 1");
        if (k > 1)
            diversify_(k, r, lambda, (1.0 - lambda) * b * sigma_sqr * 2.0);
    }
#endif
 
    int convert_to_percent(double weight) const;
 
    int convert_to_percent(const MSetIterator & it) const;
 
    Xapian::doccount get_termfreq(std::string_view term) const;
 
    double get_termweight(std::string_view term) 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;
 
    double get_max_attained() const;
    double get_max_possible() const;
 
    enum {
        SNIPPET_BACKGROUND_MODEL = 1,
        SNIPPET_EXHAUSTIVE = 2,
        SNIPPET_EMPTY_WITHOUT_MATCH = 4,
 
        SNIPPET_NGRAMS = 2048,
 
        SNIPPET_CJK_NGRAM = SNIPPET_NGRAMS,
 
        SNIPPET_WORD_BREAKS = 4096
    };
 
    std::string snippet(std::string_view text,
                        size_t length = 500,
                        const Xapian::Stem & stemmer = Xapian::Stem(),
                        unsigned flags = SNIPPET_BACKGROUND_MODEL|SNIPPET_EXHAUSTIVE,
                        std::string_view hi_start = "<b>",
                        std::string_view hi_end = "</b>",
                        std::string_view omit = "...") const;
 
    void fetch(const MSetIterator &begin, const MSetIterator &end) const;
 
    void fetch(const MSetIterator &item) const;
 
    void fetch() const { fetch_(0, Xapian::doccount(-1)); }
 
    Xapian::doccount size() const;
 
    bool empty() const { return size() == 0; }
 
    void swap(MSet & o) { internal.swap(o.internal); }
 
    MSetIterator begin() const;
 
    MSetIterator end() const;
 
    MSetIterator operator[](Xapian::doccount i) const;
 
    MSetIterator back() const;
 
    std::string get_description() const;
 
    // @{
    typedef Xapian::MSetIterator value_type;
    typedef Xapian::doccount size_type;
    typedef Xapian::doccount_diff difference_type;
    typedef Xapian::MSetIterator iterator;
    typedef Xapian::MSetIterator const_iterator;
    typedef value_type * pointer;
    typedef const value_type * const_pointer;
    typedef value_type reference;
    typedef const value_type const_reference;
    // @}
    //
    // @{
    // The size is fixed once created.
    Xapian::doccount max_size() const { return size(); }
    // @}
};
 
class XAPIAN_VISIBILITY_DEFAULT MSetIterator {
    friend class MSet;
 
    MSetIterator(const Xapian::MSet & mset_, Xapian::doccount off_from_end_)
        : mset(mset_), off_from_end(off_from_end_) { }
 
  public:
    Xapian::MSet mset;
 
    Xapian::MSet::size_type off_from_end;
 
    MSetIterator() : off_from_end(0) { }
 
    Xapian::docid operator*() const;
 
    MSetIterator & operator++() {
        --off_from_end;
        return *this;
    }
 
    MSetIterator operator++(int) {
        MSetIterator retval = *this;
        --off_from_end;
        return retval;
    }
 
    MSetIterator & operator--() {
        ++off_from_end;
        return *this;
    }
 
    MSetIterator operator--(int) {
        MSetIterator retval = *this;
        ++off_from_end;
        return retval;
    }
 
    // @{
    typedef std::random_access_iterator_tag iterator_category;
    typedef Xapian::docid value_type;
    typedef Xapian::termcount_diff difference_type;
    typedef value_type* pointer;
    typedef value_type reference;
    // @}
 
    MSetIterator & operator+=(difference_type n) {
        off_from_end -= n;
        return *this;
    }
 
    MSetIterator & operator-=(difference_type n) {
        off_from_end += n;
        return *this;
    }
 
    MSetIterator operator+(difference_type n) const {
        return MSetIterator(mset, off_from_end - n);
    }
 
    MSetIterator operator-(difference_type n) const {
        return MSetIterator(mset, off_from_end + n);
    }
 
    difference_type operator-(const MSetIterator& o) const {
        return difference_type(o.off_from_end) - difference_type(off_from_end);
    }
 
    Xapian::doccount get_rank() const {
        return mset.get_firstitem() + (mset.size() - off_from_end);
    }
 
    Xapian::Document get_document() const;
 
    double get_weight() const;
 
    std::string get_collapse_key() const;
 
    Xapian::doccount get_collapse_count() const;
 
    std::string get_sort_key() const;
 
    int get_percent() const {
        return mset.convert_to_percent(get_weight());
    }
 
    std::string get_description() const;
};
 
inline bool
operator==(const MSetIterator& a, const MSetIterator& b) noexcept
{
    return a.off_from_end == b.off_from_end;
}
 
inline bool
operator!=(const MSetIterator& a, const MSetIterator& b) noexcept
{
    return !(a == b);
}
 
inline bool
operator<(const MSetIterator& a, const MSetIterator& b) noexcept
{
    return a.off_from_end > b.off_from_end;
}
 
inline bool
operator>(const MSetIterator& a, const MSetIterator& b) noexcept
{
    return b < a;
}
 
inline bool
operator>=(const MSetIterator& a, const MSetIterator& b) noexcept
{
    return !(a < b);
}
 
inline bool
operator<=(const MSetIterator& a, const MSetIterator& b) noexcept
{
    return !(b < a);
}
 
inline MSetIterator
operator+(MSetIterator::difference_type n, const MSetIterator& it)
{
    return it + n;
}
 
// Inlined methods of MSet which need MSetIterator to have been defined:
 
inline void
MSet::fetch(const MSetIterator &begin_it, const MSetIterator &end_it) const
{
    fetch_(begin_it.off_from_end, end_it.off_from_end);
}
 
inline void
MSet::fetch(const MSetIterator &item) const
{
    fetch_(item.off_from_end, item.off_from_end);
}
 
inline MSetIterator
MSet::begin() const {
    return MSetIterator(*this, size());
}
 
inline MSetIterator
MSet::end() const {
    // Decrementing the result of end() needs to work, so we must pass in
    // *this here.
    return MSetIterator(*this, 0);
}
 
inline MSetIterator
MSet::operator[](Xapian::doccount i) const {
    return MSetIterator(*this, size() - i);
}
 
inline MSetIterator
MSet::back() const {
    return MSetIterator(*this, 1);
}
 
inline int
MSet::convert_to_percent(const MSetIterator & it) const {
    return convert_to_percent(it.get_weight());
}
 
}
 
#endif // XAPIAN_INCLUDED_MSET_H