Xapian: API Documentation: xapian-core: Xapian Namespace Reference

# Xapian Namespace Reference

The Xapian namespace contains public interfaces for the Xapian library. More...

## Namespaces
namespace | Auto
| Database factory functions which determine the database type automatically.

namespace | Brass
| Database factory functions for the brass backend.

namespace | Chert
| Database factory functions for the chert backend.

namespace | Flint
| Database factory functions for the flint backend.

namespace | InMemory
| Database factory functions for the inmemory backend.

namespace | Remote
| Database factory functions for the remote backend.

namespace | Unicode
| Functions associated with handling Unicode characters.

## Classes
class | Error
| All exceptions thrown by Xapian are subclasses of Xapian::Error. More...
class | LogicError
| The base class for exceptions indicating errors in the program logic. More...
class | RuntimeError
| The base class for exceptions indicating errors only detectable at runtime. More...
class | AssertionError
| AssertionError is thrown if a logical assertion inside Xapian fails. More...
class | InvalidArgumentError
| InvalidArgumentError indicates an invalid parameter value was passed to the API. More...
class | InvalidOperationError
| InvalidOperationError indicates the API was used in an invalid way. More...
class | UnimplementedError
| UnimplementedError indicates an attempt to use an unimplemented feature. More...
class | DatabaseError
| DatabaseError indicates some sort of database related error. More...
class | DatabaseCorruptError
| DatabaseCorruptError indicates database corruption was detected. More...
class | DatabaseCreateError
| DatabaseCreateError indicates a failure to create a database. More...
class | DatabaseLockError
| DatabaseLockError indicates failure to lock a database. More...
class | DatabaseModifiedError
| DatabaseModifiedError indicates a database was modified. More...
class | DatabaseOpeningError
| DatabaseOpeningError indicates failure to open a database. More...
class | DatabaseVersionError
| DatabaseVersionError indicates that a database is in an unsupported format. More...
class | DocNotFoundError
| Indicates an attempt to access a document not present in the database. More...
class | FeatureUnavailableError
| Indicates an attempt to use a feature which is unavailable. More...
class | InternalError
| InternalError indicates a runtime problem of some sort. More...
class | NetworkError
| Indicates a problem communicating with a remote database. More...
class | NetworkTimeoutError
| Indicates a timeout expired while communicating with a remote database. More...
class | QueryParserError
| Indicates a query string can't be parsed. More...
class | SerialisationError
| Indicates an error in the std::string serialisation of an object. More...
class | RangeError
| RangeError indicates an attempt to access outside the bounds of a container. More...
class | Compactor
| Compact a database, or merge and compact several. More...
class | Database
| This class is used to access a database, or a group of databases. More...
class | WritableDatabase
| This class provides read/write access to a database. More...
class | Document
| A handle representing a document in a Xapian database. More...
class | MSet
| A match set (MSet). More...
class | MSetIterator
| An iterator pointing to items in an MSet. More...
class | ESet
| Class representing an ordered set of expand terms (an ESet). More...
class | ESetIterator
| Iterate through terms in the ESet. More...
class | RSet
| A relevance set (R-Set). More...
class | MatchDecider
| Base class for matcher decision functor. More...
class | Enquire
| This class provides an interface to the information retrieval system for the purpose of searching. More...
class | ErrorHandler
| Decide if a Xapian::Error exception should be ignored. More...
class | ExpandDecider
| Virtual base class for expand decider functor. More...
class | ExpandDeciderAnd
| ExpandDecider subclass which rejects terms using two ExpandDeciders. More...
class | ExpandDeciderFilterTerms
| ExpandDecider subclass which rejects terms in a specified list. More...
class | KeyMaker
| Virtual base class for key making functors. More...
class | MultiValueKeyMaker
| KeyMaker subclass which combines several values. More...
class | Sorter
| Virtual base class for sorter functor. More...
class | MultiValueSorter
| Sorter subclass which sorts by a several values. More...
class | MatchSpy
| Abstract base class for match spies. More...
class | ValueCountMatchSpy
| Class for counting the frequencies of values in the matching documents. More...
class | PositionIterator
| An iterator pointing to items in a list of positions. More...
class | PostingIterator
| An iterator pointing to items in a list of postings. More...
class | PostingSource
| Base class which provides an "external" source of postings. More...
class | ValuePostingSource
| A posting source which generates weights from a value slot. More...
class | ValueWeightPostingSource
| A posting source which reads weights from a value slot. More...
class | DecreasingValueWeightPostingSource
| Read weights from a value which is known to decrease as docid increases. More...
class | ValueMapPostingSource
| A posting source which looks up weights in a map using values as the key. More...
class | FixedWeightPostingSource
| A posting source which returns a fixed weight for all documents. More...
class | Query
| Class representing a query. More...
class | Stopper
| Base class for stop-word decision functor. More...
class | SimpleStopper
| Simple implementation of Stopper class - this will suit most users. More...
struct | ValueRangeProcessor
| Base class for value range processors. More...
class | StringValueRangeProcessor
| Handle a string range. More...
class | DateValueRangeProcessor
| Handle a date range. More...
class | NumberValueRangeProcessor
| Handle a number range. More...
class | QueryParser
| Build a Xapian::Query object from a user query string. More...
class | Registry
| Registry for user subclasses. More...
struct | StemImplementation
| Class representing a stemming algorithm implementation. More...
class | Stem
| Class representing a stemming algorithm. More...
class | TermGenerator
| Parses a piece of text and generate terms. More...
class | TermIterator
| An iterator pointing to items in a list of terms. More...
class | Utf8Iterator
| An iterator which returns Unicode character values from a UTF-8 encoded string. More...
class | ValueIterator
| Class for iterating over document values. More...
class | ValueSetMatchDecider
| MatchDecider filtering results based on whether document values are in a user-defined set. More...
class | Weight
| Abstract base class for weighting schemes. More...
class | BoolWeight
| Class implementing a "boolean" weighting scheme. More...
class | BM25Weight
| Xapian::Weight subclass implementing the BM25 probabilistic formula. More...
class | TradWeight
| Xapian::Weight subclass implementing the traditional probabilistic formula. More...
## Typedefs
typedef unsigned | doccount
| A count of documents.
typedef int | doccount_diff
| A signed difference between two counts of documents.
typedef unsigned | docid
| A unique identifier for a document.
typedef double | doclength
| A normalised document length.
typedef int | percent
| The percentage score for a document in an MSet.
typedef unsigned | termcount
| A counts of terms.
typedef int | termcount_diff
| A signed difference between two counts of terms.
typedef unsigned | termpos
| A term position within a document or query.
typedef int | termpos_diff
| A signed difference between two term positions.
typedef unsigned | timeout
| A timeout value in milliseconds.
typedef unsigned | valueno
| The number for a value slot in a document.
typedef int | valueno_diff
| A signed difference between two value slot numbers.
typedef double | weight
| The weight of a document or term.
## Functions
bool | operator== (const MSetIterator &a, const MSetIterator &b)
| Equality test for MSetIterator objects.
bool | operator!= (const MSetIterator &a, const MSetIterator &b)
| Inequality test for MSetIterator objects.
bool | operator== (const ESetIterator &a, const ESetIterator &b)
| Equality test for ESetIterator objects.
bool | operator!= (const ESetIterator &a, const ESetIterator &b)
| Inequality test for ESetIterator objects.
bool | operator== (const PositionIterator &a, const PositionIterator &b)
| Test equality of two PositionIterators.
bool | operator!= (const PositionIterator &a, const PositionIterator &b)
| Test inequality of two PositionIterators.
bool | operator== (const PostingIterator &a, const PostingIterator &b)
| Test equality of two PostingIterators.
bool | operator!= (const PostingIterator &a, const PostingIterator &b)
| Test inequality of two PostingIterators.
std::string | sortable_serialise (double value)
| Convert a floating point number to a string, preserving sort order.
double | sortable_unserialise (const std::string &value)
| Convert a string encoded using sortable_serialise back to a floating point number.
bool | operator== (const TermIterator &a, const TermIterator &b)
| Equality test for TermIterator objects.
bool | operator!= (const TermIterator &a, const TermIterator &b)
| Inequality test for TermIterator objects.
bool | operator== (const ValueIterator &a, const ValueIterator &b)
| Equality test for ValueIterator objects.
bool | operator!= (const ValueIterator &a, const ValueIterator &b)
| Inequality test for ValueIterator objects.
const char * | version_string ()
| Report the version string of the library which the program is linked with.
int | major_version ()
| Report the major version of the library which the program is linked with.
int | minor_version ()
| Report the minor version of the library which the program is linked with.
int | revision ()
| Report the revision of the library which the program is linked with.
## Variables
const int | DB_CREATE_OR_OPEN = 1
| Open for read/write; create if no db exists.
const int | DB_CREATE = 2
| Create a new database; fail if db exists.
const int | DB_CREATE_OR_OVERWRITE = 3
| Overwrite existing db; create if none exists.
const int | DB_OPEN = 4
| Open for read/write; fail if no db exists.
const valueno | BAD_VALUENO = static_cast<valueno>(-1)
| Reserved value to indicate "no valueno".

