1 2.. This document was originally written by Richard Boulton. 3 4.. Copyright (C) 2007 Lemur Consulting Ltd 5.. Copyright (C) 2007,2008,2009,2010,2011,2012,2013,2015,2016 Olly Betts 6 7=========== 8Deprecation 9=========== 10 11.. contents:: Table of contents 12 13Introduction 14============ 15 16Xapian's API is fairly stable and has been polished piece by piece over time, 17but it still occasionally needs to be changed. This may be because a new 18feature has been implemented and the interface needs to allow access to it, but 19it may also be required in order to polish a rough edge which has been missed 20in earlier versions of Xapian, or simply to reflect an internal change which 21requires a modification to the external interface. 22 23We aim to make such changes in a way that allows developers to work against a 24stable API, while avoiding the need for the Xapian developers to maintain too 25many old historical interface artefacts. This document describes the process 26we use to deprecate old pieces of the API, lists parts of the API which are 27currently marked as deprecated, and also describes parts of the API which have 28been deprecated for some time, and are now removed from the Xapian library. 29 30It is possible for functions, methods, constants, types or even whole classes 31to 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. 33 34 35Deprecation Procedure 36===================== 37 38Deprecation markers 39------------------- 40 41At 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 43such as ``XAPIAN_DEPRECATED()``, which will cause compilers with appropriate 44support (such as GCC, clang and MSVC) to emit compile-time warnings if these 45features are used. 46 47If a feature is marked with one of these markers, you should avoid using it in 48new code, and should migrate your code to use a replacement when possible. The 49documentation comments for the feature, or the list at the end 50of this file, will describe possible alternatives to the deprecated feature. 51 52If you want to disable deprecation warnings temporarily, you can do so 53by passing ``"-DXAPIAN_DEPRECATED(X)=X"`` to the compiler (the quotes are 54needed to protect the brackets from the shell). If your build system uses 55make, you might do this like so: 56 57.. code-block:: sh 58 59 make 'CPPFLAGS="-DXAPIAN_DEPRECATED(X)=X"' 60 61API and ABI compatibility 62------------------------- 63 64Releases are given three-part version numbers (e.g. 1.2.9), the three parts 65being termed "major" (1), "minor" (2), and "revision" (9). Releases with 66the same major and minor version are termed a "release series". 67 68For Xapian releases 1.0.0 and higher, an even minor version indicates a stable 69release series, while an odd minor version indicates a development release 70series. 71 72Within a stable release series, we strive to maintain API and ABI forwards 73compatibility. This means that an application written and compiled against 74version `X.Y.a` of Xapian should work, without any source changes or need to 75recompile, with a later version `X.Y.b`, for all `b` >= `a`. 76Stable releases which increase the minor or major version number will usually 77change the ABI incompatibly (so that code will need to be recompiled against 78the newer release series. They may also make incompatible API changes, 79though we will attempt to do this in a way which makes it reasonably easy to 80migrate applications, and document how to do so in this document. 81 82It is possible that a feature may be marked as deprecated within a minor 83release series - that is from version `X.Y.c` 84onwards, where `c` is not zero. The API and ABI will not be changed by this 85deprecation, since the feature will still be available in the API (though the 86change may cause the compiler to emit new warnings when rebuilding code 87which uses the now-deprecated feature). 88 89Users should generally be able to expect working code which uses Xapian not to 90stop working without reason. We attempt to codify this in the following 91policy, but we reserve the right not to slavishly follow this. The spirit of 92the rule should kept in mind - for example if we discovered a feature which 93didn't actually work, making an incompatible API change at the next ABI bump 94would be reasonable. 95 96Normally a feature will be supported after being deprecated for an entire 97stable release series. For example, if a feature is deprecated in release 981.2.0, it will be supported for the entire 1.2.x release series, and removed in 99development release 1.3.0. If a feature is deprecated in release 1.2.1, it 100will be supported for the 1.2.x *and* 1.4.x stable release series (and of 101course the 1.3.x release series in between), and won't be removed until 1021.5.0. 103 104Experimental features 105--------------------- 106 107During a development release series (such as the 1.1.x series), some features 108may be marked as "experimental". Such features are liable to change without 109going through the normal deprecation procedure. This includes changing on-disk 110formats for data stored by the feature, and breaking API and ABI compatibility 111between releases for the feature. Such features are included in releases to 112get wider use and corresponding feedback about them. 113 114Deprecation in the bindings 115--------------------------- 116 117When the Xapian API changes, the interface provided by the Xapian bindings will 118usually change in step. In addition, it is sometimes necessary to change the 119way in which Xapian is wrapped by bindings - for example, to provide a better 120convenience wrapper for iterators in Python. Again, we aim to ensure that an 121application written (and compiled, if the language being bound is a compiled 122language) for version `X.Y.a` of Xapian should work without any changes or need 123to recompile, with a later version `X.Y.b`, for all `a` <= `b`. 124 125However, the bindings are a little less mature than the core C++ API, so we 126don't intend to give the same guarantee that a feature present and not 127deprecated in version `X.Y.a` will work in all versions `X+1.Y.b`. In other 128words, we may remove features which have been deprecated without waiting for 129an entire release series to pass. 130 131Any planned deprecations will be documented in the list of deprecations and 132removed features at the end of this file. 133 134Support for Other Software 135========================== 136 137Support for other software doesn't follow the same deprecation rules as 138for API features. 139 140Our guiding principle for supporting version of other software is that 141we don't aim to actively support versions which are no longer supported 142"upstream". 143 144So Xapian 1.1.0 doesn't support PHP4 because the PHP team no longer did 145when it was released. By the API deprecation rules we should have announced 146this when Xapian 1.0.0 was released, but we don't have control over when and 147to what timescales other software providers discontinue support for older 148versions. 149 150Sometimes we can support such versions without extra effort (e.g. Tcl's 151stubs mechanism means Tcl 8.1 probably still works, even though the last 1528.1.x release was over a decade ago), and in some cases Linux distros 153continue to support software after upstream stops. 154 155But in most cases keeping support around is a maintenance overhead and 156we'd rather spend our time on more useful things. 157 158Note that there's no guarantee that we will support and continue to 159support versions just because upstream still does. For example, we ceased 160providing backported packages for Ubuntu dapper with Xapian 1.1.0 - in this 161case, it's because we felt that if you're conservative enough to run dapper, 162you'd probably prefer to stick with 1.0.x until you upgrade to hardy (the next 163Ubuntu LTS release). But we may decide not to support versions for other 164reasons too. 165 166How to avoid using deprecated features 167====================================== 168 169We recommend taking the following steps to avoid depending on deprecated 170features when writing your applications: 171 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. 176 177 - Check the NEWS file for each new release for details of any new features 178 which are deprecated in the release. 179 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. 184 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. 193 194 195Features currently marked for deprecation 196========================================= 197 198Native C++ API 199-------------- 200 201.. Substitution definitions for feature names which are two wide for the column: 202 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()`` 210 211.. Keep table width to <= 126 columns. 212 213========== ====== =================================== ======================================================================== 214Deprecated Remove Feature name Upgrade suggestion and comments 215========== ====== =================================== ======================================================================== 2161.3.0 1.5.0 ``Xapian::timeout`` typedef Use ``unsigned`` instead, which should also work with older Xapian 217 releases. 218---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2191.3.0 1.5.0 ``Xapian::percent`` typedef Use ``int`` instead, which should also work with older Xapian releases. 220---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2211.3.0 1.5.0 ``Xapian::weight`` typedef Use ``double`` instead, which should also work with older Xapian 222 releases. 223---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2241.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---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2321.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---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2351.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---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2381.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---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2421.3.3 1.5.0 |set_max_wildcard_expansion| Use ``Xapian::QueryParser::set_max_expansion()`` instead. 243---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2441.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---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2521.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---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2551.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---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2581.3.6 1.5.0 |flush| Use ``Xapian::WritableDatabase::commit()`` instead (available since 259 1.1.0). 260---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2611.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---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2641.3.6 1.5.0 |DateVRP| Use ``Xapian::DateRangeProcessor`` instead (added in 1.3.6). 265---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2661.3.6 1.5.0 |NumberVRP| Use ``Xapian::NumberRangeProcessor`` instead (added in 1.3.6). 267---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2681.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---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2711.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---------- ------ ----------------------------------- ------------------------------------------------------------------------ 2751.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========== ====== =================================== ======================================================================== 279 280Bindings 281-------- 282 283.. Keep table width to <= 126 columns. 284 285========== ====== ======== ============================ ====================================================================== 286Deprecated Remove Language Feature name Upgrade suggestion and comments 287========== ====== ======== ============================ ====================================================================== 2881.2.5 1.5.0 Python MSet.items Iterate the MSet object itself instead. 289---------- ------ -------- ---------------------------- ---------------------------------------------------------------------- 2901.2.5 1.5.0 Python ESet.items Iterate the ESet object itself instead. 291========== ====== ======== ============================ ====================================================================== 292 293Omega 294----- 295 296.. Keep table width to <= 126 columns. 297 298========== ====== =================================== ======================================================================== 299Deprecated Remove Feature name Upgrade suggestion and comments 300========== ====== =================================== ======================================================================== 3011.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---------- ------ ----------------------------------- ------------------------------------------------------------------------ 3041.2.5 1.5.0 $set{spelling,true} Use $set{flag_spelling_suggestion,true} instead. 305========== ====== =================================== ======================================================================== 306 307.. Features currently marked as experimental 308.. ========================================= 309.. Native C++ API 310.. -------------- 311.. ============== =============================================================================================================== 312.. Name Details 313.. ============== =============================================================================================================== 314.. -------------- --------------------------------------------------------------------------------------------------------------- 315.. ============== =============================================================================================================== 316 317Features removed from Xapian 318============================ 319 320Native C++ API 321-------------- 322 323.. Keep table width to <= 126 columns. 324 325======= =================================== ================================================================================== 326Removed Feature name Upgrade suggestion and comments 327======= =================================== ================================================================================== 3281.0.0 QueryParser::set_stemming_options() Use ``set_stemmer()``, ``set_stemming_strategy()`` and/or ``set_stopper()`` 329 instead: 330 331 - ``set_stemming_options("")`` becomes 332 ``set_stemming_strategy(Xapian::QueryParser::STEM_NONE)`` 333 334 - ``set_stemming_options("none")`` becomes 335 ``set_stemming_strategy(Xapian::QueryParser::STEM_NONE)`` 336 337 - ``set_stemming_options(LANG)`` becomes 338 ``set_stemmer(Xapian::Stem(LANG)`` and 339 ``set_stemming_strategy(Xapian::QueryParser::STEM_SOME)`` 340 341 - ``set_stemming_options(LANG, false)`` becomes 342 ``set_stemmer(Xapian::Stem(LANG)`` and 343 ``set_stemming_strategy(Xapian::QueryParser::STEM_SOME)`` 344 345 - ``set_stemming_options(LANG, true)`` becomes 346 ``set_stemmer(Xapian::Stem(LANG)`` and 347 ``set_stemming_strategy(Xapian::QueryParser::STEM_ALL)`` 348 349 If a third parameter is passed, ``set_stopper(PARAM3)`` and treat the first two 350 parameters as above. 351------- ----------------------------------- ---------------------------------------------------------------------------------- 3521.0.0 Enquire::set_sort_forward() Use ``Enquire::set_docid_order()`` instead: 353 354 - ``set_sort_forward(true)`` becomes ``set_docid_order(ASCENDING)`` 355 - ``set_sort_forward(false)`` becomes ``set_docid_order(DESCENDING)`` 356------- ----------------------------------- ---------------------------------------------------------------------------------- 3571.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. 359 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------- ----------------------------------- ---------------------------------------------------------------------------------- 3671.0.0 Stem::stem_word(word) Use ``Stem::operator()(word)`` instead. 368------- ----------------------------------- ---------------------------------------------------------------------------------- 3691.0.0 Auto::open(path) Use the ``Database(path)`` constructor instead. 370------- ----------------------------------- ---------------------------------------------------------------------------------- 3711.0.0 Auto::open(path, action) Use the ``WritableDatabase(path, action)`` constructor instead. 372------- ----------------------------------- ---------------------------------------------------------------------------------- 3731.0.0 Query::is_empty() Use ``Query::empty()`` instead. 374------- ----------------------------------- ---------------------------------------------------------------------------------- 3751.0.0 Document::add_term_nopos() Use ``Document::add_term()`` instead. 376------- ----------------------------------- ---------------------------------------------------------------------------------- 3771.0.0 Enquire::set_bias() Use ``PostingSource`` instead (new in 1.2). 378------- ----------------------------------- ---------------------------------------------------------------------------------- 3791.0.0 ExpandDecider::operator() Return type is now ``bool`` not ``int``. 380------- ----------------------------------- ---------------------------------------------------------------------------------- 3811.0.0 MatchDecider::operator() Return type is now ``bool`` not ``int``. 382------- ----------------------------------- ---------------------------------------------------------------------------------- 3831.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------- ----------------------------------- ---------------------------------------------------------------------------------- 3871.0.0 <xapian/output.h> Use ``cout << obj.get_description();`` instead of ``cout << obj;`` 388------- ----------------------------------- ---------------------------------------------------------------------------------- 3891.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------- ----------------------------------- ---------------------------------------------------------------------------------- 3931.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------- ----------------------------------- ---------------------------------------------------------------------------------- 3981.1.0 xapian_version_string() Use ``version_string()`` instead. 399------- ----------------------------------- ---------------------------------------------------------------------------------- 4001.1.0 xapian_major_version() Use ``major_version()`` instead. 401------- ----------------------------------- ---------------------------------------------------------------------------------- 4021.1.0 xapian_minor_version() Use ``minor_version()`` instead. 403------- ----------------------------------- ---------------------------------------------------------------------------------- 4041.1.0 xapian_revision() Use ``revision()`` instead. 405------- ----------------------------------- ---------------------------------------------------------------------------------- 4061.1.0 Enquire::include_query_terms Use ``Enquire::INCLUDE_QUERY_TERMS`` instead. 407------- ----------------------------------- ---------------------------------------------------------------------------------- 4081.1.0 Enquire::use_exact_termfreq Use ``Enquire::USE_EXACT_TERMFREQ`` instead. 409------- ----------------------------------- ---------------------------------------------------------------------------------- 4101.1.0 Error::get_errno() Use ``Error::get_error_string()`` instead. 411------- ----------------------------------- ---------------------------------------------------------------------------------- 4121.1.0 Enquire::register_match_decider() This method didn't do anything, so just remove calls to it! 413------- ----------------------------------- ---------------------------------------------------------------------------------- 4141.1.0 Query::Query(Query::op, Query) This constructor isn't useful for any currently implemented 415 ``Query::op``. 416------- ----------------------------------- ---------------------------------------------------------------------------------- 4171.1.0 The Quartz backend Use the Chert backend instead. 418------- ----------------------------------- ---------------------------------------------------------------------------------- 4191.1.0 Quartz::open() Use ``Chert::open()`` instead. 420------- ----------------------------------- ---------------------------------------------------------------------------------- 4211.1.0 quartzcheck Use ``xapian-check`` instead. 422------- ----------------------------------- ---------------------------------------------------------------------------------- 4231.1.0 quartzcompact Use ``xapian-compact`` instead. 424------- ----------------------------------- ---------------------------------------------------------------------------------- 4251.1.0 quartzdump Use ``xapian-inspect`` instead. 426------- ----------------------------------- ---------------------------------------------------------------------------------- 4271.1.0 configure --enable-debug configure --enable-assertions 428------- ----------------------------------- ---------------------------------------------------------------------------------- 4291.1.0 configure --enable-debug=full configure --enable-assertions --enable-log 430------- ----------------------------------- ---------------------------------------------------------------------------------- 4311.1.0 configure --enable-debug=partial configure --enable-assertions=partial 432------- ----------------------------------- ---------------------------------------------------------------------------------- 4331.1.0 configure --enable-debug=profile configure --enable-log=profile 434------- ----------------------------------- ---------------------------------------------------------------------------------- 4351.1.0 configure --enable-debug-verbose configure --enable-log 436------- ----------------------------------- ---------------------------------------------------------------------------------- 4371.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------- ----------------------------------- ---------------------------------------------------------------------------------- 4421.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------- ----------------------------------- ---------------------------------------------------------------------------------- 4471.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------- ----------------------------------- ---------------------------------------------------------------------------------- 4501.3.0 The Flint backend Use the Chert backend instead. 451------- ----------------------------------- ---------------------------------------------------------------------------------- 4521.3.0 Flint::open() Use ``Chert::open()`` instead. 453------- ----------------------------------- ---------------------------------------------------------------------------------- 4541.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------- ----------------------------------- ---------------------------------------------------------------------------------- 4571.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. 463 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)`` 471 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------- ----------------------------------- ---------------------------------------------------------------------------------- 4761.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------- ----------------------------------- ---------------------------------------------------------------------------------- 4801.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:: 483 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); 489 490 becomes:: 491 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------- ----------------------------------- ---------------------------------------------------------------------------------- 4981.3.0 ``matchspy`` parameter to Use the newer ``MatchSpy`` class and ``Enquire::add_matchspy()`` method instead. 499 ``Enquire::get_mset()`` 500------- ----------------------------------- ---------------------------------------------------------------------------------- 5011.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------- ----------------------------------- ---------------------------------------------------------------------------------- 5071.3.2 The Brass backend Use the Glass backend instead. 508------- ----------------------------------- ---------------------------------------------------------------------------------- 5091.3.2 ``Xapian::Brass::open()`` Use the constructor with ``Xapian::DB_BACKEND_GLASS`` flag (new in 1.3.2) instead. 510------- ----------------------------------- ---------------------------------------------------------------------------------- 5111.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------- ----------------------------------- ---------------------------------------------------------------------------------- 5211.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======= =================================== ================================================================================== 525 526 527Bindings 528-------- 529 530.. Keep table width to <= 126 columns. 531 532======= ======== ============================ ================================================================================ 533Removed Language Feature name Upgrade suggestion and comments 534======= ======== ============================ ================================================================================ 5351.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------- -------- ---------------------------- -------------------------------------------------------------------------------- 5401.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. 542 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------- -------- ---------------------------- -------------------------------------------------------------------------------- 5511.0.0 SWIG Auto::open(path) Use the ``Database(path)`` constructor instead. 552 [#rswg]_ 553 554------- -------- ---------------------------- -------------------------------------------------------------------------------- 5551.0.0 SWIG Auto::open(path, action) Use the ``WritableDatabase(path, action)`` constructor instead. 556 [#rswg]_ 557------- -------- ---------------------------- -------------------------------------------------------------------------------- 5581.0.0 SWIG MSet::is_empty() Use ``MSet::empty()`` instead. 559 [#rsw3]_ 560------- -------- ---------------------------- -------------------------------------------------------------------------------- 5611.0.0 SWIG ESet::is_empty() Use ``ESet::empty()`` instead. 562 [#rsw3]_ 563------- -------- ---------------------------- -------------------------------------------------------------------------------- 5641.0.0 SWIG RSet::is_empty() Use ``RSet::empty()`` instead. 565 [#rsw3]_ 566------- -------- ---------------------------- -------------------------------------------------------------------------------- 5671.0.0 SWIG Query::is_empty() Use ``Query::empty()`` instead. 568 [#rsw3]_ 569------- -------- ---------------------------- -------------------------------------------------------------------------------- 5701.0.0 SWIG Document::add_term_nopos() Use ``Document::add_term()`` instead. 571 [#rswg]_ 572------- -------- ---------------------------- -------------------------------------------------------------------------------- 5731.0.0 CSharp ExpandDecider::Apply() Return type is now ``bool`` instead of ``int``. 574------- -------- ---------------------------- -------------------------------------------------------------------------------- 5751.0.0 CSharp MatchDecider::Apply() Return type is now ``bool`` instead of ``int``. 576------- -------- ---------------------------- -------------------------------------------------------------------------------- 5771.0.0 SWIG Stem::stem_word(word) Use ``Stem::operator()(word)`` instead. [#callable]_ 578 [#rswg]_ 579------- -------- ---------------------------- -------------------------------------------------------------------------------- 5801.1.0 SWIG xapian_version_string() Use ``version_string()`` instead. 581 [#rswg]_ 582------- -------- ---------------------------- -------------------------------------------------------------------------------- 5831.1.0 SWIG xapian_major_version() Use ``major_version()`` instead. 584 [#rswg]_ 585------- -------- ---------------------------- -------------------------------------------------------------------------------- 5861.1.0 SWIG xapian_minor_version() Use ``minor_version()`` instead. 587 [#rswg]_ 588------- -------- ---------------------------- -------------------------------------------------------------------------------- 5891.1.0 SWIG xapian_revision() Use ``revision()`` instead. 590 [#rswg]_ 591------- -------- ---------------------------- -------------------------------------------------------------------------------- 5921.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()``. 595 596------- -------- ---------------------------- -------------------------------------------------------------------------------- 5971.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------- -------- ---------------------------- -------------------------------------------------------------------------------- 6001.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------- -------- ---------------------------- -------------------------------------------------------------------------------- 6031.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------- -------- ---------------------------- -------------------------------------------------------------------------------- 6101.1.0 SWIG Error::get_errno() Use ``Error::get_error_string()`` instead. 611 [#rswg]_ 612------- -------- ---------------------------- -------------------------------------------------------------------------------- 6131.1.0 SWIG MSet::get_document_id() Use ``MSet::get_docid()`` instead. 614 [#rsw2]_ 615------- -------- ---------------------------- -------------------------------------------------------------------------------- 6161.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------- -------- ---------------------------- -------------------------------------------------------------------------------- 6201.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------- -------- ---------------------------- -------------------------------------------------------------------------------- 6251.3.0 Python Non-pythonic iterators Use the pythonic iterators instead. 626------- -------- ---------------------------- -------------------------------------------------------------------------------- 6271.3.0 Python Stem_get_available_languages Use Stem.get_available_languages instead (static method instead of function) 628======= ======== ============================ ================================================================================ 629 630.. [#rswg] This affects all SWIG generated bindings (currently: Python, PHP, Ruby, Tcl8 and CSharp) 631 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. 633 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"). 635 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. 637 638Omega 639----- 640 641.. Keep table width to <= 126 columns. 642 643======= =================================== ================================================================================== 644Removed Feature name Upgrade suggestion and comments 645======= =================================== ================================================================================== 6461.0.0 $freqs Use ``$map{$queryterms,$_: $nice{$freq{$_}}}`` instead. 647------- ----------------------------------- ---------------------------------------------------------------------------------- 6481.0.0 scriptindex -u ``-u`` was ignored for compatibility with 0.7.5 and earlier, so just remove it. 649------- ----------------------------------- ---------------------------------------------------------------------------------- 6501.0.0 scriptindex -q ``-q`` was ignored for compatibility with 0.6.1 and earlier, so just remove it. 651------- ----------------------------------- ---------------------------------------------------------------------------------- 6521.1.0 scriptindex index=nopos Use ``indexnopos`` instead. 653------- ----------------------------------- ---------------------------------------------------------------------------------- 6541.3.0 ``OLDP`` CGI parameter Use ``xP`` CGI parameter instead (direct replacement), which has been supported 655 since at least 0.5.0. 656======= =================================== ================================================================================== 657