xapian-core/include/xapian/eset.h

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