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

Class representing a document. More...

Public Member Functions

 Document (const Document &o)
 Copy constructor. More...
 
Documentoperator= (const Document &o)
 Assignment operator. More...
 
 Document (Document &&o)
 Move constructor.
 
Documentoperator= (Document &&o)
 Move assignment operator.
 
 Document ()
 Default constructor. More...
 
 ~Document ()
 Destructor.
 
Xapian::docid get_docid () const
 Get the document ID this document came from. More...
 
std::string get_data () const
 Get the document data.
 
void set_data (const std::string &data)
 Set the document data.
 
void add_term (const std::string &term, Xapian::termcount wdf_inc=1)
 Add a term to this document.
 
void add_boolean_term (const std::string &term)
 Add a boolean filter term to the document. More...
 
void remove_term (const std::string &term)
 Remove a term from this document.
 
void add_posting (const std::string &term, Xapian::termpos term_pos, Xapian::termcount wdf_inc=1)
 Add a posting for a term.
 
void remove_posting (const std::string &term, Xapian::termpos term_pos, Xapian::termcount wdf_dec=1)
 Remove posting for a term. More...
 
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. More...
 
void clear_terms ()
 Clear all terms from the document.
 
Xapian::termcount termlist_count () const
 Return the number of distinct terms in this document.
 
TermIterator termlist_begin () const
 Start iterating the terms in this document. More...
 
TermIterator termlist_end () const noexcept
 End iterator corresponding to termlist_begin().
 
std::string get_value (Xapian::valueno slot) const
 Read a value slot in this document. More...
 
void add_value (Xapian::valueno slot, const std::string &value)
 Add a value to a slot in this document. More...
 
void remove_value (Xapian::valueno slot)
 Remove any value from the specified slot. More...
 
void clear_values ()
 Clear all value slots in this document.
 
Xapian::valueno values_count () const
 Count the value slots used in this document.
 
ValueIterator values_begin () const
 Start iterating the values in this document. More...
 
ValueIterator values_end () const noexcept
 End iterator corresponding to values_begin().
 
void swap (Document &o)
 Efficiently swap this Document object with another.
 
std::string serialise () const
 Serialise document into a string. More...
 
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

Class representing a document.

The term "document" shouldn't be taken too literally - really it's a "thing to retrieve", as the list of search results is essentially a list of documents.

Document objects fetch 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 the Database object which you got the Document from.

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() [1/2]

Xapian::Document::Document ( const Document o)

Copy constructor.

The internals are reference counted, so copying is cheap.

◆ Document() [2/2]

Xapian::Document::Document ( )

Default constructor.

Creates an empty Document.

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) and is provided as a way to make a common operation more explicit.

Parameters
termThe term to add.
Since
This method was added in Xapian 1.0.18.

◆ add_value()

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

Add a value to a slot in this document.

Parameters
slotThe slot to set
valueThe new value

◆ get_docid()

Xapian::docid Xapian::Document::get_docid ( ) const

Get the document ID this document came from.

If this document didn't come from a database, this will be 0 (in Xapian 1.0.22/1.2.4 or later; prior to this the returned value was uninitialised in this case).

Note that if the document came from a sharded database, this is the docid in the shard it came from, not the docid in the combined database.

◆ get_value()

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

Read a value slot in this document.

Parameters
slotThe slot to read the value from
Returns
The value in slot slot, or an empty string if not set.

◆ operator=()

Document& Xapian::Document::operator= ( const Document o)

Assignment operator.

The internals are reference counted, so assignment is cheap.

◆ remove_posting()

void Xapian::Document::remove_posting ( const std::string &  term,
Xapian::termpos  term_pos,
Xapian::termcount  wdf_dec = 1 
)

Remove posting for a term.

The instance of the specified term at position term_pos will be removed, and the wdf reduced by wdf_dec (the wdf will not ever go below zero though - the resultant wdf is clamped to zero if it would).

If the term doesn't occur at position term_pos then Xapian::InvalidArgumentError is thrown. If you want to remove a single position which may not be present without triggering an exception you can call remove_postings(term, pos, pos) instead.

Since 1.5.0, if the final position is removed and the wdf becomes zero then the term will be removed from 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 - the resultant wdf is clamped to zero if it would).

If the term doesn't occur in the range of positions specified (including if term_pos_first > term_pos_last) then this method does nothing (unlike remove_posting() which throws an exception if the specified position is not present).

Since 1.5.0, if all remaining positions are removed and the wdf becomes zero then the term will be removed from the document. Note that this only happens if some positions are removed though - calling this method on a term which has no positions and zero wdf won't remove that term.

Returns
The number of postings removed.
Since
Added in Xapian 1.4.8.

◆ remove_value()

void Xapian::Document::remove_value ( Xapian::valueno  slot)
inline

Remove any value from the specified slot.

Parameters
slotThe slot to remove any value from.

◆ 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.

◆ termlist_begin()

TermIterator Xapian::Document::termlist_begin ( ) const

Start iterating the terms in this document.

The terms are returned ascending string order (by byte value).

◆ values_begin()

ValueIterator Xapian::Document::values_begin ( ) const

Start iterating the values in this document.

The values are returned in ascending numerical slot order.


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