Lucene.Net  3.0.3
Lucene.Net is a port of the Lucene search engine library, written in C# and targeted at .NET runtime users.
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Properties Pages
Sort.cs
Go to the documentation of this file.
1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements. See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License. You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 using System;
19 using Lucene.Net.Support;
20 
21 namespace Lucene.Net.Search
22 {
23 
24 
25  /// <summary> Encapsulates sort criteria for returned hits.
26  ///
27  /// <p/>The fields used to determine sort order must be carefully chosen.
28  /// Documents must contain a single term in such a field,
29  /// and the value of the term should indicate the document's relative position in
30  /// a given sort order. The field must be indexed, but should not be tokenized,
31  /// and does not need to be stored (unless you happen to want it back with the
32  /// rest of your document data). In other words:
33  ///
34  /// <p/><c>document.add (new Field ("byNumber", Integer.toString(x), Field.Store.NO, Field.Index.NOT_ANALYZED));</c><p/>
35  ///
36  ///
37  /// <p/><h3>Valid Types of Values</h3>
38  ///
39  /// <p/>There are four possible kinds of term values which may be put into
40  /// sorting fields: Integers, Longs, Floats, or Strings. Unless
41  /// <see cref="SortField">SortField</see> objects are specified, the type of value
42  /// in the field is determined by parsing the first term in the field.
43  ///
44  /// <p/>Integer term values should contain only digits and an optional
45  /// preceding negative sign. Values must be base 10 and in the range
46  /// <c>Integer.MIN_VALUE</c> and <c>Integer.MAX_VALUE</c> inclusive.
47  /// Documents which should appear first in the sort
48  /// should have low value integers, later documents high values
49  /// (i.e. the documents should be numbered <c>1..n</c> where
50  /// <c>1</c> is the first and <c>n</c> the last).
51  ///
52  /// <p/>Long term values should contain only digits and an optional
53  /// preceding negative sign. Values must be base 10 and in the range
54  /// <c>Long.MIN_VALUE</c> and <c>Long.MAX_VALUE</c> inclusive.
55  /// Documents which should appear first in the sort
56  /// should have low value integers, later documents high values.
57  ///
58  /// <p/>Float term values should conform to values accepted by
59  /// <see cref="float.Parse(string)" /> (except that <c>NaN</c>
60  /// and <c>Infinity</c> are not supported).
61  /// Documents which should appear first in the sort
62  /// should have low values, later documents high values.
63  ///
64  /// <p/>String term values can contain any valid String, but should
65  /// not be tokenized. The values are sorted according to their
66  /// <see cref="IComparable">natural order</see>. Note that using this type
67  /// of term value has higher memory requirements than the other
68  /// two types.
69  ///
70  /// <p/><h3>Object Reuse</h3>
71  ///
72  /// <p/>One of these objects can be
73  /// used multiple times and the sort order changed between usages.
74  ///
75  /// <p/>This class is thread safe.
76  ///
77  /// <p/><h3>Memory Usage</h3>
78  ///
79  /// <p/>Sorting uses of caches of term values maintained by the
80  /// internal HitQueue(s). The cache is static and contains an integer
81  /// or float array of length <c>IndexReader.MaxDoc</c> for each field
82  /// name for which a sort is performed. In other words, the size of the
83  /// cache in bytes is:
84  ///
85  /// <p/><c>4 * IndexReader.MaxDoc * (# of different fields actually used to sort)</c>
86  ///
87  /// <p/>For String fields, the cache is larger: in addition to the
88  /// above array, the value of every term in the field is kept in memory.
89  /// If there are many unique terms in the field, this could
90  /// be quite large.
91  ///
92  /// <p/>Note that the size of the cache is not affected by how many
93  /// fields are in the index and <i>might</i> be used to sort - only by
94  /// the ones actually used to sort a result set.
95  ///
96  /// <p/>Created: Feb 12, 2004 10:53:57 AM
97  ///
98  /// </summary>
99  [Serializable]
100  public class Sort
101  {
102 
103  /// <summary> Represents sorting by computed relevance. Using this sort criteria returns
104  /// the same results as calling
105  /// <see cref="Searcher.Search(Query,int)" />Searcher#search()without a sort criteria,
106  /// only with slightly more overhead.
107  /// </summary>
108  public static readonly Sort RELEVANCE = new Sort();
109 
110  /// <summary>Represents sorting by index order. </summary>
111  public static readonly Sort INDEXORDER;
112 
113  // internal representation of the sort criteria
114  internal SortField[] fields;
115 
116  /// <summary> Sorts by computed relevance. This is the same sort criteria as calling
117  /// <see cref="Searcher.Search(Query,int)" />without a sort criteria,
118  /// only with slightly more overhead.
119  /// </summary>
120  public Sort():this(SortField.FIELD_SCORE)
121  {
122  }
123 
124  /// <summary>Sorts by the criteria in the given SortField. </summary>
125  public Sort(SortField field)
126  {
127  SetSort(field);
128  }
129 
130  /// <summary>Sorts in succession by the criteria in each SortField. </summary>
131  public Sort(params SortField[] fields)
132  {
133  SetSort(fields);
134  }
135 
136  /// <summary>Sets the sort to the given criteria. </summary>
137  public virtual void SetSort(SortField field)
138  {
139  this.fields = new SortField[]{field};
140  }
141 
142  /// <summary>Sets the sort to the given criteria in succession. </summary>
143  public virtual void SetSort(params SortField[] fields)
144  {
145  this.fields = fields;
146  }
147 
148  /// <summary> Representation of the sort criteria.</summary>
149  /// <returns> Array of SortField objects used in this sort criteria
150  /// </returns>
151  public virtual SortField[] GetSort()
152  {
153  return fields;
154  }
155 
156  public override System.String ToString()
157  {
158  System.Text.StringBuilder buffer = new System.Text.StringBuilder();
159 
160  for (int i = 0; i < fields.Length; i++)
161  {
162  buffer.Append(fields[i].ToString());
163  if ((i + 1) < fields.Length)
164  buffer.Append(',');
165  }
166 
167  return buffer.ToString();
168  }
169 
170  /// <summary>Returns true if <c>o</c> is equal to this. </summary>
171  public override bool Equals(System.Object o)
172  {
173  if (this == o)
174  return true;
175  if (!(o is Sort))
176  return false;
177  Sort other = (Sort) o;
178 
179  bool result = false;
180  if ((this.fields == null) && (other.fields == null))
181  result = true;
182  else if ((this.fields != null) && (other.fields != null))
183  {
184  if (this.fields.Length == other.fields.Length)
185  {
186  int length = this.fields.Length;
187  result = true;
188  for (int i = 0; i < length; i++)
189  {
190  if (!(this.fields[i].Equals(other.fields[i])))
191  {
192  result = false;
193  break;
194  }
195  }
196  }
197  }
198  return result;
199  }
200 
201  /// <summary>Returns a hash code value for this object. </summary>
202  public override int GetHashCode()
203  {
204  // TODO in Java 1.5: switch to Arrays.hashCode(). The
205  // Java 1.4 workaround below calculates the same hashCode
206  // as Java 1.5's new Arrays.hashCode()
207  return 0x45aaf665 + EquatableList<SortField>.GetHashCode(fields);
208  }
209  static Sort()
210  {
211  INDEXORDER = new Sort(SortField.FIELD_DOC);
212  }
213  }
214 }