## Detailed Description

The Xapian namespace contains public interfaces for the Xapian library.

## Typedef Documentation

typedef unsigned Xapian::doccount

A count of documents.

This is used to hold values such as the number of documents in a database and the frequency of a term in the database.

typedef int Xapian::doccount_diff

A signed difference between two counts of documents.

This is used by the Xapian classes which are STL containers of documents for "difference_type".

typedef unsigned Xapian::docid

A unique identifier for a document.

Docid 0 is invalid, providing an "out of range" value which can be used to mean "not a valid document".

typedef double Xapian::doclength

A normalised document length.

The normalised document length is the document length divided by the average document length in the database.

typedef int Xapian::percent

The percentage score for a document in an MSet.

typedef unsigned Xapian::termcount

A counts of terms.

This is used to hold values such as the Within Document Frequency (wdf).

typedef int Xapian::termcount_diff

A signed difference between two counts of terms.

This is used by the Xapian classes which are STL containers of terms for "difference_type".

typedef int Xapian::termpos_diff

A signed difference between two term positions.

This is used by the Xapian classes which are STL containers of positions for "difference_type".

typedef unsigned Xapian::timeout

A timeout value in milliseconds.

There are 1000 milliseconds in a second, so for example, to set a timeout of 5 seconds use 5000.

