xapian-core  1.4.24
Public Member Functions | Static Public Member Functions | List of all members
Xapian::Document Class Reference

A handle representing a document in a Xapian database. More...

#include <document.h>

Public Member Functions

 Document (const Document &other)
 Copying is allowed.
 
void operator= (const Document &other)
 Assignment is allowed.
 
 Document ()
 Make a new empty Document.
 
 ~Document ()
 Destructor.
 
std::string get_value (Xapian::valueno slot) const
 Get value by number.
 
void add_value (Xapian::valueno slot, const std::string &value)
 Add a new value.
 
void remove_value (Xapian::valueno slot)
 Remove any value with the given number.
 
void clear_values ()
 Remove all values associated with the document.
 
std::string get_data () const
 Get data stored in the document.
 
void set_data (const std::string &data)
 Set data stored in the document.
 
void add_posting (const std::string &tname, Xapian::termpos tpos, Xapian::termcount wdfinc=1)
 Add an occurrence of a term at a particular position.
 
void add_term (const std::string &tname, Xapian::termcount wdfinc=1)
 Add a term to the document, without positional information.
 
void add_boolean_term (const std::string &term)
 Add a boolean filter term to the document.
 
void remove_posting (const std::string &tname, Xapian::termpos tpos, Xapian::termcount wdfdec=1)
 Remove a posting of a term from the document.
 
Xapian::termpos remove_postings (const std::string &term, Xapian::termpos term_pos_first, Xapian::termpos term_pos_last, Xapian::termcount wdf_dec=1)
 Remove a range of postings for a term.
 
void remove_term (const std::string &tname)
 Remove a term and all postings associated with it.
 
void clear_terms ()
 Remove all terms (and postings) from the document.
 
Xapian::termcount termlist_count () const
 The length of the termlist - i.e.
 
TermIterator termlist_begin () const
 Iterator for the terms in this document.
 
TermIterator termlist_end () const
 Equivalent end iterator for termlist_begin().
 
Xapian::termcount values_count () const
 Count the values in this document.
 
ValueIterator values_begin () const
 Iterator for the values in this document.
 
ValueIterator values_end () const
 Equivalent end iterator for values_begin().
 
docid get_docid () const
 Get the document id which is associated with this document (if any).
 
std::string serialise () const
 Serialise document into a string.
 
std::string get_description () const
 Return a string describing this object.
 

Static Public Member Functions

static Document unserialise (const std::string &serialised)
 Unserialise a document from a string produced by serialise().
 

Detailed Description

A handle representing a document in a Xapian database.

The Document class fetches information from the database lazily. Usually this behaviour isn't visible to users (except for the speed benefits), but if the document in the database is modified or deleted, then preexisting Document objects may return the old or new versions of data (or throw Xapian::DocNotFoundError in the case of deletion).

Since Database objects work on a snapshot of the database's state, the situation above can only happen with a WritableDatabase object, or if you call Database::reopen() on a Database object.

We recommend you avoid designs where this behaviour is an issue, but if you need a way to make a non-lazy version of a Document object, you can do this like so:

doc = Xapian::Document::unserialise(doc.serialise());

Constructor & Destructor Documentation

◆ Document()

Xapian::Document::Document ( const Document other)

Copying is allowed.

The internals are reference counted, so copying is cheap.

Parameters
otherThe object to copy.

Member Function Documentation

◆ add_boolean_term()

void Xapian::Document::add_boolean_term ( const std::string &  term)
inline

Add a boolean filter term to the document.

This method adds term to the document with wdf of 0 - this is generally what you want for a term used for boolean filtering as the wdf of such terms is ignored, and it doesn't make sense for them to contribute to the document's length.

If the specified term already indexes this document, this method has no effect.

It is exactly the same as add_term(term, 0).

This method was added in Xapian 1.0.18.

Parameters
termThe term to add.

◆ add_posting()

void Xapian::Document::add_posting ( const std::string &  tname,
Xapian::termpos  tpos,
Xapian::termcount  wdfinc = 1 
)

Add an occurrence of a term at a particular position.

Multiple occurrences of the term at the same position are represented only once in the positional information, but do increase the wdf.

If the term is not already in the document, it will be added to it.

