Xapian: API Documentation: Xapian::Document Class Reference

xapian-core 2.0.0

Public Member Functions | Static Public Member Functions | List of all members
Xapian::Document Class Reference

Class representing a document. More...

`#include <document.h>`

## Public Member Functions
| Document (const Document &o)
| Copy constructor.
Document & | operator= (const Document &o)
| Assignment operator.
| Document (Document &&o)
| Move constructor.
Document & | operator= (Document &&o)
| Move assignment operator.
| Document ()
| Default constructor.
| ~Document ()
| Destructor.
Xapian::docid | get_docid () const
| Get the document ID this document came from.
std::string | get_data () const
| Get the document data.
void | set_data (std::string_view data)
| Set the document data.
void | add_term (std::string_view term, Xapian::termcount wdf_inc=1)
| Add a term to this document.
void | add_boolean_term (std::string_view term)
| Add a boolean filter term to the document.
void | remove_term (std::string_view term)
| Remove a term from this document.
void | add_posting (std::string_view term, Xapian::termpos term_pos, Xapian::termcount wdf_inc=1)
| Add a posting for a term.
void | remove_posting (std::string_view term, Xapian::termpos term_pos, Xapian::termcount wdf_dec=1)
| Remove posting for a term.
Xapian::termpos | remove_postings (std::string_view 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 | 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.
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.
void | add_value (Xapian::valueno slot, std::string_view value)
| Add a value to a slot in this document.
void | remove_value (Xapian::valueno slot)
| Remove any value from the specified slot.
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.
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.
std::string | get_description () const
| Return a string describing this object.

## Static Public Member Functions
static Document | unserialise (std::string_view 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 | ( | std::string_view | 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

  term | The term to add.

Since
  This method was added in Xapian 1.0.18.

References add_term().

## ◆ add_value()

void Xapian::Document::add_value | ( | Xapian::valueno | slot,
|  | std::string_view | value )

Add a value to a slot in this document.

Parameters

  slot | The slot to set
  value | The new value

Referenced by remove_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

  slot | The 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 | ( | std::string_view | 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 2.0.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 | ( | std::string_view | 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 2.0.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

  slot | The slot to remove any value from.

References add_value().

## ◆ 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 | ( | std::string_view | data | ) |

Set the document data.

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.

## ◆ swap()

void Xapian::Document::swap | ( | Document & | o | ) |
| inline

Efficiently swap this Document object with another.

Since
  Added in Xapian 2.0.0.

## ◆ termlist_begin()

TermIterator Xapian::Document::termlist_begin | ( |  | ) | const

Start iterating the terms in this document.

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

Note that if the Document object came from a sharded database then the TermIterator returned by this method only knows about the shard the document came from so calling get_termfreq() on it will give you the term frequency in that shard rather than in the combined database.

## ◆ 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:

- xapian/document.h