xapian-core/include/xapian/eset.h

   1 /** @file
   2  *  @brief Class representing a list of query expansion terms
   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_ESET_H
  23 #define XAPIAN_INCLUDED_ESET_H
  24
  25 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
  26 # error Never use <xapian/eset.h> directly; include <xapian.h> instead.
  27 #endif
  28
  29 #include <iterator>
  30 #include <string>
  31
  32 #include <xapian/attributes.h>
  33 #include <xapian/intrusive_ptr.h>
  34 #include <xapian/stem.h>
  35 #include <xapian/types.h>
  36 #include <xapian/visibility.h>
  37
  38 namespace Xapian {
  39
  40 class ESetIterator;
  41
  42 /// Class representing a list of search results.
  43 class XAPIAN_VISIBILITY_DEFAULT ESet {
  44     friend class ESetIterator;
  45
  46   public:
  47     /// Class representing the ESet internals.
  48     class Internal;
  49     /// @private @internal Reference counted internals.
  50     Xapian::Internal::intrusive_ptr<Internal> internal;
  51
  52     /** Copying is allowed.
  53      *
  54      *  The internals are reference counted, so copying is cheap.
  55      */
  56     ESet(const ESet & o);
  57
  58     /** Copying is allowed.
  59      *
  60      *  The internals are reference counted, so assignment is cheap.
  61      */
  62     ESet & operator=(const ESet & o);
  63
  64 #ifdef XAPIAN_MOVE_SEMANTICS
  65     /// Move constructor.
  66     ESet(ESet && o);
  67
  68     /// Move assignment operator.
  69     ESet & operator=(ESet && o);
  70 #endif
  71
  72     /** Default constructor.
  73      *
  74      *  Creates an empty ESet, mostly useful as a placeholder.
  75      */
  76     ESet();
  77
  78     /// Destructor.
  79     ~ESet();
  80
  81     /** Return number of items in this ESet object. */
  82     Xapian::termcount size() const;
  83
  84     /** Return true if this ESet object is empty. */
  85     bool empty() const { return size() == 0; }
  86
  87     /** Return a bound on the full size of this ESet object.
  88      *
  89      *  This is a bound on size() if get_eset() had been called with
  90      *  maxitems set high enough that all results were returned.
  91      */
  92     Xapian::termcount get_ebound() const;
  93
  94     /** Efficiently swap this ESet object with another. */
  95     void swap(ESet & o) { internal.swap(o.internal); }
  96
  97     /** Return iterator pointing to the first item in this ESet. */
  98     ESetIterator begin() const;
  99
 100     /** Return iterator pointing to just after the last item in this ESet. */
 101     ESetIterator end() const;
 102
 103     /** Return iterator pointing to the i-th object in this ESet. */
 104     ESetIterator operator[](Xapian::termcount i) const;
 105
 106     /** Return iterator pointing to the last object in this ESet. */
 107     ESetIterator back() const;
 108
 109     /// Return a string describing this object.
 110     std::string get_description() const;
 111
 112     /** @private @internal ESet is what the C++ STL calls a container.
 113      *
 114      *  The following typedefs allow the class to be used in templates in the
 115      *  same way the standard containers can be.
 116      *
 117      *  These are deliberately hidden from the Doxygen-generated docs, as the
 118      *  machinery here isn't interesting to API users.  They just need to know
 119      *  that Xapian container classes are compatible with the STL.
 120      *
 121      *  See "The C++ Programming Language", 3rd ed. section 16.3.1:
 122      */
 123     // @{
 124     /// @private
 125     typedef Xapian::ESetIterator value_type;
 126     /// @private
 127     typedef Xapian::termcount size_type;
 128     /// @private
 129     typedef Xapian::termcount_diff difference_type;
 130     /// @private
 131     typedef Xapian::ESetIterator iterator;
 132     /// @private
 133     typedef Xapian::ESetIterator const_iterator;
 134     /// @private
 135     typedef value_type * pointer;
 136     /// @private
 137     typedef const value_type * const_pointer;
 138     /// @private
 139     typedef value_type & reference;
 140     /// @private
 141     typedef const value_type & const_reference;
 142     // @}
 143     //
 144     /** @private @internal ESet is what the C++ STL calls a container.
 145      *
 146      *  The following methods allow the class to be used in templates in the
 147      *  same way the standard containers can be.
 148      *
 149      *  These are deliberately hidden from the Doxygen-generated docs, as the
 150      *  machinery here isn't interesting to API users.  They just need to know
 151      *  that Xapian container classes are compatible with the STL.
 152      */
 153     // @{
 154     // The size is fixed once created.
 155     Xapian::termcount max_size() const { return size(); }
 156     // @}
 157 };
 158
 159 /// Iterator over a Xapian::ESet.
 160 class XAPIAN_VISIBILITY_DEFAULT ESetIterator {
 161     friend class ESet;
 162
 163     ESetIterator(const Xapian::ESet & eset_, Xapian::termcount off_from_end_)
 164         : eset(eset_), off_from_end(off_from_end_) { }
 165
 166   public:
 167     /** @private @internal The ESet we are iterating over. */
 168     Xapian::ESet eset;
 169
 170     /** @private @internal The current position of the iterator.
 171      *
 172      *  We store the offset from the end of @a eset, since that means
 173      *  ESet::end() just needs to set this member to 0.
 174      */
 175     Xapian::ESet::size_type off_from_end;
 176
 177     /** Create an unpositioned ESetIterator. */
 178     ESetIterator() : off_from_end(0) { }
 179
 180     /** Get the term at the current position. */
 181     std::string operator*() const;
 182
 183     /// Advance the iterator to the next position.
 184     ESetIterator & operator++() {
 185         --off_from_end;
 186         return *this;
 187     }
 188
 189     /// Advance the iterator to the next position (postfix version).
 190     ESetIterator operator++(int) {
 191         ESetIterator retval = *this;
 192         --off_from_end;
 193         return retval;
 194     }
 195
 196     /// Move the iterator to the previous position.
 197     ESetIterator & operator--() {
 198         ++off_from_end;
 199         return *this;
 200     }
 201
 202     /// Move the iterator to the previous position (postfix version).
 203     ESetIterator operator--(int) {
 204         ESetIterator retval = *this;
 205         ++off_from_end;
 206         return retval;
 207     }
 208
 209     /** @private @internal ESetIterator is what the C++ STL calls an
 210      *  random_access_iterator.
 211      *
 212      *  The following typedefs allow std::iterator_traits<> to work so that
 213      *  this iterator can be used with the STL.
 214      *
 215      *  These are deliberately hidden from the Doxygen-generated docs, as the
 216      *  machinery here isn't interesting to API users.  They just need to know
 217      *  that Xapian iterator classes are compatible with the STL.
 218      */
 219     // @{
 220     /// @private
 221     typedef std::random_access_iterator_tag iterator_category;
 222     /// @private
 223     typedef std::string value_type;
 224     /// @private
 225     typedef Xapian::termcount_diff difference_type;
 226     /// @private
 227     typedef std::string * pointer;
 228     /// @private
 229     typedef std::string & reference;
 230     // @}
 231
 232     /// Move the iterator forwards by n positions.
 233     ESetIterator & operator+=(difference_type n) {
 234         off_from_end -= n;
 235         return *this;
 236     }
 237
 238     /// Move the iterator back by n positions.
 239     ESetIterator & operator-=(difference_type n) {
 240         off_from_end += n;
 241         return *this;
 242     }
 243
 244     /** Return the iterator incremented by @a n positions.
 245      *
 246      *  If @a n is negative, decrements by (-n) positions.
 247      */
 248     ESetIterator operator+(difference_type n) const {
 249         return ESetIterator(eset, off_from_end - n);
 250     }
 251
 252     /** Return the iterator decremented by @a n positions.
 253      *
 254      *  If @a n is negative, increments by (-n) positions.
 255      */
 256     ESetIterator operator-(difference_type n) const {
 257         return ESetIterator(eset, off_from_end + n);
 258     }
 259
 260     /** Return the number of positions between @a o and this iterator. */
 261     difference_type operator-(const ESetIterator& o) const {
 262         return difference_type(o.off_from_end) - difference_type(off_from_end);
 263     }
 264
 265     /** Get the weight for the current position. */
 266     double get_weight() const;
 267
 268     /// Return a string describing this object.
 269     std::string get_description() const;
 270 };
 271
 272 bool
 273 XAPIAN_NOTHROW(operator==(const ESetIterator &a, const ESetIterator &b));
 274
 275 /// Equality test for ESetIterator objects.
 276 inline bool
 277 operator==(const ESetIterator &a, const ESetIterator &b) XAPIAN_NOEXCEPT
 278 {
 279     return a.off_from_end == b.off_from_end;
 280 }
 281
 282 inline bool
 283 XAPIAN_NOTHROW(operator!=(const ESetIterator &a, const ESetIterator &b));
 284
 285 /// Inequality test for ESetIterator objects.
 286 inline bool
 287 operator!=(const ESetIterator &a, const ESetIterator &b) XAPIAN_NOEXCEPT
 288 {
 289     return !(a == b);
 290 }
 291
 292 bool
 293 XAPIAN_NOTHROW(operator<(const ESetIterator &a, const ESetIterator &b));
 294
 295 /// Inequality test for ESetIterator objects.
 296 inline bool
 297 operator<(const ESetIterator &a, const ESetIterator &b) XAPIAN_NOEXCEPT
 298 {
 299     return a.off_from_end > b.off_from_end;
 300 }
 301
 302 inline bool
 303 XAPIAN_NOTHROW(operator>(const ESetIterator &a, const ESetIterator &b));
 304
 305 /// Inequality test for ESetIterator objects.
 306 inline bool
 307 operator>(const ESetIterator &a, const ESetIterator &b) XAPIAN_NOEXCEPT
 308 {
 309     return b < a;
 310 }
 311
 312 inline bool
 313 XAPIAN_NOTHROW(operator>=(const ESetIterator &a, const ESetIterator &b));
 314
 315 /// Inequality test for ESetIterator objects.
 316 inline bool
 317 operator>=(const ESetIterator &a, const ESetIterator &b) XAPIAN_NOEXCEPT
 318 {
 319     return !(a < b);
 320 }
 321
 322 inline bool
 323 XAPIAN_NOTHROW(operator<=(const ESetIterator &a, const ESetIterator &b));
 324
 325 /// Inequality test for ESetIterator objects.
 326 inline bool
 327 operator<=(const ESetIterator &a, const ESetIterator &b) XAPIAN_NOEXCEPT
 328 {
 329     return !(b < a);
 330 }
 331
 332 /** Return ESetIterator @a it incremented by @a n positions.
 333  *
 334  *  If @a n is negative, decrements by (-n) positions.
 335  */
 336 inline ESetIterator
 337 operator+(ESetIterator::difference_type n, const ESetIterator& it)
 338 {
 339     return it + n;
 340 }
 341
 342 // Inlined methods of ESet which need ESetIterator to have been defined:
 343
 344 inline ESetIterator
 345 ESet::begin() const {
 346     return ESetIterator(*this, size());
 347 }
 348
 349 inline ESetIterator
 350 ESet::end() const {
 351     // Decrementing the result of end() needs to work, so we must pass in
 352     // *this here.
 353     return ESetIterator(*this, 0);
 354 }
 355
 356 inline ESetIterator
 357 ESet::operator[](Xapian::termcount i) const {
 358     return ESetIterator(*this, size() - i);
 359 }
 360
 361 inline ESetIterator
 362 ESet::back() const {
 363     return ESetIterator(*this, 1);
 364 }
 365
 366 }
 367
 368 #endif // XAPIAN_INCLUDED_ESET_H