| blob | b4f4c0311a18ea2ee4519d39daaab6a936c6015c |
2 .. This document was originally written by Richard Boulton.
4 .. Copyright (C) 2007 Lemur Consulting Ltd
5 .. Copyright (C) 2007,2008,2009,2010,2011,2012,2013,2015,2016 Olly Betts
7 ===========
8 Deprecation
9 ===========
11 .. contents:: Table of contents
13 Introduction
14 ============
16 Xapian's API is fairly stable and has been polished piece by piece over time,
17 but it still occasionally needs to be changed. This may be because a new
18 feature has been implemented and the interface needs to allow access to it, but
19 it may also be required in order to polish a rough edge which has been missed
20 in earlier versions of Xapian, or simply to reflect an internal change which
21 requires a modification to the external interface.
23 We aim to make such changes in a way that allows developers to work against a
24 stable API, while avoiding the need for the Xapian developers to maintain too
25 many old historical interface artefacts. This document describes the process
26 we use to deprecate old pieces of the API, lists parts of the API which are
27 currently marked as deprecated, and also describes parts of the API which have
28 been deprecated for some time, and are now removed from the Xapian library.
30 It is possible for functions, methods, constants, types or even whole classes
31 to be deprecated, but to save words this document will often use the term
32 "features" to refer collectively to any of these types of interface items.
35 Deprecation Procedure
36 =====================
38 Deprecation markers
39 -------------------
41 At any particular point, some parts of the C++ API will be marked as
42 "deprecated". Deprecated features are annotated in the API headers with macros
43 such as ``XAPIAN_DEPRECATED()``, which will cause compilers with appropriate
44 support (such as GCC, clang and MSVC) to emit compile-time warnings if these
45 features are used.
47 If a feature is marked with one of these markers, you should avoid using it in
48 new code, and should migrate your code to use a replacement when possible. The
49 documentation comments for the feature, or the list at the end
50 of this file, will describe possible alternatives to the deprecated feature.
52 If you want to disable deprecation warnings temporarily, you can do so
53 by passing ``"-DXAPIAN_DEPRECATED(X)=X"`` to the compiler (the quotes are
54 needed to protect the brackets from the shell). If your build system uses
55 make, you might do this like so:
57 .. code-block:: sh
59 make 'CPPFLAGS="-DXAPIAN_DEPRECATED(X)=X"'
61 API and ABI compatibility
62 -------------------------
64 Releases are given three-part version numbers (e.g. 1.2.9), the three parts
65 being termed "major" (1), "minor" (2), and "revision" (9). Releases with
66 the same major and minor version are termed a "release series".
68 For Xapian releases 1.0.0 and higher, an even minor version indicates a stable
69 release series, while an odd minor version indicates a development release
70 series.
72 Within a stable release series, we strive to maintain API and ABI forwards
73 compatibility. This means that an application written and compiled against
74 version `X.Y.a` of Xapian should work, without any source changes or need to
75 recompile, with a later version `X.Y.b`, for all `b` >= `a`.
76 Stable releases which increase the minor or major version number will usually
77 change the ABI incompatibly (so that code will need to be recompiled against
78 the newer release series. They may also make incompatible API changes,
79 though we will attempt to do this in a way which makes it reasonably easy to
80 migrate applications, and document how to do so in this document.
82 It is possible that a feature may be marked as deprecated within a minor
83 release series - that is from version `X.Y.c`
84 onwards, where `c` is not zero. The API and ABI will not be changed by this
85 deprecation, since the feature will still be available in the API (though the
86 change may cause the compiler to emit new warnings when rebuilding code
87 which uses the now-deprecated feature).
89 Users should generally be able to expect working code which uses Xapian not to
90 stop working without reason. We attempt to codify this in the following
91 policy, but we reserve the right not to slavishly follow this. The spirit of
92 the rule should kept in mind - for example if we discovered a feature which
93 didn't actually work, making an incompatible API change at the next ABI bump
94 would be reasonable.
96 Normally a feature will be supported after being deprecated for an entire
97 stable release series. For example, if a feature is deprecated in release
98 1.2.0, it will be supported for the entire 1.2.x release series, and removed in
99 development release 1.3.0. If a feature is deprecated in release 1.2.1, it
100 will be supported for the 1.2.x *and* 1.4.x stable release series (and of
101 course the 1.3.x release series in between), and won't be removed until
102 1.5.0.
104 Experimental features
105 ---------------------
107 During a development release series (such as the 1.1.x series), some features
108 may be marked as "experimental". Such features are liable to change without
109 going through the normal deprecation procedure. This includes changing on-disk
110 formats for data stored by the feature, and breaking API and ABI compatibility
111 between releases for the feature. Such features are included in releases to
112 get wider use and corresponding feedback about them.
114 Deprecation in the bindings
115 ---------------------------
117 When the Xapian API changes, the interface provided by the Xapian bindings will
118 usually change in step. In addition, it is sometimes necessary to change the
119 way in which Xapian is wrapped by bindings - for example, to provide a better
120 convenience wrapper for iterators in Python. Again, we aim to ensure that an
121 application written (and compiled, if the language being bound is a compiled
122 language) for version `X.Y.a` of Xapian should work without any changes or need
123 to recompile, with a later version `X.Y.b`, for all `a` <= `b`.
125 However, the bindings are a little less mature than the core C++ API, so we
126 don't intend to give the same guarantee that a feature present and not
127 deprecated in version `X.Y.a` will work in all versions `X+1.Y.b`. In other
128 words, we may remove features which have been deprecated without waiting for
129 an entire release series to pass.
131 Any planned deprecations will be documented in the list of deprecations and
132 removed features at the end of this file.
134 Support for Other Software
135 ==========================
137 Support for other software doesn't follow the same deprecation rules as
138 for API features.
140 Our guiding principle for supporting version of other software is that
141 we don't aim to actively support versions which are no longer supported
142 "upstream".
144 So Xapian 1.1.0 doesn't support PHP4 because the PHP team no longer did
145 when it was released. By the API deprecation rules we should have announced
146 this when Xapian 1.0.0 was released, but we don't have control over when and
147 to what timescales other software providers discontinue support for older
148 versions.
150 Sometimes we can support such versions without extra effort (e.g. Tcl's
151 stubs mechanism means Tcl 8.1 probably still works, even though the last
152 8.1.x release was over a decade ago), and in some cases Linux distros
153 continue to support software after upstream stops.
155 But in most cases keeping support around is a maintenance overhead and
156 we'd rather spend our time on more useful things.
158 Note that there's no guarantee that we will support and continue to
159 support versions just because upstream still does. For example, we ceased
160 providing backported packages for Ubuntu dapper with Xapian 1.1.0 - in this
161 case, it's because we felt that if you're conservative enough to run dapper,
162 you'd probably prefer to stick with 1.0.x until you upgrade to hardy (the next
163 Ubuntu LTS release). But we may decide not to support versions for other
164 reasons too.
166 How to avoid using deprecated features
167 ======================================
169 We recommend taking the following steps to avoid depending on deprecated
170 features when writing your applications:
172 - If at all possible, test compile your project using a compiler which
173 supports warnings about deprecated features (such as GCC 3.1 or later), and
174 check for such warnings. Use the -Werror flag to GCC to ensure that you
175 don't miss any of them.
177 - Check the NEWS file for each new release for details of any new features
178 which are deprecated in the release.
180 - Check the documentation comments, or the automatically extracted API
181 documentation, for each feature you use in your application. This
182 documentation will indicate features which are deprecated, or planned for
183 deprecation.
185 - For applications which are not written in C++, there is currently no
186 equivalent of the ``XAPIAN_DEPRECATED`` macro for the bindings, and thus
187 there is no way for the bindings to give a warning if a deprecated feature
188 is used. This would be a nice addition for those languages in which there
189 is a reasonable way to give such warnings. Until such a feature is
190 implemented, all application writers using the bindings can do is to check
191 the list of deprecated features in each new release, or lookup the features
192 they are using in the list at the end of this file.
195 Features currently marked for deprecation
196 =========================================
198 Native C++ API
199 --------------
201 .. Substitution definitions for feature names which are two wide for the column:
203 .. |set_max_wildcard_expansion| replace:: ``Xapian::QueryParser::set_max_wildcard_expansion()``
204 .. |flush| replace:: ``Xapian::WritableDatabase::flush()``
205 .. |VRP| replace:: ``Xapian::ValueRangeProcessor``
206 .. |DateVRP| replace:: ``Xapian::DateValueRangeProcessor``
207 .. |NumberVRP| replace:: ``Xapian::NumberValueRangeProcessor``
208 .. |StringVRP| replace:: ``Xapian::StringValueRangeProcessor``
209 .. |add_valuerangeprocessor| replace:: ``Xapian::QueryParser::add_valuerangeprocessor()``
211 .. Keep table width to <= 126 columns.
213 ========== ====== =================================== ========================================================================
214 Deprecated Remove Feature name Upgrade suggestion and comments
215 ========== ====== =================================== ========================================================================
216 1.3.0 1.5.0 ``Xapian::timeout`` typedef Use ``unsigned`` instead, which should also work with older Xapian
217 releases.
218 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
219 1.3.0 1.5.0 ``Xapian::percent`` typedef Use ``int`` instead, which should also work with older Xapian releases.
220 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
221 1.3.0 1.5.0 ``Xapian::weight`` typedef Use ``double`` instead, which should also work with older Xapian
222 releases.
223 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
224 1.3.1 1.5.0 ``Xapian::ErrorHandler`` We feel the current ErrorHandler API doesn't work at the right level (it
225 only works in Enquire, whereas you should be able to handle errors at
226 the Database level too) and we can't find any evidence that people are
227 actually using it. So we've made the API a no-op and marked it as
228 deprecated. The hope is to replace it with something better thought
229 out, probably during the 1.4.x release series. There's some further
230 thoughts at https://trac.xapian.org/ticket/3#comment:8
231 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
232 1.3.2 1.5.0 ``Xapian::Auto::open_stub()`` Use the constructor with ``Xapian::DB_BACKEND_STUB`` flag (new in 1.3.2)
233 instead.
234 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
235 1.3.2 1.5.0 ``Xapian::Chert::open()`` Use the constructor with ``Xapian::DB_BACKEND_CHERT`` flag (new in
236 1.3.2) instead.
237 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
238 1.3.2 1.5.0 ``Xapian::Enquire::get_eset()`` Use ``Xapian::Enquire::set_expansion_scheme()`` to specify the algorithm
239 overloaded form taking ``k`` which ``get_eset()`` should use, along with any parameters (added in
240 parameter. 1.3.2).
241 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
242 1.3.3 1.5.0 |set_max_wildcard_expansion| Use ``Xapian::QueryParser::set_max_expansion()`` instead.
243 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
244 1.3.4 1.5.0 ``Xapian::Compactor`` methods Use the ``Xapian::Database::compact()`` method instead. The
245 ``set_block_size()``, ``Xapian::Compactor`` class is now just a subclassable functor class to
246 ``set_renumber()``, allow access to progress messages and control over merging of user
247 ``set_multipass()``, metadata.
248 ``set_compaction_level()``,
249 ``set_destdir()``, ``add_source()`
250 and ``compact()``.
251 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
252 1.3.5 1.5.0 ``Xapian::ValuePostingSource`` Use the respective getter and setter methods instead, added in 1.3.5 and
253 public member variables 1.2.23.
254 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
255 1.3.5 1.5.0 ``Xapian::InMemory::open()`` Use the constructor with ``Xapian::DB_BACKEND_INMEMORY`` flag (new in
256 1.3.5) instead.
257 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
258 1.3.6 1.5.0 |flush| Use ``Xapian::WritableDatabase::commit()`` instead (available since
259 1.1.0).
260 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
261 1.3.6 1.5.0 Subclassing |VRP| Subclass ``Xapian::RangeProcessor`` instead, and return a
262 ``Xapian::Query`` from ``operator()()`` (added in 1.3.6).
263 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
264 1.3.6 1.5.0 |DateVRP| Use ``Xapian::DateRangeProcessor`` instead (added in 1.3.6).
265 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
266 1.3.6 1.5.0 |NumberVRP| Use ``Xapian::NumberRangeProcessor`` instead (added in 1.3.6).
267 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
268 1.3.6 1.5.0 |StringVRP| Use ``Xapian::RangeProcessor`` instead, which includes equivalent
269 support for prefix/suffix checking (added in 1.3.6).
270 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
271 1.3.6 1.5.0 |add_valuerangeprocessor| Use ``Xapian::QueryParser::add_rangeprocessor()`` instead, with a
272 ``Xapian::RangeProcessor`` object instead of a |VRP| object (added in
273 1.3.6).
274 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
275 1.4.11 1.7.0 Environment variable Specify via the flags ``Xapian::QueryParser::FLAG_CJK_NGRAM``,
276 ``XAPIAN_CJK_NGRAM`` ``Xapian::TermGenerator::FLAG_CJK_NGRAM`` and
277 ``Xapian::MSet::SNIPPET_CJK_NGRAM`` instead.
278 ========== ====== =================================== ========================================================================
280 Bindings
281 --------
283 .. Keep table width to <= 126 columns.
285 ========== ====== ======== ============================ ======================================================================
286 Deprecated Remove Language Feature name Upgrade suggestion and comments
287 ========== ====== ======== ============================ ======================================================================
288 1.2.5 1.5.0 Python MSet.items Iterate the MSet object itself instead.
289 ---------- ------ -------- ---------------------------- ----------------------------------------------------------------------
290 1.2.5 1.5.0 Python ESet.items Iterate the ESet object itself instead.
291 ========== ====== ======== ============================ ======================================================================
293 Omega
294 -----
296 .. Keep table width to <= 126 columns.
298 ========== ====== =================================== ========================================================================
299 Deprecated Remove Feature name Upgrade suggestion and comments
300 ========== ====== =================================== ========================================================================
301 1.2.4 1.5.0 omindex command line long option Renamed to ``--no-delete``, which works in 1.2.4 and later.
302 ``--preserve-nonduplicates``.
303 ---------- ------ ----------------------------------- ------------------------------------------------------------------------
304 1.2.5 1.5.0 $set{spelling,true} Use $set{flag_spelling_suggestion,true} instead.
305 ========== ====== =================================== ========================================================================
307 .. Features currently marked as experimental
308 .. =========================================
309 .. Native C++ API
310 .. --------------
311 .. ============== ===============================================================================================================
312 .. Name Details
313 .. ============== ===============================================================================================================
314 .. -------------- ---------------------------------------------------------------------------------------------------------------
315 .. ============== ===============================================================================================================
317 Features removed from Xapian
318 ============================
320 Native C++ API
321 --------------
323 .. Keep table width to <= 126 columns.
325 ======= =================================== ==================================================================================
326 Removed Feature name Upgrade suggestion and comments
327 ======= =================================== ==================================================================================
328 1.0.0 QueryParser::set_stemming_options() Use ``set_stemmer()``, ``set_stemming_strategy()`` and/or ``set_stopper()``
329 instead:
331 - ``set_stemming_options("")`` becomes
332 ``set_stemming_strategy(Xapian::QueryParser::STEM_NONE)``
334 - ``set_stemming_options("none")`` becomes
335 ``set_stemming_strategy(Xapian::QueryParser::STEM_NONE)``
337 - ``set_stemming_options(LANG)`` becomes
338 ``set_stemmer(Xapian::Stem(LANG)`` and
339 ``set_stemming_strategy(Xapian::QueryParser::STEM_SOME)``
341 - ``set_stemming_options(LANG, false)`` becomes
342 ``set_stemmer(Xapian::Stem(LANG)`` and
343 ``set_stemming_strategy(Xapian::QueryParser::STEM_SOME)``
345 - ``set_stemming_options(LANG, true)`` becomes
346 ``set_stemmer(Xapian::Stem(LANG)`` and
347 ``set_stemming_strategy(Xapian::QueryParser::STEM_ALL)``
349 If a third parameter is passed, ``set_stopper(PARAM3)`` and treat the first two
350 parameters as above.
351 ------- ----------------------------------- ----------------------------------------------------------------------------------
352 1.0.0 Enquire::set_sort_forward() Use ``Enquire::set_docid_order()`` instead:
354 - ``set_sort_forward(true)`` becomes ``set_docid_order(ASCENDING)``
355 - ``set_sort_forward(false)`` becomes ``set_docid_order(DESCENDING)``
356 ------- ----------------------------------- ----------------------------------------------------------------------------------
357 1.0.0 Enquire::set_sorting() Use ``Enquire::set_sort_by_relevance()``, ``Enquire::set_sort_by_value()``, or
358 ``Enquire::set_sort_by_value_then_relevance()`` instead.
360 - ``set_sorting(KEY, 1)`` becomes ``set_sort_by_value(KEY)``
361 - ``set_sorting(KEY, 1, false)`` becomes ``set_sort_by_value(KEY)``
362 - ``set_sorting(KEY, 1, true)`` becomes ``set_sort_by_value_then_relevance(KEY)``
363 - ``set_sorting(ANYTHING, 0)`` becomes ``set_sort_by_relevance()``
364 - ``set_sorting(Xapian::BAD_VALUENO, ANYTHING)`` becomes
365 ``set_sort_by_relevance()``
366 ------- ----------------------------------- ----------------------------------------------------------------------------------
367 1.0.0 Stem::stem_word(word) Use ``Stem::operator()(word)`` instead.
368 ------- ----------------------------------- ----------------------------------------------------------------------------------
369 1.0.0 Auto::open(path) Use the ``Database(path)`` constructor instead.
370 ------- ----------------------------------- ----------------------------------------------------------------------------------
371 1.0.0 Auto::open(path, action) Use the ``WritableDatabase(path, action)`` constructor instead.
372 ------- ----------------------------------- ----------------------------------------------------------------------------------
373 1.0.0 Query::is_empty() Use ``Query::empty()`` instead.
374 ------- ----------------------------------- ----------------------------------------------------------------------------------
375 1.0.0 Document::add_term_nopos() Use ``Document::add_term()`` instead.
376 ------- ----------------------------------- ----------------------------------------------------------------------------------
377 1.0.0 Enquire::set_bias() Use ``PostingSource`` instead (new in 1.2).
378 ------- ----------------------------------- ----------------------------------------------------------------------------------
379 1.0.0 ExpandDecider::operator() Return type is now ``bool`` not ``int``.
380 ------- ----------------------------------- ----------------------------------------------------------------------------------
381 1.0.0 MatchDecider::operator() Return type is now ``bool`` not ``int``.
382 ------- ----------------------------------- ----------------------------------------------------------------------------------
383 1.0.0 Error::get_type() Return type is now ``const char *`` not ``std::string``. Most existing code
384 won't need changes, but if it does the simplest fix is to write
385 ``std::string(e.get_type())`` instead of ``e.get_type()``.
386 ------- ----------------------------------- ----------------------------------------------------------------------------------
387 1.0.0 <xapian/output.h> Use ``cout << obj.get_description();`` instead of ``cout << obj;``
388 ------- ----------------------------------- ----------------------------------------------------------------------------------
389 1.0.0 Several constructors marked Explicitly create the object type required, for example use
390 as explicit. ``Xapian::Enquire enq(Xapian::Database(path));`` instead of
391 ``Xapian::Enquire enq(path);``
392 ------- ----------------------------------- ----------------------------------------------------------------------------------
393 1.0.0 QueryParser::parse_query() throwing Catch ``Xapian::QueryParserError`` instead of ``const char *``, and call
394 ``const char *`` exception. ``get_msg()`` on the caught object. If you need to build with either version,
395 catch both (you'll need to compile the part which catches ``QueryParserError``
396 conditionally, since this exception isn't present in the 0.9 release series).
397 ------- ----------------------------------- ----------------------------------------------------------------------------------
398 1.1.0 xapian_version_string() Use ``version_string()`` instead.
399 ------- ----------------------------------- ----------------------------------------------------------------------------------
400 1.1.0 xapian_major_version() Use ``major_version()`` instead.
401 ------- ----------------------------------- ----------------------------------------------------------------------------------
402 1.1.0 xapian_minor_version() Use ``minor_version()`` instead.
403 ------- ----------------------------------- ----------------------------------------------------------------------------------
404 1.1.0 xapian_revision() Use ``revision()`` instead.
405 ------- ----------------------------------- ----------------------------------------------------------------------------------
406 1.1.0 Enquire::include_query_terms Use ``Enquire::INCLUDE_QUERY_TERMS`` instead.
407 ------- ----------------------------------- ----------------------------------------------------------------------------------
408 1.1.0 Enquire::use_exact_termfreq Use ``Enquire::USE_EXACT_TERMFREQ`` instead.
409 ------- ----------------------------------- ----------------------------------------------------------------------------------
410 1.1.0 Error::get_errno() Use ``Error::get_error_string()`` instead.
411 ------- ----------------------------------- ----------------------------------------------------------------------------------
412 1.1.0 Enquire::register_match_decider() This method didn't do anything, so just remove calls to it!
413 ------- ----------------------------------- ----------------------------------------------------------------------------------
414 1.1.0 Query::Query(Query::op, Query) This constructor isn't useful for any currently implemented
415 ``Query::op``.
416 ------- ----------------------------------- ----------------------------------------------------------------------------------
417 1.1.0 The Quartz backend Use the Chert backend instead.
418 ------- ----------------------------------- ----------------------------------------------------------------------------------
419 1.1.0 Quartz::open() Use ``Chert::open()`` instead.
420 ------- ----------------------------------- ----------------------------------------------------------------------------------
421 1.1.0 quartzcheck Use ``xapian-check`` instead.
422 ------- ----------------------------------- ----------------------------------------------------------------------------------
423 1.1.0 quartzcompact Use ``xapian-compact`` instead.
424 ------- ----------------------------------- ----------------------------------------------------------------------------------
425 1.1.0 quartzdump Use ``xapian-inspect`` instead.
426 ------- ----------------------------------- ----------------------------------------------------------------------------------
427 1.1.0 configure --enable-debug configure --enable-assertions
428 ------- ----------------------------------- ----------------------------------------------------------------------------------
429 1.1.0 configure --enable-debug=full configure --enable-assertions --enable-log
430 ------- ----------------------------------- ----------------------------------------------------------------------------------
431 1.1.0 configure --enable-debug=partial configure --enable-assertions=partial
432 ------- ----------------------------------- ----------------------------------------------------------------------------------
433 1.1.0 configure --enable-debug=profile configure --enable-log=profile
434 ------- ----------------------------------- ----------------------------------------------------------------------------------
435 1.1.0 configure --enable-debug-verbose configure --enable-log
436 ------- ----------------------------------- ----------------------------------------------------------------------------------
437 1.1.0 ``Database::positionlist_begin()`` This check is quite expensive, and often you don't care. If you
438 throwing ``RangeError`` if the do it's easy to check - just open a ``TermListIterator`` for the
439 term specified doesn't index the document and use ``skip_to()`` to check if the term is there.
440 document specified.
441 ------- ----------------------------------- ----------------------------------------------------------------------------------
442 1.1.0 ``Database::positionlist_begin()`` This check is quite expensive, and often you don't care. If you
443 throwing ``DocNotFoundError`` if do, it's easy to check - just call ``Database::get_document()`` with the
444 the document specified doesn't specified document ID.
445 exist.
446 ------- ----------------------------------- ----------------------------------------------------------------------------------
447 1.1.5 delve -k Accepted as an undocumented alias for -V since 0.9.10 for compatibility with 0.9.9
448 and earlier. Just use -V instead.
449 ------- ----------------------------------- ----------------------------------------------------------------------------------
450 1.3.0 The Flint backend Use the Chert backend instead.
451 ------- ----------------------------------- ----------------------------------------------------------------------------------
452 1.3.0 Flint::open() Use ``Chert::open()`` instead.
453 ------- ----------------------------------- ----------------------------------------------------------------------------------
454 1.3.0 xapian-chert-update Install Xapian 1.2.x (where x >= 5) to update chert databases from 1.1.3 and
455 earlier.
456 ------- ----------------------------------- ----------------------------------------------------------------------------------
457 1.3.0 Default second parameter to The parameter name was ``ascending`` and defaulted to ``true``. However
458 ``Enquire`` sorting functions. ascending=false gave what you'd expect the default sort order to be (and probably
459 think of as ascending) while ascending=true gave the reverse (descending) order.
460 For sanity, we renamed the parameter to ``reverse`` and deprecated the default
461 value. In the more distant future, we'll probably add a default again, but of
462 ``false`` instead.
464 The methods affected are:
465 ``Enquire::set_sort_by_value(Xapian::valueno sort_key)``
466 ``Enquire::set_sort_by_key(Xapian::Sorter * sorter)``
467 ``Enquire::set_sort_by_value_then_relevance(Xapian::valueno sort_key)``
468 ``Enquire::set_sort_by_key_then_relevance(Xapian::Sorter * sorter)``
469 ``Enquire::set_sort_by_relevance_then_value(Xapian::valueno sort_key)``
470 ``Enquire::set_sort_by_relevance_then_key(Xapian::Sorter * sorter)``
472 To update them, just add a second parameter with value ``true`` to each of the
473 above calls. For the methods which take a ``Xapian::Sorter`` object, you'll also
474 need to migrate to ``Xapian::KeyMaker`` (see below).
475 ------- ----------------------------------- ----------------------------------------------------------------------------------
476 1.3.0 ``Sorter`` abstract base class. Use ``KeyMaker`` class instead, which has the same semantics, but has been renamed
477 to indicate that the keys produced may be used for purposes other than sorting (we
478 plan to allow collapsing on generated keys in the future).
479 ------- ----------------------------------- ----------------------------------------------------------------------------------
480 1.3.0 ``MultiValueSorter`` class. Use ``MultiValueKeyMaker`` class instead. Note that ``MultiValueSorter::add()``
481 becomes ``MultiValueKeyMaker::add_value()``, but the sense of the direction flag
482 is reversed (to be consistent with ``Enquire::set_sort_by_value()``), so::
484 MultiValueSorter sorter;
485 // Primary ordering is forwards on value 4.
486 sorter.add(4);
487 // Secondary ordering is reverse on value 5.
488 sorter.add(5, false);
490 becomes::
492 MultiValueKeyMaker sorter;
493 // Primary ordering is forwards on value 4.
494 sorter.add_value(4);
495 // Secondary ordering is reverse on value 5.
496 sorter.add_value(5, true);
497 ------- ----------------------------------- ----------------------------------------------------------------------------------
498 1.3.0 ``matchspy`` parameter to Use the newer ``MatchSpy`` class and ``Enquire::add_matchspy()`` method instead.
499 ``Enquire::get_mset()``
500 ------- ----------------------------------- ----------------------------------------------------------------------------------
501 1.3.0 ``Xapian::Query::unserialise()`` To be compatible with older and newer Xapian, you can catch both exceptions.
502 throws
503 ``Xapian::SerialisationError`` not
504 ``Xapian::InvalidArgumentError``
505 for errors in serialised data
506 ------- ----------------------------------- ----------------------------------------------------------------------------------
507 1.3.2 The Brass backend Use the Glass backend instead.
508 ------- ----------------------------------- ----------------------------------------------------------------------------------
509 1.3.2 ``Xapian::Brass::open()`` Use the constructor with ``Xapian::DB_BACKEND_GLASS`` flag (new in 1.3.2) instead.
510 ------- ----------------------------------- ----------------------------------------------------------------------------------
511 1.3.4 Copy constructors and assignment We think it was a mistake that implicit copy constructors and assignment operators
512 operators for classes: were being provided for these functor classes - it's hard to use them correctly,
513 ``Xapian::ExpandDecider``, but easy to use them in ways which compile but don't work correctly, and we doubt
514 ``Xapian::FieldProcessor`` (new in anyone is intentionally using them, so we've simply removed them. For more
515 1.3.1), ``Xapian::KeyMaker``, information, see https://trac.xapian.org/ticket/681
516 ``Xapian::MatchDecider``,
517 ``Xapian::StemImplementation``,
518 ``Xapian::Stopper`` and
519 ``Xapian::ValueRangeProcessor``.
520 ------- ----------------------------------- ----------------------------------------------------------------------------------
521 1.3.5 ``Xapian::DBCHECK_SHOW_BITMAP`` Use ``Xapian::DBCHECK_SHOW_FREELIST`` (added in 1.3.2) instead.
522 ``Xapian::DBCHECK_SHOW_BITMAP`` was added in 1.3.0, so has never been in a stable
523 release.
524 ======= =================================== ==================================================================================
527 Bindings
528 --------
530 .. Keep table width to <= 126 columns.
532 ======= ======== ============================ ================================================================================
533 Removed Language Feature name Upgrade suggestion and comments
534 ======= ======== ============================ ================================================================================
535 1.0.0 SWIG Enquire::set_sort_forward() Use ``Enquire::set_docid_order()`` instead.
536 [#rswg]_
537 - ``set_sort_forward(true)`` becomes ``set_docid_order(ASCENDING)``
538 - ``set_sort_forward(false)`` becomes ``set_docid_order(DESCENDING)``
539 ------- -------- ---------------------------- --------------------------------------------------------------------------------
540 1.0.0 SWIG Enquire::set_sorting() Use ``Enquire::set_sort_by_relevance()``, ``Enquire::set_sort_by_value()``
541 [#rswg]_ or ``Enquire::set_sort_by_value_then_relevance()`` instead.
543 - ``set_sorting(KEY, 1)`` becomes ``set_sort_by_value(KEY)``
544 - ``set_sorting(KEY, 1, false) becomes ``set_sort_by_value(KEY)``
545 - ``set_sorting(KEY, 1, true)`` becomes
546 ``set_sort_by_value_then_relevance(KEY)``
547 - ``set_sorting(ANYTHING, 0) becomes set_sort_by_relevance()``
548 - ``set_sorting(Xapian::BAD_VALUENO, ANYTHING)`` becomes
549 ``set_sort_by_relevance()``
550 ------- -------- ---------------------------- --------------------------------------------------------------------------------
551 1.0.0 SWIG Auto::open(path) Use the ``Database(path)`` constructor instead.
552 [#rswg]_
554 ------- -------- ---------------------------- --------------------------------------------------------------------------------
555 1.0.0 SWIG Auto::open(path, action) Use the ``WritableDatabase(path, action)`` constructor instead.
556 [#rswg]_
557 ------- -------- ---------------------------- --------------------------------------------------------------------------------
558 1.0.0 SWIG MSet::is_empty() Use ``MSet::empty()`` instead.
559 [#rsw3]_
560 ------- -------- ---------------------------- --------------------------------------------------------------------------------
561 1.0.0 SWIG ESet::is_empty() Use ``ESet::empty()`` instead.
562 [#rsw3]_
563 ------- -------- ---------------------------- --------------------------------------------------------------------------------
564 1.0.0 SWIG RSet::is_empty() Use ``RSet::empty()`` instead.
565 [#rsw3]_
566 ------- -------- ---------------------------- --------------------------------------------------------------------------------
567 1.0.0 SWIG Query::is_empty() Use ``Query::empty()`` instead.
568 [#rsw3]_
569 ------- -------- ---------------------------- --------------------------------------------------------------------------------
570 1.0.0 SWIG Document::add_term_nopos() Use ``Document::add_term()`` instead.
571 [#rswg]_
572 ------- -------- ---------------------------- --------------------------------------------------------------------------------
573 1.0.0 CSharp ExpandDecider::Apply() Return type is now ``bool`` instead of ``int``.
574 ------- -------- ---------------------------- --------------------------------------------------------------------------------
575 1.0.0 CSharp MatchDecider::Apply() Return type is now ``bool`` instead of ``int``.
576 ------- -------- ---------------------------- --------------------------------------------------------------------------------
577 1.0.0 SWIG Stem::stem_word(word) Use ``Stem::operator()(word)`` instead. [#callable]_
578 [#rswg]_
579 ------- -------- ---------------------------- --------------------------------------------------------------------------------
580 1.1.0 SWIG xapian_version_string() Use ``version_string()`` instead.
581 [#rswg]_
582 ------- -------- ---------------------------- --------------------------------------------------------------------------------
583 1.1.0 SWIG xapian_major_version() Use ``major_version()`` instead.
584 [#rswg]_
585 ------- -------- ---------------------------- --------------------------------------------------------------------------------
586 1.1.0 SWIG xapian_minor_version() Use ``minor_version()`` instead.
587 [#rswg]_
588 ------- -------- ---------------------------- --------------------------------------------------------------------------------
589 1.1.0 SWIG xapian_revision() Use ``revision()`` instead.
590 [#rswg]_
591 ------- -------- ---------------------------- --------------------------------------------------------------------------------
592 1.1.0 SWIG ESetIterator::get_termname() Use ``ESetIterator::get_term()`` instead. This change is intended to
593 [#rswg]_ bring the ESet iterators in line with other term iterators, which all
594 support ``get_term()`` instead of ``get_termname()``.
596 ------- -------- ---------------------------- --------------------------------------------------------------------------------
597 1.1.0 Python get_description() All ``get_description()`` methods have been renamed to ``__str__()``,
598 so the normal python ``str()`` function can be used.
599 ------- -------- ---------------------------- --------------------------------------------------------------------------------
600 1.1.0 Python MSetItem.get_*() All these methods are deprecated, in favour of properties.
601 To convert, just change ``msetitem.get_FOO()`` to ``msetitem.FOO``
602 ------- -------- ---------------------------- --------------------------------------------------------------------------------
603 1.1.0 Python Enquire.get_matching_terms Replaced by ``Enquire.matching_terms``, for consistency with
604 rest of Python API. Note: an ``Enquire.get_matching_terms`` method existed in
605 releases up-to and including 1.2.4, but this was actually an old implementation
606 which only accepted a MSetIterator as a parameter, and would have failed with
607 code written expecting the version in 1.0.0. It was fully removed after
608 release 1.2.4.
609 ------- -------- ---------------------------- --------------------------------------------------------------------------------
610 1.1.0 SWIG Error::get_errno() Use ``Error::get_error_string()`` instead.
611 [#rswg]_
612 ------- -------- ---------------------------- --------------------------------------------------------------------------------
613 1.1.0 SWIG MSet::get_document_id() Use ``MSet::get_docid()`` instead.
614 [#rsw2]_
615 ------- -------- ---------------------------- --------------------------------------------------------------------------------
616 1.2.0 Python mset[i][xapian.MSET_DID] etc This was inadvertently removed in 1.2.0, but not noticed until 1.2.5, by which
617 point it no longer seemed worthwhile to reinstate it. Please use the property
618 API instead, e.g. ``mset[i].docid``, ``mset[i].weight``, etc.
619 ------- -------- ---------------------------- --------------------------------------------------------------------------------
620 1.2.5 Python if idx in mset This was nominally implemented, but never actually worked. Since nobody seems
621 to have noticed in 3.5 years, we just removed it. If you have uses (which were
622 presumably never called), you can replace them with:
623 ``if idx >= 0 and idx < len(mset)``
624 ------- -------- ---------------------------- --------------------------------------------------------------------------------
625 1.3.0 Python Non-pythonic iterators Use the pythonic iterators instead.
626 ------- -------- ---------------------------- --------------------------------------------------------------------------------
627 1.3.0 Python Stem_get_available_languages Use Stem.get_available_languages instead (static method instead of function)
628 ======= ======== ============================ ================================================================================
630 .. [#rswg] This affects all SWIG generated bindings (currently: Python, PHP, Ruby, Tcl8 and CSharp)
632 .. [#rsw2] This affects all SWIG-generated bindings except those for Ruby, support for which was added after the function was deprecated in Xapian-core.
634 .. [#rsw3] 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").
636 .. [#callable] 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.
638 Omega
639 -----
641 .. Keep table width to <= 126 columns.
643 ======= =================================== ==================================================================================
644 Removed Feature name Upgrade suggestion and comments
645 ======= =================================== ==================================================================================
646 1.0.0 $freqs Use ``$map{$queryterms,$_: $nice{$freq{$_}}}`` instead.
647 ------- ----------------------------------- ----------------------------------------------------------------------------------
648 1.0.0 scriptindex -u ``-u`` was ignored for compatibility with 0.7.5 and earlier, so just remove it.
649 ------- ----------------------------------- ----------------------------------------------------------------------------------
650 1.0.0 scriptindex -q ``-q`` was ignored for compatibility with 0.6.1 and earlier, so just remove it.
651 ------- ----------------------------------- ----------------------------------------------------------------------------------
652 1.1.0 scriptindex index=nopos Use ``indexnopos`` instead.
653 ------- ----------------------------------- ----------------------------------------------------------------------------------
654 1.3.0 ``OLDP`` CGI parameter Use ``xP`` CGI parameter instead (direct replacement), which has been supported
655 since at least 0.5.0.
656 ======= =================================== ==================================================================================