xapian-core/include/xapian/document.h

   1 /** @file document.h
   2  * @brief Class representing a document
   3  */
   4 /* Copyright (C) 2010,2015,2016,2017 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     /** Default constructor.
  88      *
  89      *  Creates an empty Document.
  90      */
  91     Document();
  92
  93     /// Destructor.
  94     ~Document();
  95
  96     /** Get the document ID this document came from.
  97      *
  98      *  If this document didn't come from a database, this will be 0 (in Xapian
  99      *  1.0.22/1.2.4 or later; prior to this the returned value was uninitialised
 100      *  in this case).
 101      *
 102      *  Note that if the document came from a sharded database, this is the docid
 103      *  in the shard it came from, not the docid in the combined database.
 104      */
 105     Xapian::docid get_docid() const;
 106
 107     /// Get the document data.
 108     std::string get_data() const;
 109
 110     /// Set the document data.
 111     void set_data(const std::string& data);
 112
 113     /// Add a term to this document.
 114     void add_term(const std::string& term, Xapian::termcount wdf_inc = 1);
 115
 116     /** Add a boolean filter term to the document.
 117      *
 118      *  This method adds @a term to the document with wdf of 0 -
 119      *  this is generally what you want for a term used for boolean
 120      *  filtering as the wdf of such terms is ignored, and it doesn't
 121      *  make sense for them to contribute to the document's length.
 122      *
 123      *  If the specified term already indexes this document, this method
 124      *  has no effect.
 125      *
 126      *  It is exactly the same as add_term(term, 0) and is provided as a
 127      *  way to make a common operation more explicit.
 128      *
 129      *  This method was added in Xapian 1.0.18.
 130      *
 131      *  @param term             The term to add.
 132      */
 133     void add_boolean_term(const std::string& term) { add_term(term, 0); }
 134
 135     /// Remove a term from this document.
 136     void remove_term(const std::string& term);
 137
 138     /// Add a posting for a term.
 139     void add_posting(const std::string& term,
 140                      Xapian::termpos term_pos,
 141                      Xapian::termcount wdf_inc = 1);
 142
 143     /// Remove posting for a term.
 144     void remove_posting(const std::string& term,
 145                         Xapian::termpos term_pos,
 146                         Xapian::termcount wdf_dec = 1);
 147
 148     /// Clear all terms from the document.
 149     void clear_terms();
 150
 151     /// Return the number of distinct terms in this document.
 152     Xapian::termcount termlist_count() const;
 153
 154     /** Start iterating the terms in this document.
 155      *
 156      *  The terms are returned ascending string order (by byte value).
 157      */
 158     TermIterator termlist_begin() const;
 159
 160     /// End iterator corresponding to @a termlist_begin().
 161     TermIterator XAPIAN_NOTHROW(termlist_end() const) {
 162         return TermIterator();
 163     }
 164
 165     /** Read a value slot in this document.
 166      *
 167      *  @param slot     The slot to read the value from
 168      *
 169      *  @return The value in slot @a slot, or an empty string if not set.
 170      */
 171     std::string get_value(Xapian::valueno slot) const;
 172
 173     /** Add a value to a slot in this document.
 174      *
 175      *  @param slot     The slot to set
 176      *  @param value    The new value
 177      */
 178     void add_value(Xapian::valueno slot, const std::string& value);
 179
 180     /** Remove any value from the specified slot.
 181      *
 182      *  @param slot     The slot to remove any value from.
 183      */
 184     void remove_value(Xapian::valueno slot) {
 185         add_value(slot, std::string());
 186     }
 187
 188     /// Clear all value slots in this document.
 189     void clear_values();
 190
 191     /// Count the value slots used in this document.
 192     Xapian::valueno values_count() const;
 193
 194     /** Start iterating the values in this document.
 195      *
 196      *  The values are returned in ascending numerical slot order.
 197      */
 198     ValueIterator values_begin() const;
 199
 200     /// End iterator corresponding to @a values_begin().
 201     ValueIterator XAPIAN_NOTHROW(values_end() const) {
 202         return ValueIterator();
 203     }
 204
 205     /** Efficiently swap this Document object with another. */
 206     void swap(Document& o) { internal.swap(o.internal); }
 207
 208     /** Serialise document into a string.
 209      *
 210      *  The document representation may change between Xapian releases: even
 211      *  between minor versions.  However, it is guaranteed not to change if the
 212      *  remote database protocol has not changed between releases.
 213      */
 214     std::string serialise() const;
 215
 216     /** Unserialise a document from a string produced by serialise(). */
 217     static Document unserialise(const std::string& serialised);
 218
 219     /// Return a string describing this object.
 220     std::string get_description() const;
 221 };
 222
 223 }
 224
 225 #endif // XAPIAN_INCLUDED_DOCUMENT_H