LTP GCOV extension - code coverage report
Current view: directory - usr/include/xapian - database.h
Test: lcov.info
Date: 2008-08-14 Instrumented lines: 4
Code covered: 100.0 % Executed lines: 4

       1                 : /** \file database.h
       2                 :  * \brief API for working with Xapian databases
       3                 :  */
       4                 : /* Copyright 1999,2000,2001 BrightStation PLC
       5                 :  * Copyright 2002 Ananova Ltd
       6                 :  * Copyright 2002,2003,2004,2005,2006,2007 Olly Betts
       7                 :  * Copyright 2006 Richard Boulton
       8                 :  *
       9                 :  * This program is free software; you can redistribute it and/or
      10                 :  * modify it under the terms of the GNU General Public License as
      11                 :  * published by the Free Software Foundation; either version 2 of the
      12                 :  * License, or (at your option) any later version.
      13                 :  *
      14                 :  * This program is distributed in the hope that it will be useful,
      15                 :  * but WITHOUT ANY WARRANTY; without even the implied warranty of
      16                 :  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      17                 :  * GNU General Public License for more details.
      18                 :  *
      19                 :  * You should have received a copy of the GNU General Public License
      20                 :  * along with this program; if not, write to the Free Software
      21                 :  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
      22                 :  * USA
      23                 :  */
      24                 : 
      25                 : #ifndef XAPIAN_INCLUDED_DATABASE_H
      26                 : #define XAPIAN_INCLUDED_DATABASE_H
      27                 : 
      28                 : #include <string>
      29                 : #include <vector>
      30                 : 
      31                 : #include <xapian/base.h>
      32                 : #include <xapian/types.h>
      33                 : #include <xapian/positioniterator.h>
      34                 : #include <xapian/postingiterator.h>
      35                 : #include <xapian/termiterator.h>
      36                 : #include <xapian/visibility.h>
      37                 : 
      38                 : /// The Xapian library lives in the Xapian namespace.
      39                 : namespace Xapian {
      40                 : 
      41                 : class Document;
      42                 : 
      43                 : /** This class is used to access a database, or a group of databases.
      44                 :  *
      45                 :  *  For searching, this class is used in conjunction with an Enquire object.
      46                 :  *
      47                 :  *  @exception InvalidArgumentError will be thrown if an invalid
      48                 :  *  argument is supplied, for example, an unknown database type.
      49                 :  *
      50                 :  *  @exception DatabaseOpeningError may be thrown if the database cannot
      51                 :  *  be opened (for example, a required file cannot be found).
      52                 :  *
      53                 :  *  @exception DatabaseVersionError may be thrown if the database is in an
      54                 :  *  unsupported format (for example, created by a newer version of Xapian
      55                 :  *  which uses an incompatible format).
      56                 :  */
      57                 : class XAPIAN_VISIBILITY_DEFAULT Database {
      58                 :     public:
      59                 :         class Internal;
      60                 :         /// @private @internal Reference counted internals.
      61                 :         std::vector<Xapian::Internal::RefCntPtr<Internal> > internal;
      62                 : 
      63                 :         /** Add an existing database (or group of databases) to those
      64                 :          *  accessed by this object.
      65                 :          *
      66                 :          *  @param database the database(s) to add.
      67                 :          */
      68                 :         void add_database(const Database & database);
      69                 : 
      70                 :         /** Create a Database with no databases in.
      71                 :          */
      72                 :         Database();
      73                 : 
      74                 :         /** Open a Database, automatically determining the database
      75                 :          *  backend to use.
      76                 :          *
      77                 :          * @param path directory that the database is stored in.
      78                 :          */
      79                 :         explicit Database(const std::string &path);
      80                 : 
      81                 :         /** @private @internal Create a Database from its internals.
      82                 :          */
      83                 :         explicit Database(Internal *internal);
      84                 : 
      85                 :         /** Destroy this handle on the database.
      86                 :          *
      87                 :          *  If there are no copies of this object remaining, the database(s)
      88                 :          *  will be closed.
      89                 :          */
      90                 :         virtual ~Database();
      91                 : 
      92                 :         /** Copying is allowed.  The internals are reference counted, so
      93                 :          *  copying is cheap.
      94                 :          */
      95                 :         Database(const Database &other);
      96                 : 
      97                 :         /** Assignment is allowed.  The internals are reference counted,
      98                 :          *  so assignment is cheap.
      99                 :          */
     100                 :         void operator=(const Database &other);
     101                 : 
     102                 :         /** Re-open the database.
     103                 :          *  This re-opens the database(s) to the latest available version(s).
     104                 :          *  It can be used either to make sure the latest results are
     105                 :          *  returned, or to recover from a Xapian::DatabaseModifiedError.
     106                 :          */
     107                 :         void reopen();
     108                 : 
     109                 :         /// Return a string describing this object.
     110                 :         virtual std::string get_description() const;
     111                 : 
     112                 :         /** An iterator pointing to the start of the postlist
     113                 :          *  for a given term.
     114                 :          *
     115                 :          *  If the term name is the empty string, the iterator returned
     116                 :          *  will list all the documents in the database.  Such an iterator
     117                 :          *  will always return a WDF value of 1, since there is no obvious
     118                 :          *  meaning for this quantity in this case.
     119                 :          */
     120                 :         PostingIterator postlist_begin(const std::string &tname) const;
     121                 : 
     122                 :         /** Corresponding end iterator to postlist_begin().
     123                 :          */
     124              10 :         PostingIterator postlist_end(const std::string &) const {
     125              10 :             return PostingIterator(NULL);
     126                 :         }
     127                 : 
     128                 :         /** An iterator pointing to the start of the termlist
     129                 :          *  for a given document.
     130                 :          */
     131                 :         TermIterator termlist_begin(Xapian::docid did) const;
     132                 : 
     133                 :         /** Corresponding end iterator to termlist_begin().
     134                 :          */
     135                 :         TermIterator termlist_end(Xapian::docid) const {
     136                 :             return TermIterator(NULL);
     137                 :         }
     138                 : 
     139                 :         /** Does this database have any positional information? */
     140                 :         bool has_positions() const;
     141                 : 
     142                 :         /** An iterator pointing to the start of the position list
     143                 :          *  for a given term in a given document.
     144                 :          */
     145                 :         PositionIterator positionlist_begin(Xapian::docid did, const std::string &tname) const;
     146                 : 
     147                 :         /** Corresponding end iterator to positionlist_begin().
     148                 :          */
     149                 :         PositionIterator positionlist_end(Xapian::docid, const std::string &) const {
     150                 :             return PositionIterator(NULL);
     151                 :         }
     152                 : 
     153                 :         /** An iterator which runs across all terms in the database.
     154                 :          */
     155                 :         TermIterator allterms_begin() const;
     156                 : 
     157                 :         /** Corresponding end iterator to allterms_begin().
     158                 :          */
     159                 :         TermIterator allterms_end() const {
     160                 :             return TermIterator(NULL);
     161                 :         }
     162                 : 
     163                 :         /** An iterator which runs across all terms with a given prefix.
     164                 :          *
     165                 :          *  This is functionally similar to getting an iterator with
     166                 :          *  allterms_begin() and then calling skip_to(prefix) on that iterator
     167                 :          *  to move to the start of the prefix, but is more convenient (because
     168                 :          *  it detects the end of the prefixed terms), and may be more
     169                 :          *  efficient than simply calling skip_to() after opening the iterator,
     170                 :          *  particularly for network databases.
     171                 :          *
     172                 :          *  @param prefix The prefix to restrict the returned terms to.
     173                 :          */
     174                 :         TermIterator allterms_begin(const std::string & prefix) const;
     175                 : 
     176                 :         /** Corresponding end iterator to allterms_begin(prefix).
     177                 :          */
     178               1 :         TermIterator allterms_end(const std::string &) const {
     179               1 :             return TermIterator(NULL);
     180                 :         }
     181                 : 
     182                 :         /// Get the number of documents in the database.
     183                 :         Xapian::doccount get_doccount() const;
     184                 : 
     185                 :         /// Get the highest document id which has been used in the database.
     186                 :         Xapian::docid get_lastdocid() const;
     187                 : 
     188                 :         /// Get the average length of the documents in the database.
     189                 :         Xapian::doclength get_avlength() const;
     190                 : 
     191                 :         /// Get the number of documents in the database indexed by a given term.
     192                 :         Xapian::doccount get_termfreq(const std::string & tname) const;
     193                 : 
     194                 :         /** Check if a given term exists in the database.
     195                 :          *
     196                 :          *  Return true if and only if the term exists in the database.
     197                 :          *  This is the same as (get_termfreq(tname) != 0), but will often be
     198                 :          *  more efficient.
     199                 :          */
     200                 :         bool term_exists(const std::string & tname) const;
     201                 : 
     202                 :         /** Return the total number of occurrences of the given term.
     203                 :          *
     204                 :          *  This is the sum of the number of occurrences of the term in each
     205                 :          *  document it indexes: i.e., the sum of the within document
     206                 :          *  frequencies of the term.
     207                 :          *
     208                 :          *  @param tname  The term whose collection frequency is being
     209                 :          *  requested.
     210                 :          */
     211                 :         Xapian::termcount get_collection_freq(const std::string & tname) const;
     212                 : 
     213                 :         /** Get the length of a document.
     214                 :          */
     215                 :         Xapian::doclength get_doclength(Xapian::docid did) const;
     216                 : 
     217                 :         /** Send a "keep-alive" to remote databases to stop them timing
     218                 :          *  out.
     219                 :          */
     220                 :         void keep_alive();
     221                 : 
     222                 :         /** Get a document from the database, given its document id.
     223                 :          *
     224                 :          *  This method returns a Xapian::Document object which provides the
     225                 :          *  information about a document.
     226                 :          *
     227                 :          *  @param did   The document id for which to retrieve the data.
     228                 :          *
     229                 :          *  @return      A Xapian::Document object containing the document data
     230                 :          *
     231                 :          *  @exception Xapian::DocNotFoundError      The document specified
     232                 :          *              could not be found in the database.
     233                 :          */
     234                 :         Xapian::Document get_document(Xapian::docid did) const;
     235                 : 
     236                 :         /** Suggest a spelling correction.
     237                 :          *
     238                 :          *  @param word                 The potentially misspelled word.
     239                 :          *  @param max_edit_distance    Only consider words which are at most
     240                 :          *      @a max_edit_distance edits from @a word.  An edit is a
     241                 :          *      character insertion, deletion, or the transposition of two
     242                 :          *      adjacent characters (default is 2).
     243                 :          */
     244                 :         std::string get_spelling_suggestion(const std::string &word,
     245                 :                                             unsigned max_edit_distance = 2) const;
     246                 : 
     247                 :         /** An iterator which returns all the spelling correction targets.
     248                 :          *
     249                 :          *  This returns all the words which are considered as targets for the
     250                 :          *  spelling correction algorithm.  The frequency of each word is
     251                 :          *  available as the term frequency of each entry in the returned
     252                 :          *  iterator.
     253                 :          */
     254                 :         Xapian::TermIterator spellings_begin() const;
     255                 : 
     256                 :         /// Corresponding end iterator to spellings_begin().
     257                 :         Xapian::TermIterator spellings_end() const {
     258                 :             return Xapian::TermIterator(NULL);
     259                 :         }
     260                 : 
     261                 :         /** An iterator which returns all the synonyms for a given term.
     262                 :          *
     263                 :          *  @param term     The term to return synonyms for.
     264                 :          */
     265                 :         Xapian::TermIterator synonyms_begin(const std::string &term) const;
     266                 : 
     267                 :         /// Corresponding end iterator to synonyms_begin(term).
     268                 :         Xapian::TermIterator synonyms_end(const std::string &) const {
     269                 :             return Xapian::TermIterator(NULL);
     270                 :         }
     271                 : 
     272                 :         /** An iterator which returns all terms which have synonyms.
     273                 :          *
     274                 :          *  @param prefix   If non-empty, only terms with this prefix are
     275                 :          *                  returned.
     276                 :          */
     277                 :         Xapian::TermIterator synonym_keys_begin(const std::string &prefix = "") const;
     278                 : 
     279                 :         /// Corresponding end iterator to synonym_keys_begin(prefix).
     280                 :         Xapian::TermIterator synonym_keys_end(const std::string & = "") const {
     281                 :             return Xapian::TermIterator(NULL);
     282                 :         }
     283                 : 
     284                 :         /** Get the user-specified metadata associated with a given key.
     285                 :          *
     286                 :          *  User-specified metadata allows you to store arbitrary information
     287                 :          *  in the form of (key,tag) pairs.  See @a
     288                 :          *  WritableDatabase::set_metadata() for more information.
     289                 :          *
     290                 :          *  When invoked on a Xapian::Database object representing multiple
     291                 :          *  databases, currently only the metadata for the first is considered
     292                 :          *  but this behaviour may change in the future.
     293                 :          *
     294                 :          *  If there is no piece of metadata associated with the specified
     295                 :          *  key, an empty string is returned (this applies even for backends
     296                 :          *  which don't support metadata).
     297                 :          *
     298                 :          *  Empty keys are not valid, and specifying one will cause an
     299                 :          *  exception.
     300                 :          *
     301                 :          *  @param key The key of the metadata item to access.
     302                 :          *
     303                 :          *  @return    The retrieved metadata item's value.
     304                 :          *
     305                 :          *  @exception Xapian::InvalidArgumentError will be thrown if the
     306                 :          *             key supplied is empty.
     307                 :          *
     308                 :          *  @exception Xapian::UnimplementedError will be thrown if the
     309                 :          *             database backend in use doesn't support user-specified
     310                 :          *             metadata.
     311                 :          */
     312                 :         std::string get_metadata(const std::string & key) const;
     313                 : };
     314                 : 
     315                 : /** This class provides read/write access to a database.
     316                 :  */
     317                 : class XAPIAN_VISIBILITY_DEFAULT WritableDatabase : public Database {
     318                 :     public:
     319                 :         /** Destroy this handle on the database.
     320                 :          *
     321                 :          *  If there are no copies of this object remaining, the database
     322                 :          *  will be closed.  If there are any transactions in progress
     323                 :          *  these will be aborted as if cancel_transaction had been called.
     324                 :          */
     325                 :         virtual ~WritableDatabase();
     326                 : 
     327                 :         /** Create an empty WritableDatabase.
     328                 :          */
     329                 :         WritableDatabase();
     330                 : 
     331                 :         /** Open a database for update, automatically determining the database
     332                 :          *  backend to use.
     333                 :          *
     334                 :          *  If the database is to be created, Xapian will try
     335                 :          *  to create the directory indicated by path if it doesn't already
     336                 :          *  exist (but only the leaf directory, not recursively).
     337                 :          *
     338                 :          * @param path directory that the database is stored in.
     339                 :          * @param action one of:
     340                 :          *  - Xapian::DB_CREATE_OR_OPEN open for read/write; create if no db
     341                 :          *    exists
     342                 :          *  - Xapian::DB_CREATE create new database; fail if db exists
     343                 :          *  - Xapian::DB_CREATE_OR_OVERWRITE overwrite existing db; create if
     344                 :          *    none exists
     345                 :          *  - Xapian::DB_OPEN open for read/write; fail if no db exists
     346                 :          */
     347                 :         WritableDatabase(const std::string &path, int action);
     348                 : 
     349                 :         /** @private @internal Create an WritableDatabase given its internals.
     350                 :          */
     351                 :         explicit WritableDatabase(Database::Internal *internal);
     352                 : 
     353                 :         /** Copying is allowed.  The internals are reference counted, so
     354                 :          *  copying is cheap.
     355                 :          */
     356                 :         WritableDatabase(const WritableDatabase &other);
     357                 : 
     358                 :         /** Assignment is allowed.  The internals are reference counted,
     359                 :          *  so assignment is cheap.
     360                 :          *
     361                 :          *  Note that only an WritableDatabase may be assigned to an
     362                 :          *  WritableDatabase: an attempt to assign a Database is caught
     363                 :          *  at compile-time.
     364                 :          */
     365                 :         void operator=(const WritableDatabase &other);
     366                 : 
     367                 :         /** Flush to disk any modifications made to the database.
     368                 :          *
     369                 :          *  For efficiency reasons, when performing multiple updates to a
     370                 :          *  database it is best (indeed, almost essential) to make as many
     371                 :          *  modifications as memory will permit in a single pass through
     372                 :          *  the database.  To ensure this, Xapian batches up modifications.
     373                 :          *
     374                 :          *  Flush may be called at any time to
     375                 :          *  ensure that the modifications which have been made are written to
     376                 :          *  disk: if the flush succeeds, all the preceding modifications will
     377                 :          *  have been written to disk.
     378                 :          *
     379                 :          *  If any of the modifications fail, an exception will be thrown and
     380                 :          *  the database will be left in a state in which each separate
     381                 :          *  addition, replacement or deletion operation has either been fully
     382                 :          *  performed or not performed at all: it is then up to the
     383                 :          *  application to work out which operations need to be repeated.
     384                 :          *
     385                 :          *  It's not valid to call flush within a transaction.
     386                 :          *
     387                 :          *  Beware of calling flush too frequently: this will have a severe
     388                 :          *  performance cost.
     389                 :          *
     390                 :          *  Note that flush need not be called explicitly: it will be called
     391                 :          *  automatically when the database is closed, or when a sufficient
     392                 :          *  number of modifications have been made.
     393                 :          *
     394                 :          *  @exception Xapian::DatabaseError will be thrown if a problem occurs
     395                 :          *             while modifying the database.
     396                 :          *
     397                 :          *  @exception Xapian::DatabaseCorruptError will be thrown if the
     398                 :          *             database is in a corrupt state.
     399                 :          *
     400                 :          *  @exception Xapian::DatabaseLockError will be thrown if a lock
     401                 :          *             couldn't be acquired on the database.
     402                 :          */
     403                 :         void flush();
     404                 : 
     405                 :         /** Begin a transaction.
     406                 :          *
     407                 :          *  In Xapian a transaction is a group of modifications to the database
     408                 :          *  which are linked such that either all will be applied
     409                 :          *  simultaneously or none will be applied at all.  Even in the case of
     410                 :          *  a power failure, this characteristic should be preserved (as long
     411                 :          *  as the filesystem isn't corrupted, etc).
     412                 :          *
     413                 :          *  A transaction is started with begin_transaction() and can
     414                 :          *  either be committed by calling commit_transaction() or aborted
     415                 :          *  by calling cancel_transaction().
     416                 :          *
     417                 :          *  By default, a transaction implicitly calls flush before and after
     418                 :          *  so that the modifications stand and fall without affecting
     419                 :          *  modifications before or after.
     420                 :          *
     421                 :          *  The downside of this flushing is that small transactions cause
     422                 :          *  modifications to be frequently flushed which can harm indexing
     423                 :          *  performance in the same way that explicitly calling flush
     424                 :          *  frequently can.
     425                 :          *
     426                 :          *  If you're applying atomic groups of changes and only wish to
     427                 :          *  ensure that each group is either applied or not applied, then
     428                 :          *  you can prevent the automatic flush before and after the
     429                 :          *  transaction by starting the transaction with
     430                 :          *  begin_transaction(false).  However, if cancel_transaction is
     431                 :          *  called (or if commit_transaction isn't called before the
     432                 :          *  WritableDatabase object is destroyed) then any changes which
     433                 :          *  were pending before the transaction began will also be discarded.
     434                 :          *
     435                 :          *  Transactions aren't currently supported by the InMemory backend.
     436                 :          *
     437                 :          *  @exception Xapian::UnimplementedError will be thrown if transactions
     438                 :          *             are not available for this database type.
     439                 :          *
     440                 :          *  @exception Xapian::InvalidOperationError will be thrown if this is
     441                 :          *             called at an invalid time, such as when a transaction
     442                 :          *             is already in progress.
     443                 :          */
     444                 :         void begin_transaction(bool flushed=true);
     445                 : 
     446                 :         /** Complete the transaction currently in progress.
     447                 :          *
     448                 :          *  If this method completes successfully and this is a flushed
     449                 :          *  transaction, all the database modifications
     450                 :          *  made during the transaction will have been committed to the
     451                 :          *  database.
     452                 :          *
     453                 :          *  If an error occurs, an exception will be thrown, and none of
     454                 :          *  the modifications made to the database during the transaction
     455                 :          *  will have been applied to the database.
     456                 :          *
     457                 :          *  In all cases the transaction will no longer be in progress.
     458                 :          *
     459                 :          *  @exception Xapian::DatabaseError will be thrown if a problem occurs
     460                 :          *             while modifying the database.
     461                 :          *
     462                 :          *  @exception Xapian::DatabaseCorruptError will be thrown if the
     463                 :          *             database is in a corrupt state.
     464                 :          *
     465                 :          *  @exception Xapian::InvalidOperationError will be thrown if a
     466                 :          *             transaction is not currently in progress.
     467                 :          *
     468                 :          *  @exception Xapian::UnimplementedError will be thrown if transactions
     469                 :          *             are not available for this database type.
     470                 :          */
     471                 :         void commit_transaction();
     472                 : 
     473                 :         /** Abort the transaction currently in progress, discarding the
     474                 :          *  potential modifications made to the database.
     475                 :          *
     476                 :          *  If an error occurs in this method, an exception will be thrown,
     477                 :          *  but the transaction will be cancelled anyway.
     478                 :          *
     479                 :          *  @exception Xapian::DatabaseError will be thrown if a problem occurs
     480                 :          *             while modifying the database.
     481                 :          *
     482                 :          *  @exception Xapian::DatabaseCorruptError will be thrown if the
     483                 :          *             database is in a corrupt state.
     484                 :          *
     485                 :          *  @exception Xapian::InvalidOperationError will be thrown if a
     486                 :          *             transaction is not currently in progress.
     487                 :          *
     488                 :          *  @exception Xapian::UnimplementedError will be thrown if transactions
     489                 :          *             are not available for this database type.
     490                 :          */
     491                 :         void cancel_transaction();
     492                 : 
     493                 :         /** Add a new document to the database.
     494                 :          *
     495                 :          *  This method adds the specified document to the database,
     496                 :          *  returning a newly allocated document ID.  Automatically allocated
     497                 :          *  document IDs come from a per-database monotonically increasing
     498                 :          *  counter, so IDs from deleted documents won't be reused.
     499                 :          *
     500                 :          *  If you want to specify the document ID to be used, you should
     501                 :          *  call replace_document() instead.
     502                 :          *
     503                 :          *  Note that changes to the database won't be immediately committed to
     504                 :          *  disk; see flush() for more details.
     505                 :          *
     506                 :          *  As with all database modification operations, the effect is
     507                 :          *  atomic: the document will either be fully added, or the document
     508                 :          *  fails to be added and an exception is thrown (possibly at a
     509                 :          *  later time when flush is called or the database is closed).
     510                 :          *
     511                 :          *  @param document The new document to be added.
     512                 :          *
     513                 :          *  @return         The document ID of the newly added document.
     514                 :          *
     515                 :          *  @exception Xapian::DatabaseError will be thrown if a problem occurs
     516                 :          *             while writing to the database.
     517                 :          *
     518                 :          *  @exception Xapian::DatabaseCorruptError will be thrown if the
     519                 :          *             database is in a corrupt state.
     520                 :          */
     521                 :         Xapian::docid add_document(const Xapian::Document & document);
     522                 : 
     523                 :         /** Delete a document from the database.
     524                 :          *
     525                 :          *  This method removes the document with the specified document ID
     526                 :          *  from the database.
     527                 :          *
     528                 :          *  Note that changes to the database won't be immediately committed to
     529                 :          *  disk; see flush() for more details.
     530                 :          *
     531                 :          *  As with all database modification operations, the effect is
     532                 :          *  atomic: the document will either be fully removed, or the document
     533                 :          *  fails to be removed and an exception is thrown (possibly at a
     534                 :          *  later time when flush is called or the database is closed).
     535                 :          *
     536                 :          *  @param did     The document ID of the document to be removed.
     537                 :          *
     538                 :          *  @exception Xapian::DatabaseError will be thrown if a problem occurs
     539                 :          *             while writing to the database.
     540                 :          *
     541                 :          *  @exception Xapian::DatabaseCorruptError will be thrown if the
     542                 :          *             database is in a corrupt state.
     543                 :          */
     544                 :         void delete_document(Xapian::docid did);
     545                 : 
     546                 :         /** Delete any documents indexed by a term from the database.
     547                 :          *
     548                 :          *  This method removes any documents indexed by the specified term
     549                 :          *  from the database.
     550                 :          *
     551                 :          *  A major use is for convenience when UIDs from another system are
     552                 :          *  mapped to terms in Xapian, although this method has other uses
     553                 :          *  (for example, you could add a "deletion date" term to documents at
     554                 :          *  index time and use this method to delete all documents due for
     555                 :          *  deletion on a particular date).
     556                 :          *
     557                 :          *  @param unique_term     The term to remove references to.
     558                 :          *
     559                 :          *  @exception Xapian::DatabaseError will be thrown if a problem occurs
     560                 :          *             while writing to the database.
     561                 :          *
     562                 :          *  @exception Xapian::DatabaseCorruptError will be thrown if the
     563                 :          *             database is in a corrupt state.
     564                 :          */
     565                 :         void delete_document(const std::string & unique_term);
     566                 : 
     567                 :         /** Replace a given document in the database.
     568                 :          *
     569                 :          *  This method replaces the document with the specified document ID.
     570                 :          *  If document ID @a did isn't currently used, the document will be
     571                 :          *  added with document ID @a did.
     572                 :          *
     573                 :          *  The monotonic counter used for automatically allocating document
     574                 :          *  IDs is increased so that the next automatically allocated document
     575                 :          *  ID will be did + 1.  Be aware that if you use this method to
     576                 :          *  specify a high document ID for a new document, and also use
     577                 :          *  WritableDatabase::add_document(), Xapian may get to a state where
     578                 :          *  this counter wraps around and will be unable to automatically
     579                 :          *  allocate document IDs!
     580                 :          *
     581                 :          *  Note that changes to the database won't be immediately committed to
     582                 :          *  disk; see flush() for more details.
     583                 :          *
     584                 :          *  As with all database modification operations, the effect is
     585                 :          *  atomic: the document will either be fully replaced, or the document
     586                 :          *  fails to be replaced and an exception is thrown (possibly at a
     587                 :          *  later time when flush is called or the database is closed).
     588                 :          *
     589                 :          *  @param did     The document ID of the document to be replaced.
     590                 :          *  @param document The new document.
     591                 :          *
     592                 :          *  @exception Xapian::DatabaseError will be thrown if a problem occurs
     593                 :          *             while writing to the database.
     594                 :          *
     595                 :          *  @exception Xapian::DatabaseCorruptError will be thrown if the
     596                 :          *             database is in a corrupt state.
     597                 :          */
     598                 :         void replace_document(Xapian::docid did,
     599                 :                               const Xapian::Document & document);
     600                 : 
     601                 :         /** Replace any documents matching a term.
     602                 :          *
     603                 :          *  This method replaces any documents indexed by the specified term
     604                 :          *  with the specified document.  If any documents are indexed by the
     605                 :          *  term, the lowest document ID will be used for the document,
     606                 :          *  otherwise a new document ID will be generated as for add_document.
     607                 :          *
     608                 :          *  The intended use is to allow UIDs from another system to easily
     609                 :          *  be mapped to terms in Xapian, although this method probably has
     610                 :          *  other uses.
     611                 :          *
     612                 :          *  Note that changes to the database won't be immediately committed to
     613                 :          *  disk; see flush() for more details.
     614                 :          *
     615                 :          *  As with all database modification operations, the effect is
     616                 :          *  atomic: the document(s) will either be fully replaced, or the
     617                 :          *  document(s) fail to be replaced and an exception is thrown
     618                 :          *  (possibly at a
     619                 :          *  later time when flush is called or the database is closed).
     620                 :          *
     621                 :          *  @param unique_term    The "unique" term.
     622                 :          *  @param document The new document.
     623                 :          *
     624                 :          *  @return         The document ID that document was given.
     625                 :          *
     626                 :          *  @exception Xapian::DatabaseError will be thrown if a problem occurs
     627                 :          *             while writing to the database.
     628                 :          *
     629                 :          *  @exception Xapian::DatabaseCorruptError will be thrown if the
     630                 :          *             database is in a corrupt state.
     631                 :          */
     632                 :         Xapian::docid replace_document(const std::string & unique_term,
     633                 :                                        const Xapian::Document & document);
     634                 : 
     635                 :         /** Add a word to the spelling dictionary.
     636                 :          *
     637                 :          *  If the word is already present, its frequency is increased.
     638                 :          *
     639                 :          *  @param word     The word to add.
     640                 :          *  @param freqinc  How much to increase its frequency by (default 1).
     641                 :          */
     642                 :         void add_spelling(const std::string & word,
     643                 :                           Xapian::termcount freqinc = 1) const;
     644                 : 
     645                 :         /** Remove a word from the spelling dictionary.
     646                 :          *
     647                 :          *  The word's frequency is decreased, and if would become zero or less
     648                 :          *  then the word is removed completely.
     649                 :          *
     650                 :          *  @param word     The word to remove.
     651                 :          *  @param freqdec  How much to decrease its frequency by (default 1).
     652                 :          */
     653                 :         void remove_spelling(const std::string & word,
     654                 :                              Xapian::termcount freqdec = 1) const;
     655                 : 
     656                 :         /** Add a synonym for a term.
     657                 :          *
     658                 :          *  If @a synonym is already a synonym for @a term, then no action is
     659                 :          *  taken.
     660                 :          */
     661                 :         void add_synonym(const std::string & term,
     662                 :                          const std::string & synonym) const;
     663                 : 
     664                 :         /** Remove a synonym for a term.
     665                 :          *
     666                 :          *  If @a synonym isn't a synonym for @a term, then no action is taken.
     667                 :          */
     668                 :         void remove_synonym(const std::string & term,
     669                 :                             const std::string & synonym) const;
     670                 : 
     671                 :         /** Remove all synonyms for a term.
     672                 :          *
     673                 :          *  If @a term has no synonyms, no action is taken.
     674                 :          */
     675                 :         void clear_synonyms(const std::string & term) const;
     676                 : 
     677                 :         /** Set the user-specified metadata associated with a given key.
     678                 :          *
     679                 :          *  This method sets the metadata value associated with a given key.
     680                 :          *  If there is already a metadata value stored in the database with
     681                 :          *  the same key, the old value is replaced.  If you want to delete an
     682                 :          *  existing item of metadata, just set its value to the empty string.
     683                 :          *
     684                 :          *  User-specified metadata allows you to store arbitrary information
     685                 :          *  in the form of (key,tag) pairs.
     686                 :          *
     687                 :          *  There's no hard limit on the number of metadata items, or the size
     688                 :          *  of the metadata values.  Metadata keys have a limited length, which
     689                 :          *  depends on the backend.  We recommend limiting them to 200 bytes.
     690                 :          *  Empty keys are not valid, and specifying one will cause an
     691                 :          *  exception.
     692                 :          *
     693                 :          *  Metadata modifications are committed to disk in the same way as
     694                 :          *  modifications to the documents in the database are: i.e.,
     695                 :          *  modifications are atomic, and won't be committed to disk
     696                 :          *  immediately (see flush() for more details).  This allows metadata
     697                 :          *  to be used to link databases with versioned external resources
     698                 :          *  by storing the appropriate version number in a metadata item.
     699                 :          *
     700                 :          *  You can also use the metadata to store arbitrary extra information
     701                 :          *  associated with terms, documents, or postings by encoding the
     702                 :          *  termname and/or document id into the metadata key.
     703                 :          *
     704                 :          *  @param key   The key of the metadata item to set.
     705                 :          *
     706                 :          *  @param value The value of the metadata item to set.
     707                 :          *
     708                 :          *  @exception Xapian::DatabaseError will be thrown if a problem occurs
     709                 :          *             while writing to the database.
     710                 :          *
     711                 :          *  @exception Xapian::DatabaseCorruptError will be thrown if the
     712                 :          *             database is in a corrupt state.
     713                 :          *
     714                 :          *  @exception Xapian::InvalidArgumentError will be thrown if the
     715                 :          *             key supplied is empty.
     716                 :          */
     717                 :         void set_metadata(const std::string & key, const std::string & value);
     718                 : 
     719                 :         /// Return a string describing this object.
     720                 :         std::string get_description() const;
     721                 : };
     722                 : 
     723                 : /** Open for read/write; create if no db exists. */
     724                 : const int DB_CREATE_OR_OPEN = 1;
     725                 : /** Create a new database; fail if db exists. */
     726                 : const int DB_CREATE = 2;
     727                 : /** Overwrite existing db; create if none exists. */
     728                 : const int DB_CREATE_OR_OVERWRITE = 3;
     729                 : /** Open for read/write; fail if no db exists. */
     730                 : const int DB_OPEN = 4;
     731                 : // Can't see any sensible use for this one
     732                 : // const int DB_OVERWRITE = XXX;
     733                 : 
     734                 : }
     735                 : 
     736                 : #endif /* XAPIAN_INCLUDED_DATABASE_H */

Generated by: LTP GCOV extension version 1.6