typedef unsigned Xapian::valueno

The number for a value slot in a document.

Value slot numbers are unsigned and (currently) a 32-bit quantity, with Xapian::BAD_VALUENO being represented by the largest possible value. Therefore value slots 0 to 0xFFFFFFFE are available for use.

typedef int Xapian::valueno_diff

A signed difference between two value slot numbers.

This is used by the Xapian classes which are STL containers of values for "difference_type".

typedef double Xapian::weight

The weight of a document or term.

## Function Documentation

int Xapian::major_version | ( |  | ) |

Report the major version of the library which the program is linked with.

This may be different to the version compiled against (given by XAPIAN_MAJOR_VERSION) if shared libraries are being used.

int Xapian::minor_version | ( |  | ) |

Report the minor version of the library which the program is linked with.

This may be different to the version compiled against (given by XAPIAN_MINOR_VERSION) if shared libraries are being used.

int Xapian::revision | ( |  | ) |

Report the revision of the library which the program is linked with.

This may be different to the version compiled against (given by XAPIAN_REVISION) if shared libraries are being used.

std::string Xapian::sortable_serialise | ( | double | value | ) |

Convert a floating point number to a string, preserving sort order.

This method converts a floating point number to a string, suitable for using as a value for numeric range restriction, or for use as a sort key.

The conversion is platform independent.

The conversion attempts to ensure that, for any pair of values supplied to the conversion algorithm, the result of comparing the original values (with a numeric comparison operator) will be the same as the result of comparing the resulting values (with a string comparison operator). On platforms which represent doubles with the precisions specified by IEEE_754, this will be the case: if the representation of doubles is more precise, it is possible that two very close doubles will be mapped to the same string, so will compare equal.

Note also that both zero and -zero will be converted to the same representation: since these compare equal, this satisfies the comparison constraint, but it's worth knowing this if you wish to use the encoding in some situation where this distinction matters.

Handling of NaN isn't (currently) guaranteed to be sensible.

Parameters:

  | value | The number to serialise.

double Xapian::sortable_unserialise | ( | const std::string & | value | ) |

Convert a string encoded using sortable_serialise back to a floating point number.

This expects the input to be a string produced by sortable_serialise(). If the input is not such a string, the value returned is undefined (but no error will be thrown).

The result of the conversion will be exactly the value which was supplied to sortable_serialise() when making the string on platforms which represent doubles with the precisions specified by IEEE_754, but may be a different (nearby) value on other platforms.

Parameters:

  | value | The serialised string to decode.

const char* Xapian::version_string | ( |  | ) |

Report the version string of the library which the program is linked with.

This may be different to the version compiled against (given by XAPIAN_VERSION) if shared libraries are being used.

## Variable Documentation

const valueno Xapian::BAD_VALUENO = static_cast<valueno>(-1)

Reserved value to indicate "no valueno".

const int Xapian::DB_CREATE = 2

Create a new database; fail if db exists.

const int Xapian::DB_CREATE_OR_OPEN = 1

Open for read/write; create if no db exists.

const int Xapian::DB_CREATE_OR_OVERWRITE = 3

Overwrite existing db; create if none exists.

const int Xapian::DB_OPEN = 4

Open for read/write; fail if no db exists.