Parameters
tnameThe name of the term.
tposThe position of the term.
wdfincThe increment that will be applied to the wdf for this term.

◆ add_term()

void Xapian::Document::add_term ( const std::string &  tname,
Xapian::termcount  wdfinc = 1 
)

Add a term to the document, without positional information.

Any existing positional information for the term will be left unmodified.

Parameters
tnameThe name of the term.
wdfincThe increment that will be applied to the wdf for this term (default: 1).

◆ add_value()

void Xapian::Document::add_value ( Xapian::valueno  slot,
const std::string &  value 
)

Add a new value.

The new value will replace any existing value with the same number (or if the new value is empty, it will remove any existing value with the same number).

Parameters
slotThe value slot to add the value in.
valueThe value to set.

◆ get_data()

std::string Xapian::Document::get_data ( ) const

Get data stored in the document.

This is potentially a relatively expensive operation, and shouldn't normally be used during the match (e.g. in a PostingSource or match decider functor. Put data for use by match deciders in a value instead.

◆ get_docid()

docid Xapian::Document::get_docid ( ) const

Get the document id which is associated with this document (if any).

NB If multiple databases are being searched together, then this will be the document id in the individual database, not the merged database!

Returns
If this document came from a database, return the document id in that database. Otherwise, return 0 (in Xapian 1.0.22/1.2.4 or later; prior to this the returned value was uninitialised).

◆ get_value()

std::string Xapian::Document::get_value ( Xapian::valueno  slot) const

Get value by number.

Returns an empty string if no value with the given number is present in the document.

Parameters
slotThe number of the value.

◆ operator=()

void Xapian::Document::operator= ( const Document other)

Assignment is allowed.

The internals are reference counted, so assignment is cheap.

Parameters
otherThe object to copy.

◆ remove_posting()

void Xapian::Document::remove_posting ( const std::string &  tname,
Xapian::termpos  tpos,
Xapian::termcount  wdfdec = 1 
)

Remove a posting of a term from the document.

Note that the term will still index the document even if all occurrences are removed. To remove a term from a document completely, use remove_term().

Parameters
tnameThe name of the term.
tposThe position of the term.
wdfdecThe decrement that will be applied to the wdf when removing this posting. The wdf will not go below the value of 0.
Exceptions
Xapian::InvalidArgumentErrorwill be thrown if the term is not at the position specified in the position list for this term in this document.
Xapian::InvalidArgumentErrorwill be thrown if the term is not in the document

◆ remove_postings()

Xapian::termpos Xapian::Document::remove_postings ( const std::string &  term,
Xapian::termpos  term_pos_first,
Xapian::termpos  term_pos_last,
Xapian::termcount  wdf_dec = 1 
)

Remove a range of postings for a term.

Any instances of the term at positions >= term_pos_first and <= term_pos_last will be removed, and the wdf reduced by wdf_dec for each instance removed (the wdf will not ever go below zero though).

It's OK if the term doesn't occur in the range of positions specified (unlike remove_posting()). And if term_pos_first > term_pos_last, this method does nothing.

Returns
The number of postings removed.
Exceptions
Xapian::InvalidArgumentErrorwill be thrown if the term is not in the document
Since
Added in Xapian 1.4.8.

◆ remove_term()

void Xapian::Document::remove_term ( const std::string &  tname)

Remove a term and all postings associated with it.

Parameters
tnameThe name of the term.
Exceptions
Xapian::InvalidArgumentErrorwill be thrown if the term is not in the document

◆ serialise()

std::string Xapian::Document::serialise ( ) const

Serialise document into a string.

The document representation may change between Xapian releases: even between minor versions. However, it is guaranteed not to change if the remote database protocol has not changed between releases.

◆ set_data()

void Xapian::Document::set_data ( const std::string &  data)

Set data stored in the document.

This is an opaque blob as far as Xapian is concerned - it's up to you to impose whatever structure you want on it. If you want to store structured data, consider using something like protocol buffers.

Parameters
dataThe data to store.

◆ termlist_count()

Xapian::termcount Xapian::Document::termlist_count ( ) const

The length of the termlist - i.e.

the number of different terms which index this document.


The documentation for this class was generated from the following file: