Xapian::Document Class Reference

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

#include <document.h>

Collaboration diagram for Xapian::Document:

List of all members.

Classes

class Internal

A document in the database, possibly plus modifications. More...

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.

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.

ValueIteratorEnd_ 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 &s)

Unserialise a document from a string produced by serialise().

Private Member Functions

Document (Internal *internal_)

Private Attributes

Xapian::Internal::RefCntPtr
< Internal > internal

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());

Definition at line 56 of file document.h.

Constructor & Destructor Documentation

Xapian::Document::Document ( Document::Internal * internal_ ) [explicit, private]

For internal use only.

Constructor is only used by internal classes.

Parameters:

internal_

pointer to internal opaque class

Definition at line 47 of file omdocument.cc.

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

Copying is allowed.

The internals are reference counted, so copying is cheap.

Parameters:

other

The object to copy.

Definition at line 83 of file omdocument.cc.

Xapian::Document::Document ( )

Make a new empty Document.

Definition at line 51 of file omdocument.cc.

Xapian::Document::~Document ( )

Destructor.

Definition at line 88 of file omdocument.cc.

Member Function Documentation

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:

term

The term to add.

Definition at line 178 of file document.h.

Referenced by DEFINE_TESTCASE(), and make_topercent7_db().

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:

	tname	The name of the term.
	tpos	The position of the term.
	wdfinc	The increment that will be applied to the wdf for this term.

Definition at line 120 of file omdocument.cc.

References LOGCALL_VOID.

Referenced by DEFINE_TESTCASE(), Xapian::TermGenerator::Internal::index_text(), FileIndexer::next(), and unserialise_document().

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:

	tname	The name of the term.
	wdfinc	The increment that will be applied to the wdf for this term (default: 1).

Definition at line 132 of file omdocument.cc.

References LOGCALL_VOID.

Referenced by basic_doc(), builddb_queries1(), builddb_valuestest1(), DEFINE_TESTCASE(), Xapian::TermGenerator::Internal::index_text(), make_all_tables(), make_all_tables2(), make_matchspy2_db(), make_missing_tables(), make_msize1_db(), make_msize2_db(), make_multichunk_db(), make_ordecay_db(), make_sparse_db(), make_topercent7_db(), make_xordecay1_db(), test_qp_flag_partial1(), test_qp_flag_wildcard1(), test_qp_flag_wildcard2(), test_qp_flag_wildcard3(), test_qp_spell1(), test_qp_stopword_group1(), test_serialisedoc1(), and unserialise_document().

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:

	slot	The value slot to add the value in.
	value	The value to set.

Definition at line 99 of file omdocument.cc.

References LOGCALL_VOID.

Referenced by bigoaddvalue1_helper(), builddb_valuestest1(), DEFINE_TESTCASE(), make_matchspy2_db(), make_msize1_db(), make_msize2_db(), make_valuerange5(), FileIndexer::next(), test_qp_value_range3(), test_serialisedoc1(), and unserialise_document().

void Xapian::Document::clear_terms ( )

Remove all terms (and postings) from the document.

Definition at line 160 of file omdocument.cc.

References LOGCALL_VOID.

void Xapian::Document::clear_values ( )

Remove all values associated with the document.

Definition at line 113 of file omdocument.cc.

References LOGCALL_VOID.

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.

Definition at line 63 of file omdocument.cc.

References internal, LOGCALL, and RETURN.

Referenced by InMemoryDatabase::add_document(), FlintWritableDatabase::add_document_(), ChertWritableDatabase::add_document_(), BrassWritableDatabase::add_document_(), DEFINE_TESTCASE(), main(), RemoteServer::msg_document(), SimpleMatchSpy::operator()(), myMatchDecider2::operator()(), myMatchDecider::operator()(), closedb1_iterators::perform(), InMemoryDatabase::replace_document(), FlintWritableDatabase::replace_document(), ChertWritableDatabase::replace_document(), BrassWritableDatabase::replace_document(), serialise_document(), and show_docdata().

string Xapian::Document::get_description ( ) const

Return a string describing this object.

Definition at line 93 of file omdocument.cc.

Referenced by DEFINE_TESTCASE().

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

Definition at line 196 of file omdocument.cc.

References internal, LOGCALL, and RETURN.

Referenced by DEFINE_TESTCASE().

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:

slot

The number of the value.

Definition at line 56 of file omdocument.cc.

References internal, LOGCALL, and RETURN.

Referenced by check_vals(), DEFINE_TESTCASE(), Xapian::ValueSetMatchDecider::operator()(), Xapian::ValueCountMatchSpy::operator()(), Xapian::MultiValueSorter::operator()(), Xapian::MultiValueKeyMaker::operator()(), closedb1_iterators::perform(), and show_value().

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

Assignment is allowed.

The internals are reference counted, so assignment is cheap.

Parameters:

other

The object to copy.

Definition at line 77 of file omdocument.cc.

References internal.

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:

	tname	The name of the term.
	tpos	The position of the term.
	wdfdec	The decrement that will be applied to the wdf when removing this posting. The wdf will not go below the value of 0.

Exceptions:

	Xapian::InvalidArgumentError	will be thrown if the term is not at the position specified in the position list for this term in this document.
	Xapian::InvalidArgumentError	will be thrown if the term is not in the document

Definition at line 142 of file omdocument.cc.

