xapian-core/include/xapian/mset.h

   1 /** @file  mset.h
   2  *  @brief Class representing a list of search results
   3  */
   4 /* Copyright (C) 2015,2016 Olly Betts
   5  *
   6  * This program is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU General Public License as
   8  * published by the Free Software Foundation; either version 2 of the
   9  * License, or (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
  19  * USA
  20  */
  21
  22 #ifndef XAPIAN_INCLUDED_MSET_H
  23 #define XAPIAN_INCLUDED_MSET_H
  24
  25 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
  26 # error "Never use <xapian/mset.h> directly; include <xapian.h> instead."
  27 #endif
  28
  29 #include <iterator>
  30 #include <string>
  31
  32 #include <xapian/attributes.h>
  33 #include <xapian/document.h>
  34 #include <xapian/intrusive_ptr.h>
  35 #include <xapian/stem.h>
  36 #include <xapian/types.h>
  37 #include <xapian/visibility.h>
  38
  39 namespace Xapian {
  40
  41 class MSetIterator;
  42
  43 /// Class representing a list of search results.
  44 class XAPIAN_VISIBILITY_DEFAULT MSet {
  45     friend class MSetIterator;
  46
  47     // Helper function for fetch() methods.
  48     void fetch_(Xapian::doccount first, Xapian::doccount last) const;
  49
  50   public:
  51     /// Class representing the MSet internals.
  52     class Internal;
  53     /// @private @internal Reference counted internals.
  54     Xapian::Internal::intrusive_ptr<Internal> internal;
  55
  56     /** Copying is allowed.
  57      *
  58      *  The internals are reference counted, so copying is cheap.
  59      */
  60     MSet(const MSet & o);
  61
  62     /** Copying is allowed.
  63      *
  64      *  The internals are reference counted, so assignment is cheap.
  65      */
  66     MSet & operator=(const MSet & o);
  67
  68     /** Default constructor.
  69      *
  70      *  Creates an empty MSet, mostly useful as a placeholder.
  71      */
  72     MSet();
  73
  74     /// Destructor.
  75     ~MSet();
  76
  77     int convert_to_percent(double weight) const;
  78
  79     int convert_to_percent(const MSetIterator & it) const;
  80
  81     Xapian::doccount get_termfreq(const std::string & term) const;
  82
  83     double get_termweight(const std::string & term) const;
  84
  85     Xapian::doccount get_firstitem() const;
  86
  87     Xapian::doccount get_matches_lower_bound() const;
  88     Xapian::doccount get_matches_estimated() const;
  89     Xapian::doccount get_matches_upper_bound() const;
  90
  91     Xapian::doccount get_uncollapsed_matches_lower_bound() const;
  92     Xapian::doccount get_uncollapsed_matches_estimated() const;
  93     Xapian::doccount get_uncollapsed_matches_upper_bound() const;
  94
  95     double get_max_attained() const;
  96     double get_max_possible() const;
  97
  98     enum {
  99         SNIPPET_BACKGROUND_MODEL = 1,
 100         SNIPPET_EXHAUSTIVE = 2
 101     };
 102
 103     /** Generate a snippet.
 104      *
 105      *  This method selects a continuous run of words of less than about @a
 106      *  length bytes from @a text, based mainly on where the query matches
 107      *  (currently terms, exact phrases and wildcards are taken into account),
 108      *  but also on the non-query terms in the text.
 109      *
 110      *  The returned text can be escaped (by default, it is escaped to make it
 111      *  suitable for use in HTML), and matches with the query will be
 112      *  highlighted using @a hi_start and @a hi_end.
 113      *
 114      *  If the snippet seems to start or end mid-sentence, then @a omit is
 115      *  prepended or append (respectively) to indicate this.
 116      *
 117      *  The stemmer used to build the query should be specified in @a stemmer.
 118      *
 119      *  And @a flags contains flags controlling behaviour.
 120      */
 121     std::string snippet(const std::string & text,
 122                         size_t length = 500,
 123                         const Xapian::Stem & stemmer = Xapian::Stem(),
 124                         unsigned flags = SNIPPET_BACKGROUND_MODEL|SNIPPET_EXHAUSTIVE,
 125                         const std::string & hi_start = "<b>",
 126                         const std::string & hi_end = "</b>",
 127                         const std::string & omit = "...") const;
 128
 129     /** Prefetch hint a range of items.
 130      *
 131      *  For a remote database, this may start a pipelined fetched of the
 132      *  requested documents from the remote server.
 133      *
 134      *  For a disk-based database, this may send prefetch hints to the
 135      *  operating system such that the disk blocks the requested documents
 136      *  are stored in are more likely to be in the cache when we come to
 137      *  actually read them.
 138      */
 139     void fetch(const MSetIterator &begin, const MSetIterator &end) const;
 140
 141     /** Prefetch hint a single MSet item.
 142      *
 143      *  For a remote database, this may start a pipelined fetched of the
 144      *  requested documents from the remote server.
 145      *
 146      *  For a disk-based database, this may send prefetch hints to the
 147      *  operating system such that the disk blocks the requested documents
 148      *  are stored in are more likely to be in the cache when we come to
 149      *  actually read them.
 150      */
 151     void fetch(const MSetIterator &item) const;
 152
 153     /** Prefetch hint the whole MSet.
 154      *
 155      *  For a remote database, this may start a pipelined fetched of the
 156      *  requested documents from the remote server.
 157      *
 158      *  For a disk-based database, this may send prefetch hints to the
 159      *  operating system such that the disk blocks the requested documents
 160      *  are stored in are more likely to be in the cache when we come to
 161      *  actually read them.
 162      */
 163     void fetch() const { fetch_(0, Xapian::doccount(-1)); }
 164
 165     Xapian::doccount size() const;
 166
 167     bool empty() const { return size() == 0; }
 168
 169     void swap(MSet & o) { internal.swap(o.internal); }
 170
 171     MSetIterator begin() const;
 172
 173     MSetIterator end() const;
 174
 175     MSetIterator operator[](Xapian::doccount i) const;
 176
 177     MSetIterator back() const;
 178
 179     /// Return a string describing this object.
 180     std::string get_description() const;
 181
 182     /** @private @internal MSet is what the C++ STL calls a container.
 183      *
 184      *  The following typedefs allow the class to be used in templates in the
 185      *  same way the standard containers can be.
 186      *
 187      *  These are deliberately hidden from the Doxygen-generated docs, as the
 188      *  machinery here isn't interesting to API users.  They just need to know
 189      *  that Xapian container classes are compatible with the STL.
 190      *
 191      *  See "The C++ Programming Language", 3rd ed. section 16.3.1:
 192      */
 193     // @{
 194     /// @private
 195     typedef Xapian::MSetIterator value_type;
 196     /// @private
 197     typedef Xapian::doccount size_type;
 198     /// @private
 199     typedef Xapian::doccount_diff difference_type;
 200     /// @private
 201     typedef Xapian::MSetIterator iterator;
 202     /// @private
 203     typedef Xapian::MSetIterator const_iterator;
 204     /// @private
 205     typedef value_type * pointer;
 206     /// @private
 207     typedef const value_type * const_pointer;
 208     /// @private
 209     typedef value_type & reference;
 210     /// @private
 211     typedef const value_type & const_reference;
 212     // @}
 213     //
 214     /** @private @internal MSet is what the C++ STL calls a container.
 215      *
 216      *  The following methods allow the class to be used in templates in the
 217      *  same way the standard containers can be.
 218      *
 219      *  These are deliberately hidden from the Doxygen-generated docs, as the
 220      *  machinery here isn't interesting to API users.  They just need to know
 221      *  that Xapian container classes are compatible with the STL.
 222      */
 223     // @{
 224     // The size is fixed once created.
 225     Xapian::doccount max_size() const { return size(); }
 226     // @}
 227 };
 228
 229 /// Iterator over a Xapian::MSet.
 230 class XAPIAN_VISIBILITY_DEFAULT MSetIterator {
 231     friend class MSet;
 232
 233     MSetIterator(const Xapian::MSet & mset_, Xapian::doccount off_from_end_)
 234         : mset(mset_), off_from_end(off_from_end_) { }
 235
 236   public:
 237     /** @private @internal The MSet we are iterating over. */
 238     Xapian::MSet mset;
 239
 240     /** @private @internal The current position of the iterator.
 241      *
 242      *  We store the offset from the end of @a mset, since that means
 243      *  MSet::end() just needs to set this member to 0.
 244      */
 245     Xapian::MSet::size_type off_from_end;
 246
 247     /** Create an unpositioned MSetIterator. */
 248     MSetIterator() : off_from_end(0) { }
 249
 250     /** Get the numeric document id for the current position. */
 251     Xapian::docid operator*() const;
 252
 253     /// Advance the iterator to the next position.
 254     MSetIterator & operator++() {
 255         --off_from_end;
 256         return *this;
 257     }
 258
 259     /// Advance the iterator to the next position (postfix version).
 260     MSetIterator operator++(int) {
 261         MSetIterator retval = *this;
 262         --off_from_end;
 263         return retval;
 264     }
 265
 266     /// Move the iterator to the previous position.
 267     MSetIterator & operator--() {
 268         ++off_from_end;
 269         return *this;
 270     }
 271
 272     /// Move the iterator to the previous position (postfix version).
 273     MSetIterator operator--(int) {
 274         MSetIterator retval = *this;
 275         ++off_from_end;
 276         return retval;
 277     }
 278
 279     Xapian::doccount get_rank() const {
 280         return mset.get_firstitem() + (mset.size() - off_from_end);
 281     }
 282
 283     /** Get the Document object for the current position. */
 284     Xapian::Document get_document() const;
 285
 286     /** Get the weight for the current position. */
 287     double get_weight() const;
 288
 289     std::string get_collapse_key() const;
 290
 291     Xapian::doccount get_collapse_count() const;
 292
 293     int get_percent() const {
 294         return mset.convert_to_percent(get_weight());
 295     }
 296
 297     /// Return a string describing this object.
 298     std::string get_description() const;
 299 };
 300
 301 bool
 302 XAPIAN_NOTHROW(operator==(const MSetIterator &a, const MSetIterator &b));
 303
 304 /// Equality test for MSetIterator objects.
 305 inline bool
 306 operator==(const MSetIterator &a, const MSetIterator &b) XAPIAN_NOEXCEPT
 307 {
 308     // Use a pointer comparison - this ensures both that (a == a) and correct
 309     // handling of end iterators (which we ensure have NULL internals).
 310     return a.off_from_end == b.off_from_end;
 311 }
 312
 313 inline bool
 314 XAPIAN_NOTHROW(operator!=(const MSetIterator &a, const MSetIterator &b));
 315
 316 /// Inequality test for MSetIterator objects.
 317 inline bool
 318 operator!=(const MSetIterator &a, const MSetIterator &b) XAPIAN_NOEXCEPT
 319 {
 320     return !(a == b);
 321 }
 322
 323 // Inlined methods of MSet which need MSetIterator to have been defined:
 324
 325 inline void
 326 MSet::fetch(const MSetIterator &begin, const MSetIterator &end) const
 327 {
 328     fetch_(begin.off_from_end, end.off_from_end);
 329 }
 330
 331 inline void
 332 MSet::fetch(const MSetIterator &item) const
 333 {
 334     fetch_(item.off_from_end, item.off_from_end);
 335 }
 336
 337 inline MSetIterator
 338 MSet::begin() const {
 339     return MSetIterator(*this, size());
 340 }
 341
 342 inline MSetIterator
 343 MSet::end() const {
 344     // Decrementing the result of end() needs to work, so we must pass in
 345     // *this here.
 346     return MSetIterator(*this, 0);
 347 }
 348
 349 inline MSetIterator
 350 MSet::operator[](Xapian::doccount i) const {
 351     return MSetIterator(*this, size() - i);
 352 }
 353
 354 inline MSetIterator
 355 MSet::back() const {
 356     return MSetIterator(*this, 1);
 357 }
 358
 359 }
 360
 361 #endif // XAPIAN_INCLUDED_POSTINGITERATOR_H