LCOV - lcov.info - /usr/include/xapian/database.h

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