References LOGCALL_VOID.

Referenced by DEFINE_TESTCASE().

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

Remove a term and all postings associated with it.

Parameters:

tname

The name of the term.

Exceptions:

Xapian::InvalidArgumentError

will be thrown if the term is not in the document

Definition at line 153 of file omdocument.cc.

References LOGCALL_VOID.

Referenced by DEFINE_TESTCASE().

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

Remove any value with the given number.

Definition at line 106 of file omdocument.cc.

References LOGCALL_VOID.

Referenced by DEFINE_TESTCASE().

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.

Definition at line 203 of file omdocument.cc.

References LOGCALL, and serialise_document().

Referenced by DEFINE_TESTCASE().

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

Set data stored in the document.

Xapian treats the data as an opaque blob. It may try to compress it, but other than that it will just store it and return it when requested.

Parameters:

data

The data to store.

Definition at line 70 of file omdocument.cc.

References LOGCALL_VOID.

Referenced by builddb_valuestest1(), DEFINE_TESTCASE(), main(), make_matchspy2_db(), make_sparse_db(), make_topercent7_db(), FileIndexer::next(), test_serialisedoc1(), and unserialise_document().

TermIterator Xapian::Document::termlist_begin ( ) const

Iterator for the terms in this document.

Definition at line 173 of file omdocument.cc.

References internal, LOGCALL, and RETURN.

Referenced by FlintWritableDatabase::add_document_(), ChertWritableDatabase::add_document_(), BrassWritableDatabase::add_document_(), DEFINE_TESTCASE(), InMemoryDatabase::finish_add_doc(), format_doc_termlist(), closedb1_iterators::perform(), FlintWritableDatabase::replace_document(), ChertWritableDatabase::replace_document(), BrassWritableDatabase::replace_document(), serialise_document(), FlintTermListTable::set_termlist(), ChertTermListTable::set_termlist(), and BrassTermListTable::set_termlist().

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

The length of the termlist - i.e.

the number of different terms which index this document.

Definition at line 167 of file omdocument.cc.

References internal, LOGCALL, and RETURN.

Referenced by DEFINE_TESTCASE(), serialise_document(), FlintTermListTable::set_termlist(), ChertTermListTable::set_termlist(), and BrassTermListTable::set_termlist().

TermIterator Xapian::Document::termlist_end ( ) const [inline]

Equivalent end iterator for termlist_begin().

Definition at line 224 of file document.h.

Referenced by FlintWritableDatabase::add_document_(), ChertWritableDatabase::add_document_(), BrassWritableDatabase::add_document_(), DEFINE_TESTCASE(), InMemoryDatabase::finish_add_doc(), format_doc_termlist(), FlintWritableDatabase::replace_document(), ChertWritableDatabase::replace_document(), BrassWritableDatabase::replace_document(), serialise_document(), FlintTermListTable::set_termlist(), ChertTermListTable::set_termlist(), and BrassTermListTable::set_termlist().

Document Xapian::Document::unserialise ( const std::string & s ) [static]

Unserialise a document from a string produced by serialise().

Definition at line 210 of file omdocument.cc.

References LOGCALL_STATIC, and unserialise_document().

Referenced by DEFINE_TESTCASE().

ValueIterator Xapian::Document::values_begin ( ) const

Iterator for the values in this document.

Definition at line 186 of file omdocument.cc.

References internal, LOGCALL, and RETURN.

Referenced by ChertValueManager::add_document(), BrassValueManager::add_document(), FlintWritableDatabase::add_document_(), check_vals(), DEFINE_TESTCASE(), InMemoryDatabase::finish_add_doc(), RemoteServer::msg_document(), FlintWritableDatabase::replace_document(), serialise_document(), and show_values().

Xapian::termcount Xapian::Document::values_count ( ) const

Count the values in this document.

Definition at line 180 of file omdocument.cc.

References internal, LOGCALL, and RETURN.

Referenced by check_vals(), DEFINE_TESTCASE(), and serialise_document().

ValueIteratorEnd_ Xapian::Document::values_end ( ) const [inline]

Equivalent end iterator for values_begin().

Definition at line 235 of file document.h.

Referenced by ChertValueManager::add_document(), BrassValueManager::add_document(), FlintWritableDatabase::add_document_(), check_vals(), DEFINE_TESTCASE(), InMemoryDatabase::finish_add_doc(), RemoteServer::msg_document(), FlintWritableDatabase::replace_document(), serialise_document(), and show_values().

Member Data Documentation

Xapian::Internal::RefCntPtr<Internal> Xapian::Document::internal [private]

For internal use only.

Reference counted internals.

Definition at line 58 of file document.h.

Referenced by get_data(), get_docid(), get_value(), operator=(), FlintWritableDatabase::replace_document(), ChertValueManager::replace_document(), ChertWritableDatabase::replace_document(), BrassValueManager::replace_document(), BrassWritableDatabase::replace_document(), termlist_begin(), termlist_count(), values_begin(), and values_count().

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

include/xapian/document.h
api/omdocument.cc


Classes
class	Internal
	A document in the database, possibly plus modifications. More...
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.
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.
ValueIteratorEnd_	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 &s)
	Unserialise a document from a string produced by serialise().
Private Member Functions
	Document (Internal *internal_)
Private Attributes
Xapian::Internal::RefCntPtr < Internal >	internal