<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Deprecation</title>
<style type="text/css">
/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin: 0 0 0.5em 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left {
clear: left }
img.align-right {
clear: right }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="deprecation">
<h1 class="title">Deprecation</h1>
<!-- This document was originally written by Richard Boulton. -->
<!-- Copyright (C) 2007 Lemur Consulting Ltd -->
<!-- Copyright (C) 2007,2009 Olly Betts -->
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id22">Introduction</a></li>
<li><a class="reference internal" href="#deprecation-procedure" id="id23">Deprecation Procedure</a><ul>
<li><a class="reference internal" href="#deprecation-markers" id="id24">Deprecation markers</a></li>
<li><a class="reference internal" href="#api-and-abi-compatibility" id="id25">API and ABI compatibility</a></li>
<li><a class="reference internal" href="#deprecation-in-the-bindings" id="id26">Deprecation in the bindings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#how-to-avoid-using-deprecated-features" id="id27">How to avoid using deprecated features</a></li>
<li><a class="reference internal" href="#features-currently-marked-for-deprecation" id="id28">Features currently marked for deprecation</a><ul>
<li><a class="reference internal" href="#native-c-api" id="id29">Native C++ API</a></li>
<li><a class="reference internal" href="#bindings" id="id30">Bindings</a></li>
<li><a class="reference internal" href="#omega" id="id31">Omega</a></li>
</ul>
</li>
<li><a class="reference internal" href="#features-removed-from-xapian" id="id32">Features removed from Xapian</a><ul>
<li><a class="reference internal" href="#id8" id="id33">Native C++ API</a></li>
<li><a class="reference internal" href="#id9" id="id34">Bindings</a></li>
<li><a class="reference internal" href="#id21" id="id35">Omega</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id22">Introduction</a></h1>
<p>Xapian's API is fairly stable and has been polished piece by piece over time,
but it still occasionally needs to be changed. This may be because a new
feature has been implemented and the interface needs to allow access to it, but
it may also be required in order to polish a rough edge which has been missed
in earlier versions of Xapian, or simply to reflect an internal change which
requires a modification to the external interface.</p>
<p>We aim to make such changes in a way that allows developers to work against a
stable API, while avoiding the need for the Xapian developers to maintain too
many old historical interface artefacts. This document describes the process
we use to deprecate old pieces of the API, lists parts of the API which are
currently marked as deprecated, and also describes parts of the API which have
been deprecated for some time, and are now removed from the Xapian library.</p>
<p>It is possible for functions, methods, constants, types or even whole classes
to be deprecated, but to save words this document will often use the term
"features" to refer collectively to any of these types of interface items.</p>
</div>
<div class="section" id="deprecation-procedure">
<h1><a class="toc-backref" href="#id23">Deprecation Procedure</a></h1>
<div class="section" id="deprecation-markers">
<h2><a class="toc-backref" href="#id24">Deprecation markers</a></h2>
<p>At any particular point, some parts of the C++ API will be marked as
"deprecated". This is indicated with the <tt class="docutils literal"><span class="pre">XAPIAN_DEPRECATED</span></tt> macro, which
will cause compilers with appropriate support (such as GCC 3.1 or later, and
MSVC 7.0 or later) to emit warning messages about the use of deprecated
features at compile time.</p>
<p>If a feature is marked with one of these markers, you should avoid using it in
new code, and should migrate your code to use a replacement when possible. The
documentation comments for the feature, or the list at the end
of this file, will describe possible alternatives to the deprecated feature.</p>
<p>If you want to disable deprecation warnings temporarily, you can do so
by passing <tt class="docutils literal"><span class="pre">"-DXAPIAN_DEPRECATED(X)=X"</span></tt> to the compiler (the quotes are
needed to protect the brackets from the shell). If your build system uses
make, you might do this like so:</p>
<pre class="literal-block">
make 'CPPFLAGS="-DXAPIAN_DEPRECATED(X)=X"'
</pre>
</div>
<div class="section" id="api-and-abi-compatibility">
<h2><a class="toc-backref" href="#id25">API and ABI compatibility</a></h2>
<p>Within a series of releases with a given major and minor number, we try to
maintain API and ABI forwards compatibility. This means that an application
written and compiled against version <cite>X.Y.a</cite> of Xapian should work, without any
changes or need to recompile, with a later version <cite>X.Y.b</cite>, for all <cite>a</cite> <= <cite>b</cite>.</p>
<p>It is possible that a feature may be marked as deprecated within a minor
release series - that is from version <cite>X.Y.c</cite>
onwards, where <cite>c</cite> is not zero. The API and ABI will not be changed by this
deprecation, since the feature will still be available in the API (though the
change may cause the compiler to emit new warnings at compile time).</p>
<p>In general, a feature will be supported after being deprecated for an entire
series of releases with a given major and minor number. For example, if a
feature is deprecated in release <cite>1.2.0</cite>, it will be supported for the entire
<cite>1.2.x</cite> release series, and removed in release <cite>1.3.0</cite>. If a feature is
deprecated in release <cite>1.2.5</cite>, it will be supported for all remaining releases
in the <cite>1.2.x</cite> series, and also for all releases in the <cite>1.3.x</cite> series, and
will be removed in release <cite>1.4.0</cite>.</p>
<p>However, this rule may not be followed in all cases. In particular, if a
feature was marked as "temporary" in the documentation, it may be removed
faster (and possibly, without even passing through a stage of being
deprecated).</p>
</div>
<div class="section" id="deprecation-in-the-bindings">
<h2><a class="toc-backref" href="#id26">Deprecation in the bindings</a></h2>
<p>When the Xapian API changes, the interface provided by the Xapian bindings will
usually change in step. In addition, it is sometimes necessary to change the
way in which Xapian is wrapped by bindings - for example, to provide a better
convenience wrapper for iterators in Python. Again, we aim to ensure that an
application written (and compiled, if the language being bound is a compiled
language) for version <cite>X.Y.a</cite> of Xapian should work without any changes or need
to recompile, with a later version <cite>X.Y.b</cite>, for all <cite>a</cite> <= <cite>b</cite>.</p>
<p>However, the bindings are a little less mature than the core C++ API, so we
don't intend to give the same guarantee that a feature present and not
deprecated in version <cite>X.Y.a</cite> will work in all versions <cite>X+1.Y.b</cite>. In other
words, we may remove features which have been deprecated without waiting for
an entire release series to pass.</p>
<p>Any planned deprecations will be documented in the list of deprecations and
removed features at the end of this file.</p>
</div>
</div>
<div class="section" id="how-to-avoid-using-deprecated-features">
<h1><a class="toc-backref" href="#id27">How to avoid using deprecated features</a></h1>
<p>We recommend taking the following steps to avoid depending on deprecated
features when writing your applications:</p>
<blockquote>
<ul class="simple">
<li>If at all possible, test compile your project using a compiler which
supports warnings about deprecated features (such as GCC 3.1 or later), and
check for such warnings. Use the -Werror flag to GCC to ensure that you
don't miss any of them.</li>
<li>Check the NEWS file for each new release for details of any new features
which are deprecated in the release.</li>
<li>Check the documentation comments, or the automatically extracted API
documentation, for each feature you use in your application. This
documentation will indicate features which are deprecated, or planned for
deprecation.</li>
<li>For applications which are not written in C++, there is currently no
equivalent of the <tt class="docutils literal"><span class="pre">XAPIAN_DEPRECATED</span></tt> macro for the bindings, and thus
there is no way for the bindings to give a warning if a deprecated feature
is used. This would be a nice addition for those languages in which there
is a reasonable way to give such warnings. Until such a feature is
implemented, all application writers using the bindings can do is to check
the list of deprecated features in each new release, or lookup the features
they are using in the list at the end of this file.</li>
</ul>
</blockquote>
</div>
<div class="section" id="features-currently-marked-for-deprecation">
<h1><a class="toc-backref" href="#id28">Features currently marked for deprecation</a></h1>
<div class="section" id="native-c-api">
<h2><a class="toc-backref" href="#id29">Native C++ API</a></h2>
<!-- Keep table width to <= 126 columns. -->
<table border="1" class="docutils">
<colgroup>
<col width="8%" />
<col width="5%" />
<col width="28%" />
<col width="59%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Deprecated</th>
<th class="head">Remove</th>
<th class="head">Feature name</th>
<th class="head">Upgrade suggestion and comments</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>0.9.6</td>
<td>1.1.0</td>
<td>xapian_version_string()</td>
<td>Use <tt class="docutils literal"><span class="pre">version_string()</span></tt> instead.</td>
</tr>
<tr><td>0.9.6</td>
<td>1.1.0</td>
<td>xapian_major_version()</td>
<td>Use <tt class="docutils literal"><span class="pre">major_version()</span></tt> instead.</td>
</tr>
<tr><td>0.9.6</td>
<td>1.1.0</td>
<td>xapian_minor_version()</td>
<td>Use <tt class="docutils literal"><span class="pre">minor_version()</span></tt> instead.</td>
</tr>
<tr><td>0.9.6</td>
<td>1.1.0</td>
<td>xapian_revision()</td>
<td>Use <tt class="docutils literal"><span class="pre">revision()</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>1.1.0</td>
<td>Enquire::include_query_terms</td>
<td>Use <tt class="docutils literal"><span class="pre">Enquire::INCLUDE_QUERY_TERMS</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>1.1.0</td>
<td>Enquire::use_exact_termfreq</td>
<td>Use <tt class="docutils literal"><span class="pre">Enquire::USE_EXACT_TERMFREQ</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>1.1.0</td>
<td>Error::get_errno()</td>
<td>Use <tt class="docutils literal"><span class="pre">Error::get_error_string()</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>1.1.0</td>
<td>The Quartz backend</td>
<td>Use the Flint backend instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>1.1.0</td>
<td>Quartz::open()</td>
<td>Use <tt class="docutils literal"><span class="pre">Flint::open()</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>1.1.0</td>
<td>quartzcheck</td>
<td>Use <tt class="docutils literal"><span class="pre">xapian-check</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>1.1.0</td>
<td>quartzcompact</td>
<td>Use <tt class="docutils literal"><span class="pre">xapian-compact</span></tt> instead.</td>
</tr>
<tr><td>1.0.3</td>
<td>1.1.0</td>
<td>Enquire::register_match_decider()</td>
<td>This method didn't do anything, so just remove calls to it!</td>
</tr>
<tr><td>1.0.3</td>
<td>1.1.0</td>
<td><tt class="docutils literal"><span class="pre">Database::positionlist_begin()</span></tt>
throwing <tt class="docutils literal"><span class="pre">RangeError</span></tt> if the
term specified doesn't index the
document specified.</td>
<td>This check is quite expensive, and often you don't care. If you
do it's easy to check - just open a <tt class="docutils literal"><span class="pre">TermListIterator</span></tt> for the
document and use <tt class="docutils literal"><span class="pre">skip_to()</span></tt> to check if the term is there.</td>
</tr>
<tr><td>1.0.3</td>
<td>1.1.0</td>
<td><tt class="docutils literal"><span class="pre">Database::positionlist_begin()</span></tt>
throwing <tt class="docutils literal"><span class="pre">DocNotFoundError</span></tt> if
the document specified doesn't
exist.</td>
<td>This check is quite expensive, and often you don't care. If you
do, it's easy to check - just call <tt class="docutils literal"><span class="pre">Database::get_document()</span></tt> with the
specified document ID.</td>
</tr>
<tr><td>1.0.4</td>
<td>1.1.0</td>
<td>Query::Query(Query::op, Query)</td>
<td>This constructor isn't useful for any currently implemented
<tt class="docutils literal"><span class="pre">Query::op</span></tt>.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="bindings">
<h2><a class="toc-backref" href="#id30">Bindings</a></h2>
<!-- Keep table width to <= 126 columns. -->
<table border="1" class="docutils">
<colgroup>
<col width="8%" />
<col width="5%" />
<col width="7%" />
<col width="23%" />
<col width="57%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Deprecated</th>
<th class="head">Remove</th>
<th class="head">Language</th>
<th class="head">Feature name</th>
<th class="head">Upgrade suggestion and comments</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>0.9.6</td>
<td>1.1.0</td>
<td>SWIG
<a class="footnote-reference" href="#swig" id="id1">[1]</a></td>
<td>xapian_version_string()</td>
<td>Use <tt class="docutils literal"><span class="pre">version_string()</span></tt> instead.</td>
</tr>
<tr><td>0.9.6</td>
<td>1.1.0</td>
<td>SWIG
<a class="footnote-reference" href="#swig" id="id2">[1]</a></td>
<td>xapian_major_version()</td>
<td>Use <tt class="docutils literal"><span class="pre">major_version()</span></tt> instead.</td>
</tr>
<tr><td>0.9.6</td>
<td>1.1.0</td>
<td>SWIG
<a class="footnote-reference" href="#swig" id="id3">[1]</a></td>
<td>xapian_minor_version()</td>
<td>Use <tt class="docutils literal"><span class="pre">minor_version()</span></tt> instead.</td>
</tr>
<tr><td>0.9.6</td>
<td>1.1.0</td>
<td>SWIG
<a class="footnote-reference" href="#swig" id="id4">[1]</a></td>
<td>xapian_revision()</td>
<td>Use <tt class="docutils literal"><span class="pre">revision()</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>1.1.0</td>
<td>SWIG
<a class="footnote-reference" href="#swig" id="id5">[1]</a></td>
<td>ESet::get_termname()</td>
<td>Use <tt class="docutils literal"><span class="pre">ESet::get_term()</span></tt> instead. This change is intended to bring
the ESet iterators in line with other term iterators, which all
support <tt class="docutils literal"><span class="pre">get_term()</span></tt> instead of <tt class="docutils literal"><span class="pre">get_termname()</span></tt>.</td>
</tr>
<tr><td>1.0.0</td>
<td>1.1.0</td>
<td>Python</td>
<td>get_description()</td>
<td>All <tt class="docutils literal"><span class="pre">get_description()</span></tt> methods have been renamed to <tt class="docutils literal"><span class="pre">__str__()</span></tt>,
so the normal python <tt class="docutils literal"><span class="pre">str()</span></tt> function can be used.</td>
</tr>
<tr><td>1.0.0</td>
<td>1.1.0</td>
<td>Python</td>
<td>MSetItem.get_*()</td>
<td>All these methods are deprecated, in favour of properties.
To convert, just change <tt class="docutils literal"><span class="pre">msetitem.get_FOO()</span></tt> to <tt class="docutils literal"><span class="pre">msetitem.FOO</span></tt></td>
</tr>
<tr><td>1.0.0</td>
<td>1.1.0</td>
<td>Python</td>
<td>Enquire.get_matching_terms</td>
<td>Replaced by <tt class="docutils literal"><span class="pre">Enquire.matching_terms</span></tt>, for consistency with
rest of Python API.</td>
</tr>
<tr><td>1.0.0</td>
<td>1.1.0</td>
<td>SWIG
<a class="footnote-reference" href="#swig" id="id6">[1]</a></td>
<td>Error::get_errno()</td>
<td>Use <tt class="docutils literal"><span class="pre">Error::get_error_string()</span></tt> instead.</td>
</tr>
<tr><td>0.9.6</td>
<td>1.1.0</td>
<td>SWIG
<a class="footnote-reference" href="#swg2" id="id7">[2]</a></td>
<td>MSet::get_document_id()</td>
<td>Use <tt class="docutils literal"><span class="pre">MSet::get_docid()</span></tt> instead.</td>
</tr>
<tr><td>1.0.4</td>
<td>1.3.0</td>
<td>Python</td>
<td>Non-pythonic iterators</td>
<td>Use the pythonic iterators instead.</td>
</tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="swig" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[1]</td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id2">2</a>, <a class="fn-backref" href="#id3">3</a>, <a class="fn-backref" href="#id4">4</a>, <a class="fn-backref" href="#id5">5</a>, <a class="fn-backref" href="#id6">6</a>)</em> This affects all SWIG-generated bindings (currently: Python, PHP, Ruby, Tcl8 and CSharp)</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="swg2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id7">[2]</a></td><td>This affects all SWIG-generated bindings except those for Ruby, support for which was added after the function waan-core.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="omega">
<h2><a class="toc-backref" href="#id31">Omega</a></h2>
<!-- Keep table width to <= 126 columns. -->
<table border="1" class="docutils">
<colgroup>
<col width="8%" />
<col width="5%" />
<col width="28%" />
<col width="59%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Deprecated</th>
<th class="head">Remove</th>
<th class="head">Feature name</th>
<th class="head">Upgrade suggestion and comments</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>0.9.5</td>
<td>1.1.0</td>
<td>scriptindex index=nopos</td>
<td>Use <tt class="docutils literal"><span class="pre">indexnopos</span></tt> instead.</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="features-removed-from-xapian">
<h1><a class="toc-backref" href="#id32">Features removed from Xapian</a></h1>
<div class="section" id="id8">
<h2><a class="toc-backref" href="#id33">Native C++ API</a></h2>
<!-- Keep table width to <= 126 columns. -->
<table border="1" class="docutils">
<colgroup>
<col width="6%" />
<col width="28%" />
<col width="66%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Removed</th>
<th class="head">Feature name</th>
<th class="head">Upgrade suggestion and comments</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>1.0.0</td>
<td>QueryParser::set_stemming_options()</td>
<td><p class="first">Use <tt class="docutils literal"><span class="pre">set_stemmer()</span></tt>, <tt class="docutils literal"><span class="pre">set_stemming_strategy()</span></tt> and/or <tt class="docutils literal"><span class="pre">set_stopper()</span></tt>
instead:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">set_stemming_options("")</span></tt> becomes
<tt class="docutils literal"><span class="pre">set_stemming_strategy(Xapian::QueryParser::STEM_NONE)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_stemming_options("none")</span></tt> becomes
<tt class="docutils literal"><span class="pre">set_stemming_strategy(Xapian::QueryParser::STEM_NONE)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_stemming_options(LANG)</span></tt> becomes
<tt class="docutils literal"><span class="pre">set_stemmer(Xapian::Stem(LANG)</span></tt> and
<tt class="docutils literal"><span class="pre">set_stemming_strategy(Xapian::QueryParser::STEM_SOME)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_stemming_options(LANG,</span> <span class="pre">false)</span></tt> becomes
<tt class="docutils literal"><span class="pre">set_stemmer(Xapian::Stem(LANG)</span></tt> and
<tt class="docutils literal"><span class="pre">set_stemming_strategy(Xapian::QueryParser::STEM_SOME)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_stemming_options(LANG,</span> <span class="pre">true)</span></tt> becomes
<tt class="docutils literal"><span class="pre">set_stemmer(Xapian::Stem(LANG)</span></tt> and
<tt class="docutils literal"><span class="pre">set_stemming_strategy(Xapian::QueryParser::STEM_ALL)</span></tt></li>
</ul>
<p class="last">If a third parameter is passed, <tt class="docutils literal"><span class="pre">set_stopper(PARAM3)</span></tt> and treat the first two
parameters as above.</p>
</td>
</tr>
<tr><td>1.0.0</td>
<td>Enquire::set_sort_forward()</td>
<td><p class="first">Use <tt class="docutils literal"><span class="pre">Enquire::set_docid_order()</span></tt> instead:</p>
<blockquote class="last">
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">set_sort_forward(true)</span></tt> becomes <tt class="docutils literal"><span class="pre">set_docid_order(ASCENDING)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_sort_forward(false)</span></tt> becomes <tt class="docutils literal"><span class="pre">set_docid_order(DESCENDING)</span></tt></li>
</ul>
</blockquote>
</td>
</tr>
<tr><td>1.0.0</td>
<td>Enquire::set_sorting()</td>
<td><p class="first">Use <tt class="docutils literal"><span class="pre">Enquire::set_sort_by_relevance()</span></tt>, <tt class="docutils literal"><span class="pre">Enquire::set_sort_by_value()</span></tt>, or
<tt class="docutils literal"><span class="pre">Enquire::set_sort_by_value_then_relevance()</span></tt> instead.</p>
<blockquote class="last">
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">set_sorting(KEY,</span> <span class="pre">1)</span></tt> becomes <tt class="docutils literal"><span class="pre">set_sort_by_value(KEY)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_sorting(KEY,</span> <span class="pre">1,</span> <span class="pre">false)</span></tt> becomes <tt class="docutils literal"><span class="pre">set_sort_by_value(KEY)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_sorting(KEY,</span> <span class="pre">1,</span> <span class="pre">true)</span></tt> becomes <tt class="docutils literal"><span class="pre">set_sort_by_value_then_relevance(KEY)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_sorting(ANYTHING,</span> <span class="pre">0)</span></tt> becomes <tt class="docutils literal"><span class="pre">set_sort_by_relevance()</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_sorting(Xapian::BAD_VALUENO,</span> <span class="pre">ANYTHING)</span></tt> becomes
<tt class="docutils literal"><span class="pre">set_sort_by_relevance()</span></tt></li>
</ul>
</blockquote>
</td>
</tr>
<tr><td>1.0.0</td>
<td>Stem::stem_word(word)</td>
<td>Use <tt class="docutils literal"><span class="pre">Stem::operator()(word)</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>Auto::open(path)</td>
<td>Use the <tt class="docutils literal"><span class="pre">Database(path)</span></tt> constructor instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>Auto::open(path, action)</td>
<td>Use the <tt class="docutils literal"><span class="pre">WritableDatabase(path,</span> <span class="pre">action)</span></tt> constructor instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>Query::is_empty()</td>
<td>Use <tt class="docutils literal"><span class="pre">Query::empty()</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>Document::add_term_nopos()</td>
<td>Use <tt class="docutils literal"><span class="pre">Document::add_term()</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>Enquire::set_bias()</td>
<td>No replacement yet implemented.</td>
</tr>
<tr><td>1.0.0</td>
<td>ExpandDecider::operator()</td>
<td>Return type is now <tt class="docutils literal"><span class="pre">bool</span></tt> not <tt class="docutils literal"><span class="pre">int</span></tt>.</td>
</tr>
<tr><td>1.0.0</td>
<td>MatchDecider::operator()</td>
<td>Return type is now <tt class="docutils literal"><span class="pre">bool</span></tt> not <tt class="docutils literal"><span class="pre">int</span></tt>.</td>
</tr>
<tr><td>1.0.0</td>
<td>Error::get_type()</td>
<td>Return type is now <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> not <tt class="docutils literal"><span class="pre">std::string</span></tt>. Most existing code
won't need changes, but if it does the simplest fix is to write
<tt class="docutils literal"><span class="pre">std::string(e.get_type())</span></tt> instead of <tt class="docutils literal"><span class="pre">e.get_type()</span></tt>.</td>
</tr>
<tr><td>1.0.0</td>
<td><xapian/output.h></td>
<td>Use <tt class="docutils literal"><span class="pre">cout</span> <span class="pre"><<</span> <span class="pre">obj.get_description();</span></tt> instead of <tt class="docutils literal"><span class="pre">cout</span> <span class="pre"><<</span> <span class="pre">obj;</span></tt></td>
</tr>
<tr><td>1.0.0</td>
<td>Several constructors marked
as explicit.</td>
<td>Explicitly create the object type required, for example use
<tt class="docutils literal"><span class="pre">Xapian::Enquire</span> <span class="pre">enq(Xapian::Database(path));</span></tt> instead of
<tt class="docutils literal"><span class="pre">Xapian::Enquire</span> <span class="pre">enq(path);</span></tt></td>
</tr>
<tr><td>1.0.0</td>
<td>QueryParser::parse_query() throwing
<tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt> exception.</td>
<td>Catch <tt class="docutils literal"><span class="pre">Xapian::QueryParserError</span></tt> instead of <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char</span> <span class="pre">*</span></tt>, and call
<tt class="docutils literal"><span class="pre">get_msg()</span></tt> on the caught object. If you need to build with either version,
catch both (you'll need to compile the part which catches <tt class="docutils literal"><span class="pre">QueryParserError</span></tt>
conditionally, since this exception isn't present in the 0.9 release series).</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="id9">
<h2><a class="toc-backref" href="#id34">Bindings</a></h2>
<!-- Keep table width to <= 126 columns. -->
<table border="1" class="docutils">
<colgroup>
<col width="6%" />
<col width="7%" />
<col width="23%" />
<col width="65%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Removed</th>
<th class="head">Language</th>
<th class="head">Feature name</th>
<th class="head">Upgrade suggestion and comments</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>1.0.0</td>
<td>SWIG
<a class="footnote-reference" href="#rswg" id="id10">[3]</a></td>
<td>Enquire::set_sort_forward()</td>
<td><p class="first">Use <tt class="docutils literal"><span class="pre">Enquire::set_docid_order()</span></tt> instead.</p>
<blockquote class="last">
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">set_sort_forward(true)</span></tt> becomes <tt class="docutils literal"><span class="pre">set_docid_order(ASCENDING)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_sort_forward(false)</span></tt> becomes <tt class="docutils literal"><span class="pre">set_docid_order(DESCENDING)</span></tt></li>
</ul>
</blockquote>
</td>
</tr>
<tr><td>1.0.0</td>
<td>SWIG
<a class="footnote-reference" href="#rswg" id="id11">[3]</a></td>
<td>Enquire::set_sorting()</td>
<td><p class="first">Use <tt class="docutils literal"><span class="pre">Enquire::set_sort_by_relevance()</span></tt>, <tt class="docutils literal"><span class="pre">Enquire::set_sort_by_value()</span></tt>
or <tt class="docutils literal"><span class="pre">Enquire::set_sort_by_value_then_relevance()</span></tt> instead.</p>
<blockquote class="last">
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">set_sorting(KEY,</span> <span class="pre">1)</span></tt> becomes <tt class="docutils literal"><span class="pre">set_sort_by_value(KEY)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_sorting(KEY,</span> <span class="pre">1,</span> <span class="pre">false)</span> <span class="pre">becomes</span> <span class="pre">``set_sort_by_value(KEY)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_sorting(KEY,</span> <span class="pre">1,</span> <span class="pre">true)</span></tt> becomes
<tt class="docutils literal"><span class="pre">set_sort_by_value_then_relevance(KEY)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_sorting(ANYTHING,</span> <span class="pre">0)</span> <span class="pre">becomes</span> <span class="pre">set_sort_by_relevance()</span></tt></li>
<li><tt class="docutils literal"><span class="pre">set_sorting(Xapian::BAD_VALUENO,</span> <span class="pre">ANYTHING)</span></tt> becomes
<tt class="docutils literal"><span class="pre">set_sort_by_relevance()</span></tt></li>
</ul>
</blockquote>
</td>
</tr>
<tr><td>1.0.0</td>
<td>SWIG
<a class="footnote-reference" href="#rswg" id="id12">[3]</a></td>
<td>Auto::open(path)</td>
<td>Use the <tt class="docutils literal"><span class="pre">Database(path)</span></tt> constructor instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>SWIG
<a class="footnote-reference" href="#rswg" id="id13">[3]</a></td>
<td>Auto::open(path, action)</td>
<td>Use the <tt class="docutils literal"><span class="pre">WritableDatabase(path,</span> <span class="pre">action)</span></tt> constructor instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>SWIG
<a class="footnote-reference" href="#rsw3" id="id14">[4]</a></td>
<td>MSet::is_empty()</td>
<td>Use <tt class="docutils literal"><span class="pre">MSet::empty()</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>SWIG
<a class="footnote-reference" href="#rsw3" id="id15">[4]</a></td>
<td>ESet::is_empty()</td>
<td>Use <tt class="docutils literal"><span class="pre">ESet::empty()</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>SWIG
<a class="footnote-reference" href="#rsw3" id="id16">[4]</a></td>
<td>RSet::is_empty()</td>
<td>Use <tt class="docutils literal"><span class="pre">RSet::empty()</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>SWIG
<a class="footnote-reference" href="#rsw3" id="id17">[4]</a></td>
<td>Query::is_empty()</td>
<td>Use <tt class="docutils literal"><span class="pre">Query::empty()</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>SWIG
<a class="footnote-reference" href="#rswg" id="id18">[3]</a></td>
<td>Document::add_term_nopos()</td>
<td>Use <tt class="docutils literal"><span class="pre">Document::add_term()</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>CSharp</td>
<td>ExpandDecider::Apply()</td>
<td>Return type is now <tt class="docutils literal"><span class="pre">bool</span></tt> instead of <tt class="docutils literal"><span class="pre">int</span></tt>.</td>
</tr>
<tr><td>1.0.0</td>
<td>CSharp</td>
<td>MatchDecider::Apply()</td>
<td>Return type is now <tt class="docutils literal"><span class="pre">bool</span></tt> instead of <tt class="docutils literal"><span class="pre">int</span></tt>.</td>
</tr>
<tr><td>1.0.0</td>
<td>SWIG
<a class="footnote-reference" href="#rswg" id="id19">[3]</a></td>
<td>Stem::stem_word(word)</td>
<td>Use <tt class="docutils literal"><span class="pre">Stem::operator()(word)</span></tt> instead. <a class="footnote-reference" href="#callable" id="id20">[5]</a></td>
</tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="rswg" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[3]</td><td><em>(<a class="fn-backref" href="#id10">1</a>, <a class="fn-backref" href="#id11">2</a>, <a class="fn-backref" href="#id12">3</a>, <a class="fn-backref" href="#id13">4</a>, <a class="fn-backref" href="#id18">5</a>, <a class="fn-backref" href="#id19">6</a>)</em> This affects all SWIG generated bindings (currently: Python, PHP, Ruby, Tcl8 and CSharp)</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="rsw3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[4]</td><td><em>(<a class="fn-backref" href="#id14">1</a>, <a class="fn-backref" href="#id15">2</a>, <a class="fn-backref" href="#id16">3</a>, <a class="fn-backref" href="#id17">4</a>)</em> This affects all SWIG generated bindings except those for Ruby, which was added after the function was deprecated in Xapian-core, and PHP, where empty is a reserved word (and therefore, the method remains "is_empty").</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="callable" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id20">[5]</a></td><td>Python handles this like C++. Ruby renames it to 'call' (idiomatic Ruby). PHP renames it to 'apply'. CSharp to 'Apply' (delegates could probably be used to provide C++-like functor syntax, but that's effort and it seems debatable if it would actually be more natural to a C# programmer). Tcl8 renames it to 'apply' - need to ask a Tcl type if that's the best solution.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="id21">
<h2><a class="toc-backref" href="#id35">Omega</a></h2>
<!-- Keep table width to <= 126 columns. -->
<table border="1" class="docutils">
<colgroup>
<col width="6%" />
<col width="28%" />
<col width="66%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Removed</th>
<th class="head">Feature name</th>
<th class="head">Upgrade suggestion and comments</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>1.0.0</td>
<td>$freqs</td>
<td>Use <tt class="docutils literal"><span class="pre">$map{$queryterms,$_:&nbsp;$nice{$freq{$_}}}</span></tt> instead.</td>
</tr>
<tr><td>1.0.0</td>
<td>scriptindex -u</td>
<td><tt class="docutils literal"><span class="pre">-u</span></tt> was ignored for compatibility with 0.7.5 and earlier, so just remove it.</td>
</tr>
<tr><td>1.0.0</td>
<td>scriptindex -q</td>
<td><tt class="docutils literal"><span class="pre">-q</span></tt> was ignored for compatibility with 0.6.1 and earlier, so just remove it.</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</body>
</html>
