LCOV - code coverage report
Current view: top level - include/xapian - document.h (source / functions) Hit Total Coverage
Test: Test Coverage for xapian-core 954b5873a738 Lines: 9 9 100.0 %
Date: 2019-06-30 05:20:33 Functions: 8 8 100.0 %
Branches: 1 2 50.0 %

           Branch data     Line data    Source code
       1                 :            : /** @file document.h
       2                 :            :  * @brief Class representing a document
       3                 :            :  */
       4                 :            : /* Copyright (C) 2010,2015,2016,2017,2018,2019 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                 :      42600 : 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                 :        313 :     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                 :            :      *
     151                 :            :      *  The instance of the specified term at position term_pos will be
     152                 :            :      *  removed, and the @a wdf reduced by @a wdf_dec (the wdf will not
     153                 :            :      *  ever go below zero though - the resultant wdf is clamped to zero
     154                 :            :      *  if it would).
     155                 :            :      *
     156                 :            :      *  If the term doesn't occur at position term_pos then
     157                 :            :      *  Xapian::InvalidArgumentError is thrown.  If you want to remove a single
     158                 :            :      *  position which may not be present without triggering an exception you
     159                 :            :      *  can call <code>remove_postings(term, pos, pos)</code> instead.
     160                 :            :      *
     161                 :            :      *  Since 1.5.0, if the final position is removed and the wdf becomes zero
     162                 :            :      *  then the term will be removed from the document.
     163                 :            :      */
     164                 :            :     void remove_posting(const std::string& term,
     165                 :            :                         Xapian::termpos term_pos,
     166                 :            :                         Xapian::termcount wdf_dec = 1);
     167                 :            : 
     168                 :            :     /** Remove a range of postings for a term.
     169                 :            :      *
     170                 :            :      *  Any instances of the term at positions >= @a term_pos_first and
     171                 :            :      *  <= @a term_pos_last will be removed, and the wdf reduced by
     172                 :            :      *  @a wdf_dec for each instance removed (the wdf will not ever go
     173                 :            :      *  below zero though - the resultant wdf is clamped to zero if it would).
     174                 :            :      *
     175                 :            :      *  If the term doesn't occur in the range of positions specified (including
     176                 :            :      *  if term_pos_first > term_pos_last) then this method does nothing (unlike
     177                 :            :      *  @a remove_posting() which throws an exception if the specified position
     178                 :            :      *  is not present).
     179                 :            :      *
     180                 :            :      *  Since 1.5.0, if all remaining positions are removed and the wdf becomes
     181                 :            :      *  zero then the term will be removed from the document.  Note that this
     182                 :            :      *  only happens if some positions are removed though - calling this method
     183                 :            :      *  on a term which has no positions and zero wdf won't remove that term.
     184                 :            :      *
     185                 :            :      *  @return The number of postings removed.
     186                 :            :      *
     187                 :            :      *  @since Added in Xapian 1.4.8.
     188                 :            :      */
     189                 :            :     Xapian::termpos remove_postings(const std::string& term,
     190                 :            :                                     Xapian::termpos term_pos_first,
     191                 :            :                                     Xapian::termpos term_pos_last,
     192                 :            :                                     Xapian::termcount wdf_dec = 1);
     193                 :            : 
     194                 :            :     /// Clear all terms from the document.
     195                 :            :     void clear_terms();
     196                 :            : 
     197                 :            :     /// Return the number of distinct terms in this document.
     198                 :            :     Xapian::termcount termlist_count() const;
     199                 :            : 
     200                 :            :     /** Start iterating the terms in this document.
     201                 :            :      *
     202                 :            :      *  The terms are returned ascending string order (by byte value).
     203                 :            :      */
     204                 :            :     TermIterator termlist_begin() const;
     205                 :            : 
     206                 :            :     /// End iterator corresponding to @a termlist_begin().
     207                 :    6040130 :     TermIterator XAPIAN_NOTHROW(termlist_end() const) {
     208                 :    6040130 :         return TermIterator();
     209                 :            :     }
     210                 :            : 
     211                 :            :     /** Read a value slot in this document.
     212                 :            :      *
     213                 :            :      *  @param slot     The slot to read the value from
     214                 :            :      *
     215                 :            :      *  @return The value in slot @a slot, or an empty string if not set.
     216                 :            :      */
     217                 :            :     std::string get_value(Xapian::valueno slot) const;
     218                 :            : 
     219                 :            :     /** Add a value to a slot in this document.
     220                 :            :      *
     221                 :            :      *  @param slot     The slot to set
     222                 :            :      *  @param value    The new value
     223                 :            :      */
     224                 :            :     void add_value(Xapian::valueno slot, const std::string& value);
     225                 :            : 
     226                 :            :     /** Remove any value from the specified slot.
     227                 :            :      *
     228                 :            :      *  @param slot     The slot to remove any value from.
     229                 :            :      */
     230                 :          3 :     void remove_value(Xapian::valueno slot) {
     231         [ +  - ]:          3 :         add_value(slot, std::string());
     232                 :          3 :     }
     233                 :            : 
     234                 :            :     /// Clear all value slots in this document.
     235                 :            :     void clear_values();
     236                 :            : 
     237                 :            :     /// Count the value slots used in this document.
     238                 :            :     Xapian::valueno values_count() const;
     239                 :            : 
     240                 :            :     /** Start iterating the values in this document.
     241                 :            :      *
     242                 :            :      *  The values are returned in ascending numerical slot order.
     243                 :            :      */
     244                 :            :     ValueIterator values_begin() const;
     245                 :            : 
     246                 :            :     /// End iterator corresponding to @a values_begin().
     247                 :    3213179 :     ValueIterator XAPIAN_NOTHROW(values_end() const) {
     248                 :    3213179 :         return ValueIterator();
     249                 :            :     }
     250                 :            : 
     251                 :            :     /** Efficiently swap this Document object with another. */
     252                 :            :     void swap(Document& o) { internal.swap(o.internal); }
     253                 :            : 
     254                 :            :     /** Serialise document into a string.
     255                 :            :      *
     256                 :            :      *  The document representation may change between Xapian releases: even
     257                 :            :      *  between minor versions.  However, it is guaranteed not to change if the
     258                 :            :      *  remote database protocol has not changed between releases.
     259                 :            :      */
     260                 :            :     std::string serialise() const;
     261                 :            : 
     262                 :            :     /** Unserialise a document from a string produced by serialise(). */
     263                 :            :     static Document unserialise(const std::string& serialised);
     264                 :            : 
     265                 :            :     /// Return a string describing this object.
     266                 :            :     std::string get_description() const;
     267                 :            : };
     268                 :            : 
     269                 :            : }
     270                 :            : 
     271                 :            : #endif // XAPIAN_INCLUDED_DOCUMENT_H

Generated by: LCOV version 1.11