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

           Branch data     Line data    Source code
       1                 :            : /** @file database.h
       2                 :            :  * @brief An indexed database of documents
       3                 :            :  */
       4                 :            : /* Copyright 2003,2004,2005,2006,2007,2008,2009,2011,2012,2013,2014,2015,2016,2017,2018,2019 Olly Betts
       5                 :            :  * Copyright 2007,2008,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_DATABASE_H
      24                 :            : #define XAPIAN_INCLUDED_DATABASE_H
      25                 :            : 
      26                 :            : #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
      27                 :            : # error "Never use <xapian/database.h> directly; include <xapian.h> instead."
      28                 :            : #endif
      29                 :            : 
      30                 :            : #include <iosfwd>
      31                 :            : #include <string>
      32                 :            : #include <utility>
      33                 :            : #include <vector>
      34                 :            : 
      35                 :            : #include <xapian/attributes.h>
      36                 :            : #include <xapian/intrusive_ptr.h>
      37                 :            : #include <xapian/positioniterator.h>
      38                 :            : #include <xapian/postingiterator.h>
      39                 :            : #include <xapian/termiterator.h>
      40                 :            : #include <xapian/types.h>
      41                 :            : #include <xapian/valueiterator.h>
      42                 :            : #include <xapian/visibility.h>
      43                 :            : 
      44                 :            : namespace Xapian {
      45                 :            : 
      46                 :            : class Compactor;
      47                 :            : class Document;
      48                 :            : 
      49                 :            : /** An indexed database of documents.
      50                 :            :  *
      51                 :            :  *  A Database object contains zero or more shards, and operations are
      52                 :            :  *  performed across these shards.
      53                 :            :  *
      54                 :            :  *  To perform a search on a Database, you need to use an Enquire object.
      55                 :            :  *
      56                 :            :  *  @since 1.5.0 This class is a reference counted handle like many other
      57                 :            :  *         Xapian API classes.  In earlier versions, it worked like a typedef
      58                 :            :  *         to std::vector<database_shard>.  The key difference is that
      59                 :            :  *         previously copying or assigning a Xapian::Database made a deep copy,
      60                 :            :  *         whereas now it makes a shallow copy.
      61                 :            :  *
      62                 :            :  *  Most methods can throw:
      63                 :            :  *
      64                 :            :  *  @exception Xapian::DatabaseCorruptError if database corruption is detected
      65                 :            :  *  @exception Xapian::DatabaseError in various situation (for example, calling
      66                 :            :  *             methods after @a close() has been called)
      67                 :            :  *  @exception Xapian::DatabaseModifiedError if the revision being read has
      68                 :            :  *             been discarded
      69                 :            :  *  @exception Xapian::NetworkError when remote databases are in use
      70                 :            :  */
      71                 :    1109946 : class XAPIAN_VISIBILITY_DEFAULT Database {
      72                 :            :     /// @internal Implementation behind check() static methods.
      73                 :            :     static size_t check_(const std::string* path_ptr,
      74                 :            :                          int fd,
      75                 :            :                          int opts,
      76                 :            :                          std::ostream* out);
      77                 :            : 
      78                 :            :     /// @internal Implementation behind public compact() methods.
      79                 :            :     void compact_(const std::string* output_ptr,
      80                 :            :                   int fd,
      81                 :            :                   unsigned flags,
      82                 :            :                   int block_size,
      83                 :            :                   Xapian::Compactor* compactor) const;
      84                 :            : 
      85                 :            :   protected:
      86                 :            :     /// @private @internal Implementation behind public add_database() methods.
      87                 :            :     void add_database_(const Database& other, bool read_only);
      88                 :            : 
      89                 :            :   public:
      90                 :            :     /// Class representing the Database internals.
      91                 :            :     class Internal;
      92                 :            :     /// @private @internal Reference counted internals.
      93                 :            :     Xapian::Internal::intrusive_ptr_nonnull<Internal> internal;
      94                 :            : 
      95                 :            :     /** Add shards from another Database.
      96                 :            :      *
      97                 :            :      *  Any shards in @a other are appended to the list of shards in this
      98                 :            :      *  object.  The shards are reference counted and also remain in @a other.
      99                 :            :      *
     100                 :            :      *  @param other    Another Database to add shards from
     101                 :            :      *
     102                 :            :      *  @exception Xapian::InvalidArgumentError if @a other is the same object
     103                 :            :      *             as this.
     104                 :            :      */
     105                 :        975 :     void add_database(const Database& other) {
     106                 :        975 :         add_database_(other, true);
     107                 :        975 :     }
     108                 :            : 
     109                 :            :     /** Return number of shards in this Database object. */
     110                 :            :     size_t size() const;
     111                 :            : 
     112                 :            :     /** Construct a Database containing no shards.
     113                 :            :      *
     114                 :            :      *  You can then add shards by calling add_database().  A Database
     115                 :            :      *  containing no shards can also be useful in situations where you need an
     116                 :            :      *  empty database.
     117                 :            :      */
     118                 :            :     Database();
     119                 :            : 
     120                 :            :     /** Open a Database.
     121                 :            :      *
     122                 :            :      *  @param path     Filing system path to open database from
     123                 :            :      *  @param flags    Bitwise-or of Xapian::DB_* constants
     124                 :            :      *
     125                 :            :      *  The @a path can be a file (for a stub database or a single-file glass
     126                 :            :      *  database) or a directory (for a standard glass database).  If
     127                 :            :      *  @a flags includes @a DB_BACKEND_INMEMORY then @a path is ignored.
     128                 :            :      *
     129                 :            :      *  @exception Xapian::DatabaseOpeningError if the specified database
     130                 :            :      *             cannot be opened
     131                 :            :      *  @exception Xapian::DatabaseVersionError if the specified database has
     132                 :            :      *             a format too old or too new to be supported.
     133                 :            :      */
     134                 :            :     explicit Database(const std::string& path, int flags = 0);
     135                 :            : 
     136                 :            :     /** Open a single-file Database.
     137                 :            :      *
     138                 :            :      *  This method opens a single-file Database given a file descriptor open
     139                 :            :      *  on it.  Xapian looks starting at the current file offset, allowing a
     140                 :            :      *  single file database to be easily embedded within another file.
     141                 :            :      *
     142                 :            :      *  @param fd       File descriptor for the file.  Xapian takes ownership
     143                 :            :      *                  of this and will close it when the database is closed.
     144                 :            :      *  @param flags    Bitwise-or of Xapian::DB_* constants.
     145                 :            :      *
     146                 :            :      *  @exception Xapian::DatabaseOpeningError if the specified database
     147                 :            :      *             cannot be opened
     148                 :            :      *  @exception Xapian::DatabaseVersionError if the specified database has
     149                 :            :      *             a format too old or too new to be supported.
     150                 :            :      */
     151                 :            :     explicit Database(int fd, int flags = 0);
     152                 :            : 
     153                 :            :     /// @private @internal Wrap an existing Internal.
     154                 :            :     XAPIAN_VISIBILITY_INTERNAL
     155                 :            :     explicit Database(Internal* internal) XAPIAN_NONNULL();
     156                 :            : 
     157                 :            :     /// Destructor.
     158                 :            :     virtual ~Database();
     159                 :            : 
     160                 :            :     /** Copy constructor.
     161                 :            :      *
     162                 :            :      *  The internals are reference counted, so copying is cheap.
     163                 :            :      */
     164                 :            :     Database(const Database& o);
     165                 :            : 
     166                 :            :     /** Assignment operator.
     167                 :            :      *
     168                 :            :      *  The internals are reference counted, so assignment is cheap.
     169                 :            :      */
     170                 :            :     Database& operator=(const Database& o);
     171                 :            : 
     172                 :            :     /// Move constructor.
     173                 :            :     Database(Database&& o);
     174                 :            : 
     175                 :            :     /// Move assignment operator.
     176                 :            :     Database& operator=(Database&& o);
     177                 :            : 
     178                 :            :     /** Reopen the database at the latest available revision.
     179                 :            :      *
     180                 :            :      *  Xapian databases (at least with most backends) support versioning
     181                 :            :      *  such that a Database object uses a snapshot of the database.
     182                 :            :      *  However, write operations may cause this snapshot to be discarded,
     183                 :            :      *  which can cause Xapian::DatabaseModifiedError to be thrown.  You
     184                 :            :      *  can recover from this situation by calling reopen() and restarting
     185                 :            :      *  the search operation.
     186                 :            :      *
     187                 :            :      *  All shards are updated to the latest available revision.  This should
     188                 :            :      *  be a cheap operation if they're already at the latest revision, so
     189                 :            :      *  if you're using the same Database object for many searches it's
     190                 :            :      *  reasonable to call reopen() before each search.
     191                 :            :      *
     192                 :            :      *  @return true if one or more shards have moved to a newer revision
     193                 :            :      *          (if false is returned then it's definitely the case that no
     194                 :            :      *          shards were reopened, which applications may find useful when
     195                 :            :      *          caching results, etc).  In Xapian < 1.3.0, this method did not
     196                 :            :      *          return a value.
     197                 :            :      *
     198                 :            :      *  @exception Xapian::DatabaseError is thrown if close() has been called
     199                 :            :      *             on any of the shards.
     200                 :            :      */
     201                 :            :     bool reopen();
     202                 :            : 
     203                 :            :     /** Close the database.
     204                 :            :      *
     205                 :            :      *  This closes the database and closes all its file handles.
     206                 :            :      *
     207                 :            :      *  For a WritableDatabase, if a transaction is active it will be aborted,
     208                 :            :      *  while if no transaction is active commit() will be implicitly called.
     209                 :            :      *  Also the write lock is released.
     210                 :            :      *
     211                 :            :      *  Closing a database cannot be undone - in particular, calling reopen()
     212                 :            :      *  after close() will not reopen it, but will instead throw a
     213                 :            :      *  Xapian::DatabaseError exception.
     214                 :            :      *
     215                 :            :      *  Calling close() again on a database which has already been closed has
     216                 :            :      *  no effect (and doesn't raise an exception).
     217                 :            :      *
     218                 :            :      *  After close() has been called, calls to other methods of the database,
     219                 :            :      *  and to methods of other objects associated with the database, will
     220                 :            :      *  either:
     221                 :            :      *
     222                 :            :      *   - behave exactly as they would have done if the database had not been
     223                 :            :      *     closed (this can only happen if all the required data is cached)
     224                 :            :      *
     225                 :            :      *   - raise a Xapian::DatabaseError exception indicating that the database
     226                 :            :      *     is closed.
     227                 :            :      *
     228                 :            :      *  The reason for this behaviour is that otherwise we'd have to check that
     229                 :            :      *  the database is still open on every method call on every object
     230                 :            :      *  associated with a Database, when in many cases they are working on data
     231                 :            :      *  which has already been loaded and so they are able to just behave
     232                 :            :      *  correctly.
     233                 :            :      *
     234                 :            :      *  @since This method was added in Xapian 1.1.0.
     235                 :            :      */
     236                 :            :     virtual void close();
     237                 :            : 
     238                 :            :     /// Return a string describing this object.
     239                 :            :     virtual std::string get_description() const;
     240                 :            : 
     241                 :            :     /** Start iterating the postings of a term.
     242                 :            :      *
     243                 :            :      *  @param term     The term to iterate the postings of.  An empty string
     244                 :            :      *                  acts as a special pseudo-term which indexes all the
     245                 :            :      *                  documents in the database with a wdf of 1.
     246                 :            :      */
     247                 :            :     PostingIterator postlist_begin(const std::string& term) const;
     248                 :            : 
     249                 :            :     /** End iterator corresponding to postlist_begin(). */
     250                 :      97268 :     PostingIterator XAPIAN_NOTHROW(postlist_end(const std::string&) const) {
     251                 :      97268 :         return PostingIterator();
     252                 :            :     }
     253                 :            : 
     254                 :            :     /** Start iterating the terms in a document.
     255                 :            :      *
     256                 :            :      *  @param did      The document id to iterate terms from
     257                 :            :      *
     258                 :            :      *  The terms are returned ascending string order (by byte value).
     259                 :            :      */
     260                 :            :     TermIterator termlist_begin(Xapian::docid did) const;
     261                 :            : 
     262                 :            :     /** End iterator corresponding to termlist_begin(). */
     263                 :      74914 :     TermIterator XAPIAN_NOTHROW(termlist_end(Xapian::docid) const) {
     264                 :      74914 :         return TermIterator();
     265                 :            :     }
     266                 :            : 
     267                 :            :     /** Does this database have any positional information? */
     268                 :            :     bool has_positions() const;
     269                 :            : 
     270                 :            :     /** Start iterating positions for a term in a document.
     271                 :            :      *
     272                 :            :      *  @param did      The document id of the document
     273                 :            :      *  @param term     The term
     274                 :            :      *
     275                 :            :      *  @since 1.1.0    If the specified document doesn't exist or the
     276                 :            :      *                  specified term doesn't exist in the specified document,
     277                 :            :      *                  then a valid iterator is still returned, but it will be
     278                 :            :      *                  equal to positionlist_end().
     279                 :            :      */
     280                 :            :     PositionIterator positionlist_begin(Xapian::docid did, const std::string& term) const;
     281                 :            : 
     282                 :            :     /** End iterator corresponding to positionlist_begin(). */
     283                 :      17094 :     PositionIterator XAPIAN_NOTHROW(positionlist_end(Xapian::docid, const std::string&) const) {
     284                 :      17094 :         return PositionIterator();
     285                 :            :     }
     286                 :            : 
     287                 :            :     /** Start iterating all terms in the database with a given prefix.
     288                 :            :      *
     289                 :            :      *  @param prefix   The prefix to restrict the returned terms to (default:
     290                 :            :      *                  iterate all terms)
     291                 :            :      */
     292                 :            :     TermIterator allterms_begin(const std::string& prefix = std::string()) const;
     293                 :            : 
     294                 :            :     /** End iterator corresponding to allterms_begin(prefix). */
     295                 :       5989 :     TermIterator XAPIAN_NOTHROW(allterms_end(const std::string& = std::string()) const) {
     296                 :       5989 :         return TermIterator();
     297                 :            :     }
     298                 :            : 
     299                 :            :     /// Get the number of documents in the database.
     300                 :            :     Xapian::doccount get_doccount() const;
     301                 :            : 
     302                 :            :     /// Get the highest document id which has been used in the database.
     303                 :            :     Xapian::docid get_lastdocid() const;
     304                 :            : 
     305                 :            :     /// Get the mean document length in the database.
     306                 :            :     double get_average_length() const;
     307                 :            : 
     308                 :            :     /// Old name for get_average_length() for backward compatibility.
     309                 :       6056 :     double get_avlength() const { return get_average_length(); }
     310                 :            : 
     311                 :            :     /** Get the total length of all the documents in the database.
     312                 :            :      *
     313                 :            :      *  @since Added in Xapian 1.4.5.
     314                 :            :      */
     315                 :            :     Xapian::totallength get_total_length() const;
     316                 :            : 
     317                 :            :     /** Get the number of documents indexed by a specified term.
     318                 :            :      *
     319                 :            :      *  @param term     The term to get the frequency of.  An empty string
     320                 :            :      *                  acts as a special pseudo-term which indexes all the
     321                 :            :      *                  documents in the database, so returns get_doccount().
     322                 :            :      *                  If the term isn't present in the database, 0 is
     323                 :            :      *                  returned.
     324                 :            :      */
     325                 :            :     Xapian::doccount get_termfreq(const std::string& term) const;
     326                 :            : 
     327                 :            :     /** Test is a particular term is present in any document.
     328                 :            :      *
     329                 :            :      *  @param term     The term to test for.  An empty string acts as a
     330                 :            :      *                  special pseudo-term which indexes all the documents in
     331                 :            :      *                  the database, so returns true if the database contains
     332                 :            :      *                  any documents.
     333                 :            :      *
     334                 :            :      *  db.term_exists(t) gives the same answer as db.get_termfreq(t) != 0, but
     335                 :            :      *  is typically more efficient.
     336                 :            :      */
     337                 :            :     bool term_exists(const std::string& term) const;
     338                 :            : 
     339                 :            :     /** Get the total number of occurrences of a specified term.
     340                 :            :      *
     341                 :            :      *  The collection frequency of a term is defined as the total number of
     342                 :            :      *  times it occurs in the database, which is the sum of its wdf in all the
     343                 :            :      *  documents it indexes.
     344                 :            :      *
     345                 :            :      *  @param term     The term to get the collection frequency of.  An empty
     346                 :            :      *                  string acts as a special pseudo-term which indexes all
     347                 :            :      *                  the documents in the database, so returns
     348                 :            :      *                  get_doccount().  If the term isn't present in the
     349                 :            :      *                  database, 0 is returned.
     350                 :            :      */
     351                 :            :     Xapian::termcount get_collection_freq(const std::string& term) const;
     352                 :            : 
     353                 :            :     /** Return the frequency of a given value slot.
     354                 :            :      *
     355                 :            :      *  This is the number of documents which have a (non-empty) value stored
     356                 :            :      *  in the slot.
     357                 :            :      *
     358                 :            :      *  @param slot The value slot to examine.
     359                 :            :      */
     360                 :            :     Xapian::doccount get_value_freq(Xapian::valueno slot) const;
     361                 :            : 
     362                 :            :     /** Get a lower bound on the values stored in the given value slot.
     363                 :            :      *
     364                 :            :      *  If there are no values stored in the given value slot, this will return
     365                 :            :      *  an empty string.
     366                 :            :      *
     367                 :            :      *  @param slot The value slot to examine.
     368                 :            :      */
     369                 :            :     std::string get_value_lower_bound(Xapian::valueno slot) const;
     370                 :            : 
     371                 :            :     /** Get an upper bound on the values stored in the given value slot.
     372                 :            :      *
     373                 :            :      *  If there are no values stored in the given value slot, this will return
     374                 :            :      *  an empty string.
     375                 :            :      *
     376                 :            :      *  @param slot The value slot to examine.
     377                 :            :      */
     378                 :            :     std::string get_value_upper_bound(Xapian::valueno slot) const;
     379                 :            : 
     380                 :            :     /** Get a lower bound on the length of a document in this DB.
     381                 :            :      *
     382                 :            :      *  This bound does not include any zero-length documents.
     383                 :            :      */
     384                 :            :     Xapian::termcount get_doclength_lower_bound() const;
     385                 :            : 
     386                 :            :     /// Get an upper bound on the length of a document in this DB.
     387                 :            :     Xapian::termcount get_doclength_upper_bound() const;
     388                 :            : 
     389                 :            :     /// Get an upper bound on the wdf of term @a term.
     390                 :            :     Xapian::termcount get_wdf_upper_bound(const std::string& term) const;
     391                 :            : 
     392                 :            :     /// Get a lower bound on the unique terms size of a document in this DB.
     393                 :            :     Xapian::termcount get_unique_terms_lower_bound() const;
     394                 :            : 
     395                 :            :     /// Get an upper bound on the unique terms size of a document in this DB.
     396                 :            :     Xapian::termcount get_unique_terms_upper_bound() const;
     397                 :            : 
     398                 :            :     /// Return an iterator over the value in slot @a slot for each document.
     399                 :            :     ValueIterator valuestream_begin(Xapian::valueno slot) const;
     400                 :            : 
     401                 :            :     /// Return end iterator corresponding to valuestream_begin().
     402                 :     195071 :     ValueIterator XAPIAN_NOTHROW(valuestream_end(Xapian::valueno) const) {
     403                 :     195071 :         return ValueIterator();
     404                 :            :     }
     405                 :            : 
     406                 :            :     /** Get the length of a document.
     407                 :            :      *
     408                 :            :      *  @param did   The document id of the document
     409                 :            :      *
     410                 :            :      *  Xapian defines a document's length as the sum of the wdf of all the
     411                 :            :      *  terms which index it.
     412                 :            :      */
     413                 :            :     Xapian::termcount get_doclength(Xapian::docid did) const;
     414                 :            : 
     415                 :            :     /** Get the number of unique terms in a document.
     416                 :            :      *
     417                 :            :      *  @param did   The document id of the document
     418                 :            :      *
     419                 :            :      *  This is the number of different terms which index the given document.
     420                 :            :      */
     421                 :            :     Xapian::termcount get_unique_terms(Xapian::docid did) const;
     422                 :            : 
     423                 :            :     /** Send a keep-alive message.
     424                 :            :      *
     425                 :            :      *  For remote databases, this method sends a message to the server to
     426                 :            :      *  reset the timeout timer.  As well as preventing timeouts at the Xapian
     427                 :            :      *  remote protocol level, this message will also avoid timeouts at lower
     428                 :            :      *  levels.
     429                 :            :      *
     430                 :            :      *  For local databases, this method does nothing.
     431                 :            :      */
     432                 :            :     void keep_alive();
     433                 :            : 
     434                 :            :     /** Get a document from the database.
     435                 :            :      *
     436                 :            :      *  The returned object acts as a handle which lazily fetches information
     437                 :            :      *  about the specified document from the database.
     438                 :            :      *
     439                 :            :      *  @param did      The document ID of the document to be get
     440                 :            :      *  @param flags    Zero or more flags bitwise-or-ed together (currently
     441                 :            :      *                  only Xapian::DOC_ASSUME_VALID is supported).
     442                 :            :      *                  (default: 0)
     443                 :            :      *
     444                 :            :      *  @exception Xapian::InvalidArgumentError is thrown if @a did is 0.
     445                 :            :      *
     446                 :            :      *  @exception Xapian::DocNotFoundError is thrown if the specified docid
     447                 :            :      *             is not present in this database.
     448                 :            :      */
     449                 :            :     Xapian::Document get_document(Xapian::docid did,
     450                 :            :                                   unsigned flags = 0) const;
     451                 :            : 
     452                 :            :     /** Suggest a spelling correction.
     453                 :            :      *
     454                 :            :      *  @param word                     The potentially misspelled word.
     455                 :            :      *  @param max_edit_distance        Only consider words which are at most
     456                 :            :      *                                  @a max_edit_distance edits from @a
     457                 :            :      *                                  word.  An edit is a character
     458                 :            :      *                                  insertion, deletion, or the
     459                 :            :      *                                  transposition of two adjacent
     460                 :            :      *                                  characters (default is 2).
     461                 :            :      */
     462                 :            :     std::string get_spelling_suggestion(const std::string& word,
     463                 :            :                                         unsigned max_edit_distance = 2) const;
     464                 :            : 
     465                 :            :     /** An iterator which returns all the spelling correction targets.
     466                 :            :      *
     467                 :            :      *  This returns all the words which are considered as targets for the
     468                 :            :      *  spelling correction algorithm.  The frequency of each word is available
     469                 :            :      *  as the term frequency of each entry in the returned iterator.
     470                 :            :      */
     471                 :            :     Xapian::TermIterator spellings_begin() const;
     472                 :            : 
     473                 :            :     /// End iterator corresponding to spellings_begin().
     474                 :         15 :     Xapian::TermIterator XAPIAN_NOTHROW(spellings_end() const) {
     475                 :         15 :         return Xapian::TermIterator();
     476                 :            :     }
     477                 :            : 
     478                 :            :     /** An iterator which returns all the synonyms for a given term.
     479                 :            :      *
     480                 :            :      *  @param term     The term to return synonyms for.
     481                 :            :      */
     482                 :            :     Xapian::TermIterator synonyms_begin(const std::string& term) const;
     483                 :            : 
     484                 :            :     /// End iterator corresponding to synonyms_begin(term).
     485                 :      68709 :     Xapian::TermIterator XAPIAN_NOTHROW(synonyms_end(const std::string&) const) {
     486                 :      68709 :         return Xapian::TermIterator();
     487                 :            :     }
     488                 :            : 
     489                 :            :     /** An iterator which returns all terms which have synonyms.
     490                 :            :      *
     491                 :            :      *  @param prefix   If non-empty, only terms with this prefix are returned.
     492                 :            :      */
     493                 :            :     Xapian::TermIterator synonym_keys_begin(const std::string& prefix = std::string()) const;
     494                 :            : 
     495                 :            :     /// End iterator corresponding to synonym_keys_begin(prefix).
     496                 :      20704 :     Xapian::TermIterator XAPIAN_NOTHROW(synonym_keys_end(const std::string& = std::string()) const) {
     497                 :      20704 :         return Xapian::TermIterator();
     498                 :            :     }
     499                 :            : 
     500                 :            :     /** Get the user-specified metadata associated with a given key.
     501                 :            :      *
     502                 :            :      *  User-specified metadata allows you to store arbitrary information in
     503                 :            :      *  the form of (key, value) pairs.  See @a
     504                 :            :      *  WritableDatabase::set_metadata() for more information.
     505                 :            :      *
     506                 :            :      *  When invoked on a Xapian::Database object representing multiple
     507                 :            :      *  databases, currently only the metadata for the first is considered but
     508                 :            :      *  this behaviour may change in the future.
     509                 :            :      *
     510                 :            :      *  If there is no piece of metadata associated with the specified key, an
     511                 :            :      *  empty string is returned (this applies even for backends which don't
     512                 :            :      *  support metadata).
     513                 :            :      *
     514                 :            :      *  Empty keys are not valid, and specifying one will cause an exception.
     515                 :            :      *
     516                 :            :      *  @param key The key of the metadata item to access.
     517                 :            :      *
     518                 :            :      *  @return    The retrieved metadata item's value.
     519                 :            :      *
     520                 :            :      *  @exception Xapian::InvalidArgumentError will be thrown if the key
     521                 :            :      *             supplied is empty.
     522                 :            :      */
     523                 :            :     std::string get_metadata(const std::string& key) const;
     524                 :            : 
     525                 :            :     /** An iterator which returns all user-specified metadata keys.
     526                 :            :      *
     527                 :            :      *  When invoked on a Xapian::Database object representing multiple
     528                 :            :      *  databases, currently only the metadata for the first is considered but
     529                 :            :      *  this behaviour may change in the future.
     530                 :            :      *
     531                 :            :      *  If the backend doesn't support metadata, then this method returns an
     532                 :            :      *  iterator which compares equal to that returned by metadata_keys_end().
     533                 :            :      *
     534                 :            :      *  @param prefix   If non-empty, only keys with this prefix are returned.
     535                 :            :      *
     536                 :            :      *  @exception Xapian::UnimplementedError will be thrown if the backend
     537                 :            :      *             implements user-specified metadata, but doesn't implement
     538                 :            :      *             iterating its keys (currently this happens for the InMemory
     539                 :            :      *             backend).
     540                 :            :      */
     541                 :            :     Xapian::TermIterator metadata_keys_begin(const std::string&prefix = std::string()) const;
     542                 :            : 
     543                 :            :     /// End iterator corresponding to metadata_keys_begin().
     544                 :        154 :     Xapian::TermIterator XAPIAN_NOTHROW(metadata_keys_end(const std::string& = std::string()) const) {
     545                 :        154 :         return Xapian::TermIterator();
     546                 :            :     }
     547                 :            : 
     548                 :            :     /** Get a UUID for the database.
     549                 :            :      *
     550                 :            :      *  The UUID will persist for the lifetime of the database.
     551                 :            :      *
     552                 :            :      *  Replicas (eg, made with the replication protocol, or by copying all the
     553                 :            :      *  database files) will have the same UUID.  However, copies (made with
     554                 :            :      *  copydatabase, or xapian-compact) will have different UUIDs.
     555                 :            :      *
     556                 :            :      *  If the backend does not support UUIDs or this database has no
     557                 :            :      *  subdatabases, the UUID will be empty.
     558                 :            :      *
     559                 :            :      *  If this database has multiple sub-databases, the UUID string will
     560                 :            :      *  contain the UUIDs of all the sub-databases separated by colons.
     561                 :            :      */
     562                 :            :     std::string get_uuid() const;
     563                 :            : 
     564                 :            :     /** Test if this database is currently locked for writing.
     565                 :            :      *
     566                 :            :      *  If the underlying object is actually a WritableDatabase, always returns
     567                 :            :      *  true.
     568                 :            :      *
     569                 :            :      *  Otherwise tests if there's a writer holding the lock (or if we can't
     570                 :            :      *  test for a lock without taking it on the current platform, throw
     571                 :            :      *  Xapian::UnimplementedError).  If there's an error while trying to test
     572                 :            :      *  the lock, throws Xapian::DatabaseLockError.
     573                 :            :      *
     574                 :            :      *  For multi-databases, this tests each sub-database and returns true if
     575                 :            :      *  any of them are locked.
     576                 :            :      */
     577                 :            :     bool locked() const;
     578                 :            : 
     579                 :            :     /** Get the revision of the database.
     580                 :            :      *
     581                 :            :      *  The revision is an unsigned integer which increases with each commit.
     582                 :            :      *
     583                 :            :      *  The database must have exactly one sub-database, which must be of type
     584                 :            :      *  glass.  Otherwise an exception will be thrown.
     585                 :            :      *
     586                 :            :      *  Experimental - see
     587                 :            :      *  https://xapian.org/docs/deprecation#experimental-features
     588                 :            :      */
     589                 :            :     Xapian::rev get_revision() const;
     590                 :            : 
     591                 :            :     /** Check the integrity of a database or database table.
     592                 :            :      *
     593                 :            :      *  @param path     Path to database or table
     594                 :            :      *  @param opts     Options to use for check
     595                 :            :      *  @param out      std::ostream to write output to (NULL for no output)
     596                 :            :      */
     597                 :         28 :     static size_t check(const std::string& path,
     598                 :            :                         int opts = 0,
     599                 :            :                         std::ostream* out = NULL) {
     600                 :         28 :         return check_(&path, 0, opts, out);
     601                 :            :     }
     602                 :            : 
     603                 :            :     /** Check the integrity of a single file database.
     604                 :            :      *
     605                 :            :      *  @param fd       file descriptor for the database.  The current file
     606                 :            :      *                  offset is used, allowing checking a single file
     607                 :            :      *                  database which is embedded within another file.  Xapian
     608                 :            :      *                  takes ownership of the file descriptor and will close
     609                 :            :      *                  it before returning.
     610                 :            :      *  @param opts     Options to use for check
     611                 :            :      *  @param out      std::ostream to write output to (NULL for no output)
     612                 :            :      */
     613                 :          1 :     static size_t check(int fd, int opts = 0, std::ostream* out = NULL) {
     614                 :          1 :         return check_(NULL, fd, opts, out);
     615                 :            :     }
     616                 :            : 
     617                 :            :     /** Produce a compact version of this database.
     618                 :            :      *
     619                 :            :      *  New 1.3.4.  Various methods of the Compactor class were deprecated in
     620                 :            :      *  1.3.4.
     621                 :            :      *
     622                 :            :      *  @param output   Path to write the compact version to.  This can be the
     623                 :            :      *                  same as an input if that input is a stub database (in
     624                 :            :      *                  which case the database(s) listed in the stub will be
     625                 :            :      *                  compacted to a new database and then the stub will be
     626                 :            :      *                  atomically updated to point to this new database).
     627                 :            :      *
     628                 :            :      *  @param flags    Any of the following combined using bitwise-or (| in
     629                 :            :      *                  C++):
     630                 :            :      *   - Xapian::DBCOMPACT_NO_RENUMBER By default the document ids will
     631                 :            :      *          be renumbered the output - currently by applying the same
     632                 :            :      *          offset to all the document ids in a particular source database.
     633                 :            :      *          If this flag is specified, then this renumbering doesn't
     634                 :            :      *          happen, but all the document ids must be unique over all source
     635                 :            :      *          databases.  Currently the ranges of document ids in each source
     636                 :            :      *          must not overlap either, though this restriction may be removed
     637                 :            :      *          in the future.
     638                 :            :      *   - Xapian::DBCOMPACT_MULTIPASS
     639                 :            :      *          If merging more than 3 databases, merge the postlists in
     640                 :            :      *          multiple passes, which is generally faster but requires more
     641                 :            :      *          disk space for temporary files.
     642                 :            :      *   - Xapian::DBCOMPACT_SINGLE_FILE
     643                 :            :      *          Produce a single-file database (only supported for glass
     644                 :            :      *          currently).
     645                 :            :      *   - At most one of:
     646                 :            :      *     - Xapian::Compactor::STANDARD - Don't split items unnecessarily.
     647                 :            :      *     - Xapian::Compactor::FULL     - Split items whenever it saves space
     648                 :            :      *                                     (the default).
     649                 :            :      *     - Xapian::Compactor::FULLER   - Allow oversize items to save more
     650                 :            :      *                                     space (not recommended if you ever
     651                 :            :      *                                     plan to update the compacted
     652                 :            :      *                                     database).
     653                 :            :      *   - At most one of the following to specify the output format (currently
     654                 :            :      *     only glass to honey conversion is supported, and all shards of the
     655                 :            :      *     input must have the same format):
     656                 :            :      *     - Xapian::DB_BACKEND_HONEY
     657                 :            :      *
     658                 :            :      *  @param block_size       This specifies the block size (in bytes) for to
     659                 :            :      *                          use for the output.  For glass, the block size
     660                 :            :      *                          must be a power of 2 between 2048 and 65536
     661                 :            :      *                          (inclusive), and the default (also used if an
     662                 :            :      *                          invalid value is passed) is 8192 bytes.
     663                 :            :      */
     664                 :        402 :     void compact(const std::string& output,
     665                 :            :                  unsigned flags = 0,
     666                 :            :                  int block_size = 0) {
     667                 :        402 :         compact_(&output, 0, flags, block_size, NULL);
     668                 :        392 :     }
     669                 :            : 
     670                 :            :     /** Produce a compact version of this database.
     671                 :            :      *
     672                 :            :      *  New 1.3.4.  Various methods of the Compactor class were deprecated in
     673                 :            :      *  1.3.4.
     674                 :            :      *
     675                 :            :      *  This variant writes a single-file database to the specified file
     676                 :            :      *  descriptor.  Only the glass backend supports such databases, so
     677                 :            :      *  this form is only supported for this backend.
     678                 :            :      *
     679                 :            :      *  @param fd       File descriptor to write the compact version to.  The
     680                 :            :      *                  descriptor needs to be readable and writable (open with
     681                 :            :      *                  O_RDWR) and seekable.  The current file offset is used,
     682                 :            :      *                  allowing compacting to a single file database embedded
     683                 :            :      *                  within another file.  Xapian takes ownership of the
     684                 :            :      *                  file descriptor and will close it before returning.
     685                 :            :      *
     686                 :            :      *  @param flags    Any of the following combined using bitwise-or (| in
     687                 :            :      *                  C++):
     688                 :            :      *   - Xapian::DBCOMPACT_NO_RENUMBER By default the document ids will
     689                 :            :      *          be renumbered the output - currently by applying the same
     690                 :            :      *          offset to all the document ids in a particular source database.
     691                 :            :      *          If this flag is specified, then this renumbering doesn't
     692                 :            :      *          happen, but all the document ids must be unique over all source
     693                 :            :      *          databases.  Currently the ranges of document ids in each source
     694                 :            :      *          must not overlap either, though this restriction may be removed
     695                 :            :      *          in the future.
     696                 :            :      *   - Xapian::DBCOMPACT_MULTIPASS
     697                 :            :      *          If merging more than 3 databases, merge the postlists in
     698                 :            :      *          multiple passes, which is generally faster but requires more
     699                 :            :      *          disk space for temporary files.
     700                 :            :      *   - Xapian::DBCOMPACT_SINGLE_FILE
     701                 :            :      *          Produce a single-file database (only supported for glass
     702                 :            :      *          currently).
     703                 :            :      *   - At most one of:
     704                 :            :      *     - Xapian::Compactor::STANDARD - Don't split items unnecessarily.
     705                 :            :      *     - Xapian::Compactor::FULL     - Split items whenever it saves space
     706                 :            :      *                                     (the default).
     707                 :            :      *     - Xapian::Compactor::FULLER   - Allow oversize items to save more
     708                 :            :      *                                     space (not recommended if you ever
     709                 :            :      *                                     plan to update the compacted
     710                 :            :      *                                     database).
     711                 :            :      *
     712                 :            :      *  @param block_size       This specifies the block size (in bytes) for to
     713                 :            :      *                          use for the output.  For glass, the block size
     714                 :            :      *                          must be a power of 2 between 2048 and 65536
     715                 :            :      *                          (inclusive), and the default (also used if an
     716                 :            :      *                          invalid value is passed) is 8192 bytes.
     717                 :            :      */
     718                 :          8 :     void compact(int fd,
     719                 :            :                  unsigned flags = 0,
     720                 :            :                  int block_size = 0) {
     721                 :          8 :         compact_(NULL, fd, flags, block_size, NULL);
     722                 :          8 :     }
     723                 :            : 
     724                 :            :     /** Produce a compact version of this database.
     725                 :            :      *
     726                 :            :      *  New 1.3.4.  Various methods of the Compactor class were deprecated
     727                 :            :      *  in 1.3.4.
     728                 :            :      *
     729                 :            :      *  The @a compactor functor allows handling progress output and
     730                 :            :      *  specifying how user metadata is merged.
     731                 :            :      *
     732                 :            :      *  @param output Path to write the compact version to.
     733                 :            :      *            This can be the same as an input if that input is a
     734                 :            :      *            stub database (in which case the database(s) listed
     735                 :            :      *            in the stub will be compacted to a new database and
     736                 :            :      *            then the stub will be atomically updated to point to
     737                 :            :      *            this new database).
     738                 :            :      *
     739                 :            :      *  @param flags    Any of the following combined using bitwise-or (| in
     740                 :            :      *                  C++):
     741                 :            :      *   - Xapian::DBCOMPACT_NO_RENUMBER By default the document ids will
     742                 :            :      *          be renumbered the output - currently by applying the same
     743                 :            :      *          offset to all the document ids in a particular source database.
     744                 :            :      *          If this flag is specified, then this renumbering doesn't
     745                 :            :      *          happen, but all the document ids must be unique over all source
     746                 :            :      *          databases.  Currently the ranges of document ids in each source
     747                 :            :      *          must not overlap either, though this restriction may be removed
     748                 :            :      *          in the future.
     749                 :            :      *   - Xapian::DBCOMPACT_MULTIPASS
     750                 :            :      *          If merging more than 3 databases, merge the postlists in
     751                 :            :      *          multiple passes, which is generally faster but requires more
     752                 :            :      *          disk space for temporary files.
     753                 :            :      *   - Xapian::DBCOMPACT_SINGLE_FILE
     754                 :            :      *          Produce a single-file database (only supported for glass
     755                 :            :      *          currently).
     756                 :            :      *   - At most one of:
     757                 :            :      *     - Xapian::Compactor::STANDARD - Don't split items unnecessarily.
     758                 :            :      *     - Xapian::Compactor::FULL     - Split items whenever it saves space
     759                 :            :      *                                     (the default).
     760                 :            :      *     - Xapian::Compactor::FULLER   - Allow oversize items to save more
     761                 :            :      *                                     space (not recommended if you ever
     762                 :            :      *                                     plan to update the compacted
     763                 :            :      *                                     database).
     764                 :            :      *
     765                 :            :      *  @param block_size       This specifies the block size (in bytes) for to
     766                 :            :      *                          use for the output.  For glass, the block size
     767                 :            :      *                          must be a power of 2 between 2048 and 65536
     768                 :            :      *                          (inclusive), and the default (also used if an
     769                 :            :      *                          invalid value is passed) is 8192 bytes.
     770                 :            :      *
     771                 :            :      *  @param compactor Functor
     772                 :            :      */
     773                 :            :     void compact(const std::string& output,
     774                 :            :                  unsigned flags,
     775                 :            :                  int block_size,
     776                 :            :                  Xapian::Compactor& compactor)
     777                 :            :     {
     778                 :            :         compact_(&output, 0, flags, block_size, &compactor);
     779                 :            :     }
     780                 :            : 
     781                 :            :     /** Produce a compact version of this database.
     782                 :            :      *
     783                 :            :      *  New 1.3.4.  Various methods of the Compactor class were deprecated in
     784                 :            :      *  1.3.4.
     785                 :            :      *
     786                 :            :      *  The @a compactor functor allows handling progress output and specifying
     787                 :            :      *  how user metadata is merged.
     788                 :            :      *
     789                 :            :      *  This variant writes a single-file database to the specified file
     790                 :            :      *  descriptor.  Only the glass backend supports such databases, so this
     791                 :            :      *  form is only supported for this backend.
     792                 :            :      *
     793                 :            :      *  @param fd       File descriptor to write the compact version to.  The
     794                 :            :      *                  descriptor needs to be readable and writable (open with
     795                 :            :      *                  O_RDWR) and seekable.  The current file offset is used,
     796                 :            :      *                  allowing compacting to a single file database embedded
     797                 :            :      *                  within another file.  Xapian takes ownership of the
     798                 :            :      *                  file descriptor and will close it before returning.
     799                 :            :      *
     800                 :            :      *  @param flags    Any of the following combined using bitwise-or (| in
     801                 :            :      *                  C++):
     802                 :            :      *   - Xapian::DBCOMPACT_NO_RENUMBER By default the document ids will
     803                 :            :      *          be renumbered the output - currently by applying the same
     804                 :            :      *          offset to all the document ids in a particular source database.
     805                 :            :      *          If this flag is specified, then this renumbering doesn't
     806                 :            :      *          happen, but all the document ids must be unique over all source
     807                 :            :      *          databases.  Currently the ranges of document ids in each source
     808                 :            :      *          must not overlap either, though this restriction may be removed
     809                 :            :      *          in the future.
     810                 :            :      *   - Xapian::DBCOMPACT_MULTIPASS
     811                 :            :      *          If merging more than 3 databases, merge the postlists in
     812                 :            :      *          multiple passes, which is generally faster but requires more
     813                 :            :      *          disk space for temporary files.
     814                 :            :      *   - Xapian::DBCOMPACT_SINGLE_FILE
     815                 :            :      *          Produce a single-file database (only supported for glass
     816                 :            :      *          currently).
     817                 :            :      *   - At most one of:
     818                 :            :      *     - Xapian::Compactor::STANDARD - Don't split items unnecessarily.
     819                 :            :      *     - Xapian::Compactor::FULL     - Split items whenever it saves space
     820                 :            :      *                                     (the default).
     821                 :            :      *     - Xapian::Compactor::FULLER   - Allow oversize items to save more
     822                 :            :      *                                     space (not recommended if you ever
     823                 :            :      *                                     plan to update the compacted
     824                 :            :      *                                     database).
     825                 :            :      *
     826                 :            :      *  @param block_size       This specifies the block size (in bytes) for to
     827                 :            :      *                          use for the output.  For glass, the block size
     828                 :            :      *                          must be a power of 2 between 2048 and 65536
     829                 :            :      *                          (inclusive), and the default (also used if an
     830                 :            :      *                          invalid value is passed) is 8192 bytes.
     831                 :            :      *
     832                 :            :      *  @param compactor Functor
     833                 :            :      */
     834                 :            :     void compact(int fd,
     835                 :            :                  unsigned flags,
     836                 :            :                  int block_size,
     837                 :            :                  Xapian::Compactor& compactor)
     838                 :            :     {
     839                 :            :         compact_(NULL, fd, flags, block_size, &compactor);
     840                 :            :     }
     841                 :            : };
     842                 :            : 
     843                 :            : /** This class provides read/write access to a database.
     844                 :            :  *
     845                 :            :  *  A WritableDatabase object contains zero or more shards, and operations are
     846                 :            :  *  performed across these shards.  Documents added by add_database() are
     847                 :            :  *  stored to the shards in a round-robin fashion.
     848                 :            :  *
     849                 :            :  *  @since 1.5.0 This class is a reference counted handle like many other
     850                 :            :  *         Xapian API classes.  In earlier versions, it worked like a typedef
     851                 :            :  *         to std::vector<database_shard>.  The key difference is that
     852                 :            :  *         previously copying or assigning a Xapian::Database made a deep copy,
     853                 :            :  *         whereas now it makes a shallow copy.
     854                 :            :  *
     855                 :            :  *  Most methods can throw:
     856                 :            :  *
     857                 :            :  *  @exception Xapian::DatabaseCorruptError if database corruption is detected
     858                 :            :  *  @exception Xapian::DatabaseError in various situation (for example, calling
     859                 :            :  *             methods after @a close() has been called)
     860                 :            :  *  @exception Xapian::NetworkError when remote databases are in use
     861                 :            :  */
     862         [ -  + ]:       5216 : class XAPIAN_VISIBILITY_DEFAULT WritableDatabase : public Database {
     863                 :            :     /** @internal @private Helper method which implements cancel_transaction()
     864                 :            :      *  and commit_transaction().
     865                 :            :      *
     866                 :            :      *  @param do_commit If true, then commit, else cancel.
     867                 :            :      */
     868                 :            :     void end_transaction_(bool do_commit);
     869                 :            : 
     870                 :            :   public:
     871                 :            :     /** Create a WritableDatabase with no subdatabases.
     872                 :            :      *
     873                 :            :      *  The created object isn't very useful in this state - it's intended
     874                 :            :      *  as a placeholder value.
     875                 :            :      */
     876                 :        464 :     WritableDatabase() : Database() {}
     877                 :            : 
     878                 :            :     /** Add shards from another WritableDatabase.
     879                 :            :      *
     880                 :            :      *  Any shards in @a other are added to the list of shards in this object.
     881                 :            :      *  The shards are reference counted and also remain in @a other.
     882                 :            :      *
     883                 :            :      *  @param other    Another WritableDatabase to add shards from
     884                 :            :      *
     885                 :            :      *  @exception Xapian::InvalidArgumentError if @a other is the same object
     886                 :            :      *             as this.
     887                 :            :      */
     888                 :        513 :     void add_database(const WritableDatabase& other) {
     889                 :            :         // This method is provided mainly so that adding a Database to a
     890                 :            :         // WritableDatabase is a compile-time error - prior to 1.5.0, it
     891                 :            :         // would essentially act as a "black-hole" shard which discarded
     892                 :            :         // any changes made to it.
     893                 :        513 :         add_database_(other, false);
     894                 :        513 :     }
     895                 :            : 
     896                 :            :     /** Test if this database is currently locked for writing.
     897                 :            :      *
     898                 :            :      *  If the underlying object is actually a WritableDatabase, always returns
     899                 :            :      *  true.
     900                 :            :      *
     901                 :            :      *  Otherwise tests if there's a writer holding the lock (or if we can't
     902                 :            :      *  test for a lock without taking it on the current platform, throw
     903                 :            :      *  Xapian::UnimplementedError).  If there's an error while trying to test
     904                 :            :      *  the lock, throws Xapian::DatabaseLockError.
     905                 :            :      *
     906                 :            :      *  For multi-databases, this tests each sub-database and returns true if
     907                 :            :      *  any of them are locked.
     908                 :            :      */
     909                 :          4 :     bool locked() const {
     910                 :            :         // If this method is called, the type is statically known to be
     911                 :            :         // WritableDatabase so we can just inline the known answer.  In most
     912                 :            :         // cases, a call into the library will be needed.
     913                 :          4 :         return true;
     914                 :            :     }
     915                 :            : 
     916                 :            :     /** Create or open a Xapian database for both reading and writing.
     917                 :            :      *
     918                 :            :      *  @param path  Filing system path for the database.  If creating a
     919                 :            :      *               new database with a backend which uses a directory of
     920                 :            :      *               files (such as glass does by default) then Xapian will
     921                 :            :      *               create a directory for @a path if necessary (but the
     922                 :            :      *               parent directory must already exist).
     923                 :            :      *
     924                 :            :      *  @param flags  A bitwise-or (| in C++) combination of:
     925                 :            :      *
     926                 :            :      *  * at most one of the following constants indicating how to handle
     927                 :            :      *    the database already existing or not (the default action is
     928                 :            :      *    Xapian::DB_CREATE_OR_OPEN):
     929                 :            :      *
     930                 :            :      *      Constant                     | DB exists | DB doesn't exist
     931                 :            :      *    ------------------------------ | --------- | ------------------
     932                 :            :      *    Xapian::DB_CREATE_OR_OPEN      | open      | create
     933                 :            :      *    Xapian::DB_CREATE              | fail      | create
     934                 :            :      *    Xapian::DB_CREATE_OR_OVERWRITE | overwrite | create
     935                 :            :      *    Xapian::DB_OPEN                | open      | fail
     936                 :            :      *
     937                 :            :      *  * at most one of the follow constants indicating which backend to
     938                 :            :      *    use when creating a new database, ignored when opening or overwriting
     939                 :            :      *    an existing database (default: currently Xapian::DB_BACKEND_GLASS):
     940                 :            :      *
     941                 :            :      *      Constant                     | Meaning
     942                 :            :      *    ------------------------------ | -----------------------
     943                 :            :      *    Xapian::DB_BACKEND_GLASS       | Create a glass database
     944                 :            :      *    Xapian::DB_BACKEND_CHERT       | Create a chert database
     945                 :            :      *    Xapian::DB_BACKEND_INMEMORY    | Create inmemory DB (ignores @a path)
     946                 :            :      *
     947                 :            :      *  * any number of the following flags:
     948                 :            :      *
     949                 :            :      *   - Xapian::DB_NO_SYNC don't call fsync() or similar
     950                 :            :      *   - Xapian::DB_FULL_SYNC try harder to ensure data is safe
     951                 :            :      *   - Xapian::DB_DANGEROUS don't be crash-safe, no concurrent readers
     952                 :            :      *   - Xapian::DB_RETRY_LOCK to wait to get a write lock
     953                 :            :      *
     954                 :            :      *  @param block_size  The block size in bytes to use when creating a
     955                 :            :      *                     new database.  This is ignored when opening an
     956                 :            :      *                     existing database, and by backends which don't
     957                 :            :      *                     have the concept of a block size.  The glass
     958                 :            :      *                     backend allows block sizes which are a power of
     959                 :            :      *                     2 between 2048 and 65536 (inclusive) and its
     960                 :            :      *                     default (also used instead of an invalid value)
     961                 :            :      *                     is 8192 bytes.
     962                 :            :      *
     963                 :            :      *  @exception Xapian::DatabaseLockError is thrown if the database's
     964                 :            :      *             write lock could not be acquired.
     965                 :            :      *  @exception Xapian::DatabaseOpeningError if the specified database
     966                 :            :      *             cannot be opened
     967                 :            :      *  @exception Xapian::DatabaseVersionError if the specified database has
     968                 :            :      *             a format too old or too new to be supported.
     969                 :            :      */
     970                 :            :     explicit WritableDatabase(const std::string& path,
     971                 :            :                               int flags = 0,
     972                 :            :                               int block_size = 0);
     973                 :            : 
     974                 :            :     /** @private @internal Create a WritableDatabase given its internals. */
     975                 :            :     XAPIAN_VISIBILITY_INTERNAL
     976                 :        174 :     explicit WritableDatabase(Database::Internal* internal_)
     977                 :        174 :         : Database(internal_) {}
     978                 :            : 
     979                 :            :     /** Copy constructor.
     980                 :            :      *
     981                 :            :      *  The internals are reference counted, so copying is cheap.
     982                 :            :      */
     983                 :         12 :     WritableDatabase(const WritableDatabase& o) : Database(o) {}
     984                 :            : 
     985                 :            :     /** Assignment operator.
     986                 :            :      *
     987                 :            :      *  The internals are reference counted, so assignment is cheap.
     988                 :            :      */
     989                 :         12 :     WritableDatabase& operator=(const WritableDatabase& o) {
     990                 :         12 :         Database::operator=(o);
     991                 :         12 :         return *this;
     992                 :            :     }
     993                 :            : 
     994                 :            :     /// Move constructor.
     995                 :          2 :     WritableDatabase(WritableDatabase&& o) : Database(std::move(o)) {}
     996                 :            : 
     997                 :            :     /// Move assignment operator.
     998                 :         91 :     WritableDatabase& operator=(WritableDatabase&& o) {
     999                 :         91 :         Database::operator=(std::move(o));
    1000                 :         91 :         return *this;
    1001                 :            :     }
    1002                 :            : 
    1003                 :            :     /** Commit pending modifications.
    1004                 :            :      *
    1005                 :            :      *  Updates to a Xapian database are more efficient when applied in bulk,
    1006                 :            :      *  so by default Xapian stores modifications in memory until a threshold
    1007                 :            :      *  is exceeded and then they are committed to disk.
    1008                 :            :      *
    1009                 :            :      *  When the database is closed (by an explicit call to close() or its
    1010                 :            :      *  destructor being called) then commit() is implicitly called unless
    1011                 :            :      *  a transaction is active.
    1012                 :            :      *
    1013                 :            :      *  You can force any such pending modifications to be committed by calling
    1014                 :            :      *  this method, but bear in mind that the batching happens for a reason
    1015                 :            :      *  and calling commit() a lot is likely to slow down indexing.
    1016                 :            :      *
    1017                 :            :      *  If the commit operation succeeds then the changes are reliably written
    1018                 :            :      *  to disk and available to readers.  If the commit operation fails, then
    1019                 :            :      *  any pending modifications are discarded.
    1020                 :            :      *
    1021                 :            :      *  It's not valid to call commit() within a transaction - see
    1022                 :            :      *  begin_transaction() for more details of how transactions work in
    1023                 :            :      *  Xapian.
    1024                 :            :      *
    1025                 :            :      *  Currently batched modifications are automatically committed every
    1026                 :            :      *  10000 documents added, deleted, or modified.  This value is rather
    1027                 :            :      *  conservative, and if you have a machine with plenty of memory,
    1028                 :            :      *  you can improve indexing throughput dramatically by setting
    1029                 :            :      *  XAPIAN_FLUSH_THRESHOLD in the environment to a larger value.
    1030                 :            :      *
    1031                 :            :      *  @since This method was new in Xapian 1.1.0 - in earlier versions it
    1032                 :            :      *         was called flush().
    1033                 :            :      */
    1034                 :            :     void commit();
    1035                 :            : 
    1036                 :            :     /** Begin a transaction.
    1037                 :            :      *
    1038                 :            :      *  A Xapian transaction is a set of consecutive modifications to be
    1039                 :            :      *  committed as an atomic unit - in any committed revision of the
    1040                 :            :      *  database either none are present or they all are.
    1041                 :            :      *
    1042                 :            :      *  A transaction is started with begin_transaction() and can either be
    1043                 :            :      *  completed by calling commit_transaction() or aborted by calling
    1044                 :            :      *  cancel_transaction().
    1045                 :            :      *
    1046                 :            :      *  Closing the database (by an explicit call to close() or by its
    1047                 :            :      *  destructor being called) when a transaction is active will implicitly
    1048                 :            :      *  call cancel_transaction() to abort the transaction and discard the
    1049                 :            :      *  changes in it.
    1050                 :            :      *
    1051                 :            :      *  By default, commit() is implicitly called by begin_transaction() and
    1052                 :            :      *  commit_transaction() so that the changes in the transaction are
    1053                 :            :      *  committed or not independent of changes before or after it.
    1054                 :            :      *
    1055                 :            :      *  The downside of these implicit calls to commit() is that small
    1056                 :            :      *  transactions can harm indexing performance in the same way that
    1057                 :            :      *  explicitly calling commit() frequently can.
    1058                 :            :      *
    1059                 :            :      *  If you're applying atomic groups of changes and only wish to ensure
    1060                 :            :      *  that each group is either applied or not applied, then you can prevent
    1061                 :            :      *  the automatic commit() before and after the transaction by starting the
    1062                 :            :      *  transaction with begin_transaction(false).  However, if
    1063                 :            :      *  cancel_transaction() is called (or if commit_transaction() isn't called
    1064                 :            :      *  before the WritableDatabase object is destroyed) then any changes which
    1065                 :            :      *  were pending before the transaction began will also be discarded.
    1066                 :            :      *
    1067                 :            :      *  @param flushed  Is this a flushed transaction?  By default transactions
    1068                 :            :      *                  are "flushed", which means that committing a
    1069                 :            :      *                  transaction will ensure those changes are permanently
    1070                 :            :      *                  written to the database.  By contrast, unflushed
    1071                 :            :      *                  transactions only ensure that changes within the
    1072                 :            :      *                  transaction are either all applied or all aren't.
    1073                 :            :      *
    1074                 :            :      *  @exception Xapian::UnimplementedError is thrown if this is an InMemory
    1075                 :            :      *             database, which don't currently support transactions.
    1076                 :            :      *  @exception Xapian::InvalidOperationError will be thrown if a transaction
    1077                 :            :      *             is already active.
    1078                 :            :      */
    1079                 :            :     void begin_transaction(bool flushed = true);
    1080                 :            : 
    1081                 :            :     /** Complete the transaction currently in progress.
    1082                 :            :      *
    1083                 :            :      *  If the transaction was begun as a flushed transaction then the changes
    1084                 :            :      *  in it have been committed to the database upon successful completion
    1085                 :            :      *  of this method.
    1086                 :            :      *
    1087                 :            :      *  If an exception is thrown, then the changes in the transaction will be
    1088                 :            :      *  discarded (if the transaction was not begun as a flushed transaction,
    1089                 :            :      *  any changes made but not committed before begin_transaction() will also
    1090                 :            :      *  be discarded).
    1091                 :            :      *
    1092                 :            :      *  In all cases the transaction will no longer be in progress.
    1093                 :            :      *
    1094                 :            :      *  @exception Xapian::UnimplementedError is thrown if this is an InMemory
    1095                 :            :      *             database, which don't currently support transactions.
    1096                 :            :      *  @exception Xapian::InvalidOperationError is thrown if no transaction
    1097                 :            :      *             was active.
    1098                 :            :      */
    1099                 :         32 :     void commit_transaction() { end_transaction_(true); }
    1100                 :            : 
    1101                 :            :     /** Abort the transaction currently in progress.
    1102                 :            :      *
    1103                 :            :      *  Changes made within the current transaction will be discarded (if the
    1104                 :            :      *  transaction was not begun as a flushed transaction, any changes made
    1105                 :            :      *  but not committed before begin_transaction() will also be discarded).
    1106                 :            :      *
    1107                 :            :      *  @exception Xapian::UnimplementedError is thrown if this is an InMemory
    1108                 :            :      *             database, which don't currently support transactions.
    1109                 :            :      *  @exception Xapian::InvalidOperationError is thrown if no transaction
    1110                 :            :      *             was active.
    1111                 :            :      */
    1112                 :         73 :     void cancel_transaction() { end_transaction_(false); }
    1113                 :            : 
    1114                 :            :     /** Add a document to the database.
    1115                 :            :      *
    1116                 :            :      *  The document is allocated document ID (get_lastdocid() + 1) - the
    1117                 :            :      *  next highest document ID which has never previously been used by
    1118                 :            :      *  this database (so docids from deleted documents won't be reused).
    1119                 :            :      *
    1120                 :            :      *  If you want to specify the document ID to be used, you should
    1121                 :            :      *  call replace_document() instead.
    1122                 :            :      *
    1123                 :            :      *  If a transaction is active, the document addition is added to the
    1124                 :            :      *  transaction; otherwise it is added to the current batch of changes.
    1125                 :            :      *  Either way, it won't be visible to readers right away (unless we're
    1126                 :            :      *  not in a transaction and the addition triggers an automatic commit).
    1127                 :            :      *
    1128                 :            :      *  @param doc  The Document object to be added.
    1129                 :            :      *
    1130                 :            :      *  @return The document ID allocated to the document.
    1131                 :            :      */
    1132                 :            :     Xapian::docid add_document(const Xapian::Document& doc);
    1133                 :            : 
    1134                 :            :     /** Delete a document from the database.
    1135                 :            :      *
    1136                 :            :      *  This method removes the document with the specified document ID
    1137                 :            :      *  from the database.
    1138                 :            :      *
    1139                 :            :      *  If a transaction is active, the document removal is added to the
    1140                 :            :      *  transaction; otherwise it is added to the current batch of changes.
    1141                 :            :      *  Either way, it won't be visible to readers right away (unless we're
    1142                 :            :      *  not in a transaction and the addition triggers an automatic commit).
    1143                 :            :      *
    1144                 :            :      *  @param did     The document ID of the document to be removed.
    1145                 :            :      */
    1146                 :            :     void delete_document(Xapian::docid did);
    1147                 :            : 
    1148                 :            :     /** Delete any documents indexed by a term from the database.
    1149                 :            :      *
    1150                 :            :      *  This method removes any documents indexed by the specified term
    1151                 :            :      *  from the database.
    1152                 :            :      *
    1153                 :            :      *  A major use is for convenience when UIDs from another system are
    1154                 :            :      *  mapped to terms in Xapian, although this method has other uses
    1155                 :            :      *  (for example, you could add a "deletion date" term to documents at
    1156                 :            :      *  index time and use this method to delete all documents due for
    1157                 :            :      *  deletion on a particular date).
    1158                 :            :      *
    1159                 :            :      *  @param unique_term     The term to remove references to.
    1160                 :            :      *
    1161                 :            :      *  @since 1.5.0 The changes made by this method are made atomically.
    1162                 :            :      *               Previously automatic commits could happen during the
    1163                 :            :      *               batch.
    1164                 :            :      */
    1165                 :            :     void delete_document(const std::string& unique_term);
    1166                 :            : 
    1167                 :            :     /** Replace a document in the database.
    1168                 :            :      *
    1169                 :            :      *  This method replaces the document with the specified document ID.
    1170                 :            :      *  If document ID @a did isn't currently used, the document will be
    1171                 :            :      *  added with document ID @a did.
    1172                 :            :      *
    1173                 :            :      *  The monotonic counter used for automatically allocating document
    1174                 :            :      *  IDs is increased so that the next automatically allocated document
    1175                 :            :      *  ID will be did + 1.  Be aware that if you use this method to
    1176                 :            :      *  specify a high document ID for a new document, and also use
    1177                 :            :      *  WritableDatabase::add_document(), Xapian may get to a state where
    1178                 :            :      *  this counter wraps around and will be unable to automatically
    1179                 :            :      *  allocate document IDs!
    1180                 :            :      *
    1181                 :            :      *  Note that changes to the database won't be immediately committed to
    1182                 :            :      *  disk; see commit() for more details.
    1183                 :            :      *
    1184                 :            :      *  @param did      The document ID of the document to be replaced.
    1185                 :            :      *  @param document The new document.
    1186                 :            :      */
    1187                 :            :     void replace_document(Xapian::docid did, const Xapian::Document& document);
    1188                 :            : 
    1189                 :            :     /** Replace any documents matching a term.
    1190                 :            :      *
    1191                 :            :      *  This method replaces any documents indexed by the specified term
    1192                 :            :      *  with the specified document.  If any documents are indexed by the
    1193                 :            :      *  term, the lowest document ID will be used for the document,
    1194                 :            :      *  otherwise a new document ID will be generated as for add_document.
    1195                 :            :      *
    1196                 :            :      *  One common use is to allow UIDs from another system to easily be
    1197                 :            :      *  mapped to terms in Xapian.  Note that this method doesn't
    1198                 :            :      *  automatically add unique_term as a term, so you'll need to call
    1199                 :            :      *  document.add_term(unique_term) first when using replace_document()
    1200                 :            :      *  in this way.
    1201                 :            :      *
    1202                 :            :      *  Note that changes to the database won't be immediately committed to
    1203                 :            :      *  disk; see commit() for more details.
    1204                 :            :      *
    1205                 :            :      *  @param unique_term      The "unique" term.
    1206                 :            :      *  @param document         The new document.
    1207                 :            :      *
    1208                 :            :      *  @return The document ID used by the new document.  If term existed
    1209                 :            :      *          in the database, this will be the first document ID that
    1210                 :            :      *          was indexed by that term; otherwise the database allocates
    1211                 :            :      *          (get_lastdocid() + 1) as it does for add_document().
    1212                 :            :      *
    1213                 :            :      *  @since 1.5.0 The changes made by this method are made atomically.
    1214                 :            :      *               Previously automatic commits could happen during the
    1215                 :            :      *               batch.
    1216                 :            :      */
    1217                 :            :     Xapian::docid replace_document(const std::string& unique_term,
    1218                 :            :                                    const Xapian::Document& document);
    1219                 :            : 
    1220                 :            :     /** Add a word to the spelling dictionary.
    1221                 :            :      *
    1222                 :            :      *  If the word is already present, its frequency is increased.
    1223                 :            :      *
    1224                 :            :      *  @param word     The word to add.
    1225                 :            :      *  @param freqinc  How much to increase its frequency by (default 1).
    1226                 :            :      */
    1227                 :            :     void add_spelling(const std::string& word,
    1228                 :            :                       Xapian::termcount freqinc = 1) const;
    1229                 :            : 
    1230                 :            :     /** Remove a word from the spelling dictionary.
    1231                 :            :      *
    1232                 :            :      *  The word's frequency is decreased, and if would become zero or less
    1233                 :            :      *  then the word is removed completely.
    1234                 :            :      *
    1235                 :            :      *  @param word     The word to remove.
    1236                 :            :      *  @param freqdec  How much to decrease its frequency by (default 1).
    1237                 :            :      *
    1238                 :            :      *  @return Any "unused" freqdec (if the word's frequency was less than
    1239                 :            :      *          freqdec then the difference is returned, else 0 is returned).
    1240                 :            :      *          Prior to 1.5.0 this method had void return type.
    1241                 :            :      */
    1242                 :            :     termcount remove_spelling(const std::string& word,
    1243                 :            :                               termcount freqdec = 1) const;
    1244                 :            : 
    1245                 :            :     /** Add a synonym for a term.
    1246                 :            :      *
    1247                 :            :      *  @param term     The term to add a synonym for.
    1248                 :            :      *  @param synonym  The synonym to add.  If this is already a synonym for
    1249                 :            :      *                  @a term, then no action is taken.
    1250                 :            :      */
    1251                 :            :     void add_synonym(const std::string& term,
    1252                 :            :                      const std::string& synonym) const;
    1253                 :            : 
    1254                 :            :     /** Remove a synonym for a term.
    1255                 :            :      *
    1256                 :            :      *  @param term     The term to remove a synonym for.
    1257                 :            :      *  @param synonym  The synonym to remove.  If this isn't currently a
    1258                 :            :      *                  synonym for @a term, then no action is taken.
    1259                 :            :      */
    1260                 :            :     void remove_synonym(const std::string& term,
    1261                 :            :                         const std::string& synonym) const;
    1262                 :            : 
    1263                 :            :     /** Remove all synonyms for a term.
    1264                 :            :      *
    1265                 :            :      *  @param term     The term to remove all synonyms for.  If the term has
    1266                 :            :      *                  no synonyms, no action is taken.
    1267                 :            :      */
    1268                 :            :     void clear_synonyms(const std::string& term) const;
    1269                 :            : 
    1270                 :            :     /** Set the user-specified metadata associated with a given key.
    1271                 :            :      *
    1272                 :            :      *  This method sets the metadata value associated with a given key.  If
    1273                 :            :      *  there is already a metadata value stored in the database with the same
    1274                 :            :      *  key, the old value is replaced.  If you want to delete an existing item
    1275                 :            :      *  of metadata, just set its value to the empty string.
    1276                 :            :      *
    1277                 :            :      *  User-specified metadata allows you to store arbitrary information in
    1278                 :            :      *  the form of (key, value) pairs.
    1279                 :            :      *
    1280                 :            :      *  There's no hard limit on the number of metadata items, or the size of
    1281                 :            :      *  the metadata values.  Metadata keys have a limited length, which depend
    1282                 :            :      *  on the backend.  We recommend limiting them to 200 bytes.  Empty keys
    1283                 :            :      *  are not valid, and specifying one will cause an exception.
    1284                 :            :      *
    1285                 :            :      *  Metadata modifications are committed to disk in the same way as
    1286                 :            :      *  modifications to the documents in the database are: i.e., modifications
    1287                 :            :      *  are atomic, and won't be committed to disk immediately (see commit()
    1288                 :            :      *  for more details).  This allows metadata to be used to link databases
    1289                 :            :      *  with versioned external resources by storing the appropriate version
    1290                 :            :      *  number in a metadata item.
    1291                 :            :      *
    1292                 :            :      *  You can also use the metadata to store arbitrary extra information
    1293                 :            :      *  associated with terms, documents, or postings by encoding the termname
    1294                 :            :      *  and/or document id into the metadata key.
    1295                 :            :      *
    1296                 :            :      *  @param key       The key of the metadata item to set.
    1297                 :            :      *
    1298                 :            :      *  @param metadata  The value of the metadata item to set.
    1299                 :            :      *
    1300                 :            :      *  @exception Xapian::DatabaseError will be thrown if a problem occurs
    1301                 :            :      *             while writing to the database.
    1302                 :            :      *
    1303                 :            :      *  @exception Xapian::DatabaseCorruptError will be thrown if the database
    1304                 :            :      *             is in a corrupt state.
    1305                 :            :      *
    1306                 :            :      *  @exception Xapian::InvalidArgumentError will be thrown if the key
    1307                 :            :      *             supplied is empty.
    1308                 :            :      *
    1309                 :            :      *  @exception Xapian::UnimplementedError will be thrown if the database
    1310                 :            :      *             backend in use doesn't support user-specified metadata.
    1311                 :            :      */
    1312                 :            :     void set_metadata(const std::string& key, const std::string& metadata);
    1313                 :            : 
    1314                 :            :     /// Return a string describing this object.
    1315                 :            :     std::string get_description() const;
    1316                 :            : };
    1317                 :            : 
    1318                 :            : }
    1319                 :            : 
    1320                 :            : #endif // XAPIAN_INCLUDED_DATABASE_H

Generated by: LCOV version 1.11