xapian-core/include/xapian/document.h

   1 /** @file document.h
   2  * @brief Class representing a document
   3  */
   4 /* Copyright (C) 2010,2015,2016,2017,2018 Olly Betts
   5  * Copyright 2009 Lemur Consulting Ltd
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License as
   9  * published by the Free Software Foundation; either version 2 of the
  10  * License, or (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
  20  * USA
  21  */
  22
  23 #ifndef XAPIAN_INCLUDED_DOCUMENT_H
  24 #define XAPIAN_INCLUDED_DOCUMENT_H
  25
  26 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
  27 # error "Never use <xapian/document.h> directly; include <xapian.h> instead."
  28 #endif
  29
  30 #include <string>
  31
  32 #include <xapian/attributes.h>
  33 #include <xapian/intrusive_ptr.h>
  34 #include <xapian/termiterator.h>
  35 #include <xapian/types.h>
  36 #include <xapian/valueiterator.h>
  37 #include <xapian/visibility.h>
  38
  39 namespace Xapian {
  40
  41 /** Class representing a document.
  42  *
  43  *  The term "document" shouldn't be taken too literally - really it's a "thing
  44  *  to retrieve", as the list of search results is essentially a list of
  45  *  documents.
  46  *
  47  *  Document objects fetch information from the database lazily.  Usually
  48  *  this behaviour isn't visible to users (except for the speed benefits), but
  49  *  if the document in the database is modified or deleted then preexisting
  50  *  Document objects may return the old or new versions of data (or throw
  51  *  Xapian::DocNotFoundError in the case of deletion).
  52  *
  53  *  Since Database objects work on a snapshot of the database's state, the
  54  *  situation above can only happen with a WritableDatabase object, or if
  55  *  you call Database::reopen() on the Database object which you got the
  56  *  Document from.
  57  *
  58  *  We recommend you avoid designs where this behaviour is an issue, but if
  59  *  you need a way to make a non-lazy version of a Document object, you can do
  60  *  this like so:
  61  *
  62  *      doc = Xapian::Document::unserialise(doc.serialise());
  63  */
  64 class XAPIAN_VISIBILITY_DEFAULT Document {
  65   public:
  66     /// Class representing the Document internals.
  67     class Internal;
  68     /// @private @internal Reference counted internals.
  69     Xapian::Internal::intrusive_ptr_nonnull<Internal> internal;
  70
  71     /// @private @internal Wrap an existing Internal.
  72     XAPIAN_VISIBILITY_INTERNAL
  73     explicit Document(Internal*);
  74
  75     /** Copy constructor.
  76      *
  77      *  The internals are reference counted, so copying is cheap.
  78      */
  79     Document(const Document& o);
  80
  81     /** Assignment operator.
  82      *
  83      *  The internals are reference counted, so assignment is cheap.
  84      */
  85     Document& operator=(const Document& o);
  86
  87     /// Move constructor.
  88     Document(Document&& o);
  89
  90     /// Move assignment operator.
  91     Document& operator=(Document&& o);
  92
  93     /** Default constructor.
  94      *
  95      *  Creates an empty Document.
  96      */
  97     Document();
  98
  99     /// Destructor.
 100     ~Document();
 101
 102     /** Get the document ID this document came from.
 103      *
 104      *  If this document didn't come from a database, this will be 0 (in Xapian
 105      *  1.0.22/1.2.4 or later; prior to this the returned value was uninitialised
 106      *  in this case).
 107      *
 108      *  Note that if the document came from a sharded database, this is the docid
 109      *  in the shard it came from, not the docid in the combined database.
 110      */
 111     Xapian::docid get_docid() const;
 112
 113     /// Get the document data.
 114     std::string get_data() const;
 115
 116     /// Set the document data.
 117     void set_data(const std::string& data);
 118
 119     /// Add a term to this document.
 120     void add_term(const std::string& term, Xapian::termcount wdf_inc = 1);
 121
 122     /** Add a boolean filter term to the document.
 123      *
 124      *  This method adds @a term to the document with wdf of 0 -
 125      *  this is generally what you want for a term used for boolean
 126      *  filtering as the wdf of such terms is ignored, and it doesn't
 127      *  make sense for them to contribute to the document's length.
 128      *
 129      *  If the specified term already indexes this document, this method
 130      *  has no effect.
 131      *
 132      *  It is exactly the same as add_term(term, 0) and is provided as a
 133      *  way to make a common operation more explicit.
 134      *
 135      *  This method was added in Xapian 1.0.18.
 136      *
 137      *  @param term             The term to add.
 138      */
 139     void add_boolean_term(const std::string& term) { add_term(term, 0); }
 140
 141     /// Remove a term from this document.
 142     void remove_term(const std::string& term);
 143
 144     /// Add a posting for a term.
 145     void add_posting(const std::string& term,
 146                      Xapian::termpos term_pos,
 147                      Xapian::termcount wdf_inc = 1);
 148
 149     /// Remove posting for a term.
 150     void remove_posting(const std::string& term,
 151                         Xapian::termpos term_pos,
 152                         Xapian::termcount wdf_dec = 1);
 153
 154     /** Remove a range of postings for a term.
 155      *
 156      *  Any instances of the term at positions >= @a term_pos_first and
 157      *  <= @a term_pos_last will be removed, and the wdf reduced by
 158      *  @a wdf_dec for each instance removed (the wdf will not ever go
 159      *  below zero though).
 160      *
 161      *  It's OK if the term doesn't occur in the range of positions
 162      *  specified (unlike @a remove_posting()).  And if
 163      *  term_pos_first > term_pos_last, this method does nothing.
 164      *
 165      *  @return The number of postings removed.
 166      */
 167     Xapian::termpos remove_postings(const std::string& term,
 168                                     Xapian::termpos term_pos_first,
 169                                     Xapian::termpos term_pos_last,
 170                                     Xapian::termcount wdf_dec = 1);
 171
 172     /// Clear all terms from the document.
 173     void clear_terms();
 174
 175     /// Return the number of distinct terms in this document.
 176     Xapian::termcount termlist_count() const;
 177
 178     /** Start iterating the terms in this document.
 179      *
 180      *  The terms are returned ascending string order (by byte value).
 181      */
 182     TermIterator termlist_begin() const;
 183
 184     /// End iterator corresponding to @a termlist_begin().
 185     TermIterator XAPIAN_NOTHROW(termlist_end() const) {
 186         return TermIterator();
 187     }
 188
 189     /** Read a value slot in this document.
 190      *
 191      *  @param slot     The slot to read the value from
 192      *
 193      *  @return The value in slot @a slot, or an empty string if not set.
 194      */
 195     std::string get_value(Xapian::valueno slot) const;
 196
 197     /** Add a value to a slot in this document.
 198      *
 199      *  @param slot     The slot to set
 200      *  @param value    The new value
 201      */
 202     void add_value(Xapian::valueno slot, const std::string& value);
 203
 204     /** Remove any value from the specified slot.
 205      *
 206      *  @param slot     The slot to remove any value from.
 207      */
 208     void remove_value(Xapian::valueno slot) {
 209         add_value(slot, std::string());
 210     }
 211
 212     /// Clear all value slots in this document.
 213     void clear_values();
 214
 215     /// Count the value slots used in this document.
 216     Xapian::valueno values_count() const;
 217
 218     /** Start iterating the values in this document.
 219      *
 220      *  The values are returned in ascending numerical slot order.
 221      */
 222     ValueIterator values_begin() const;
 223
 224     /// End iterator corresponding to @a values_begin().
 225     ValueIterator XAPIAN_NOTHROW(values_end() const) {
 226         return ValueIterator();
 227     }
 228
 229     /** Efficiently swap this Document object with another. */
 230     void swap(Document& o) { internal.swap(o.internal); }
 231
 232     /** Serialise document into a string.
 233      *
 234      *  The document representation may change between Xapian releases: even
 235      *  between minor versions.  However, it is guaranteed not to change if the
 236      *  remote database protocol has not changed between releases.
 237      */
 238     std::string serialise() const;
 239
 240     /** Unserialise a document from a string produced by serialise(). */
 241     static Document unserialise(const std::string& serialised);
 242
 243     /// Return a string describing this object.
 244     std::string get_description() const;
 245 };
 246
 247 }
 248
 249 #endif // XAPIAN_INCLUDED_DOCUMENT_H