/* * Copyright 2004 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ using System; namespace Lucene.Net.Search { /// Encapsulates sort criteria for returned hits. /// ///

The fields used to determine sort order must be carefully chosen. /// Documents must contain a single term in such a Field, /// and the value of the term should indicate the document's relative position in /// a given sort order. The Field must be indexed, but should not be tokenized, /// and does not need to be stored (unless you happen to want it back with the /// rest of your document data). In other words: /// ///

document.add (new Field ("byNumber", Integer.toString(x), Field.Store.NO, Field.Index.UN_TOKENIZED));

/// /// ///

Valid Types of Values

/// ///

There are three possible kinds of term values which may be put into /// sorting fields: Integers, Floats, or Strings. Unless /// {@link SortField SortField} objects are specified, the type of value /// in the Field is determined by parsing the first term in the Field. /// ///

Integer term values should contain only digits and an optional /// preceeding negative sign. Values must be base 10 and in the range /// Integer.MIN_VALUE and Integer.MAX_VALUE inclusive. /// Documents which should appear first in the sort /// should have low value integers, later documents high values /// (i.e. the documents should be numbered 1..n where /// 1 is the first and n the last). /// ///

Float term values should conform to values accepted by /// {@link Float Float.valueOf(String)} (except that NaN /// and Infinity are not supported). /// Documents which should appear first in the sort /// should have low values, later documents high values. /// ///

String term values can contain any valid String, but should /// not be tokenized. The values are sorted according to their /// {@link Comparable natural order}. Note that using this type /// of term value has higher memory requirements than the other /// two types. /// ///

Object Reuse

/// ///

One of these objects can be /// used multiple times and the sort order changed between usages. /// ///

This class is thread safe. /// ///

Memory Usage

/// ///

Sorting uses of caches of term values maintained by the /// internal HitQueue(s). The cache is static and contains an integer /// or float array of length IndexReader.maxDoc() for each Field /// name for which a sort is performed. In other words, the size of the /// cache in bytes is: /// ///

4 * IndexReader.maxDoc() * (# of different fields actually used to sort) /// ///

For String fields, the cache is larger: in addition to the /// above array, the value of every term in the Field is kept in memory. /// If there are many unique terms in the Field, this could /// be quite large. /// ///

Note that the size of the cache is not affected by how many /// fields are in the index and might be used to sort - only by /// the ones actually used to sort a result set. /// ///

The cache is cleared each time a new IndexReader is /// passed in, or if the value returned by maxDoc() /// changes for the current IndexReader. This class is not set up to /// be able to efficiently sort hits from more than one index /// simultaneously. /// ///

Created: Feb 12, 2004 10:53:57 AM /// ///

/// Tim Jones (Nacimiento Software) /// /// lucene 1.4 /// /// $Id: Sort.cs,v 1.2 2005/10/06 19:29:57 dsd Exp $ /// [Serializable] public class Sort { /// Represents sorting by computed relevance. Using this sort criteria returns /// the same results as calling /// {@link Searcher#Search(Query) Searcher#search()}without a sort criteria, /// only with slightly more overhead. /// public static readonly Sort RELEVANCE = new Sort(); /// Represents sorting by index order. public static readonly Sort INDEXORDER; // internal representation of the sort criteria internal SortField[] fields; /// Sorts by computed relevance. This is the same sort criteria as calling /// {@link Searcher#Search(Query) Searcher#search()}without a sort criteria, /// only with slightly more overhead. /// public Sort() : this(new SortField[]{SortField.FIELD_SCORE, SortField.FIELD_DOC}) { } /// Sorts by the terms in field then by index order (document /// number). The type of value in field is determined /// automatically. /// /// /// /// public Sort(System.String field) { SetSort(field, false); } /// Sorts possibly in reverse by the terms in field then by /// index order (document number). The type of value in field is /// determined automatically. /// /// /// /// public Sort(System.String field, bool reverse) { SetSort(field, reverse); } /// Sorts in succession by the terms in each field. The type of value in /// field is determined automatically. /// /// /// /// public Sort(System.String[] fields) { SetSort(fields); } /// Sorts by the criteria in the given SortField. public Sort(SortField field) { SetSort(field); } /// Sorts in succession by the criteria in each SortField. public Sort(SortField[] fields) { SetSort(fields); } /// Sets the sort to the terms in Field then by index order /// (document number). /// public void SetSort(System.String field) { SetSort(field, false); } /// Sets the sort to the terms in Field possibly in reverse, /// then by index order (document number). /// public virtual void SetSort(System.String field, bool reverse) { SortField[] nfields = new SortField[]{new SortField(field, SortField.AUTO, reverse), SortField.FIELD_DOC}; fields = nfields; } /// Sets the sort to the terms in each Field in succession. public virtual void SetSort(System.String[] fieldnames) { int n = fieldnames.Length; SortField[] nfields = new SortField[n]; for (int i = 0; i < n; ++i) { nfields[i] = new SortField(fieldnames[i], SortField.AUTO); } fields = nfields; } /// Sets the sort to the given criteria. public virtual void SetSort(SortField field) { this.fields = new SortField[]{field}; } /// Sets the sort to the given criteria in succession. public virtual void SetSort(SortField[] fields) { this.fields = fields; } /// Representation of the sort criteria. /// Array of SortField objects used in this sort criteria /// public virtual SortField[] GetSort() { return fields; } public override System.String ToString() { System.Text.StringBuilder buffer = new System.Text.StringBuilder(); for (int i = 0; i < fields.Length; i++) { buffer.Append(fields[i].ToString()); if ((i + 1) < fields.Length) buffer.Append(','); } return buffer.ToString(); } static Sort() { INDEXORDER = new Sort(SortField.FIELD_DOC); } } }