beagled/Lucene.Net/Search/Sort.cs

   1 /*
   2  * Copyright 2004 The Apache Software Foundation
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 using System;
  17 namespace Lucene.Net.Search
  18 {
  19
  20
  21         /// <summary> Encapsulates sort criteria for returned hits.
  22         ///
  23         /// <p>The fields used to determine sort order must be carefully chosen.
  24         /// Documents must contain a single term in such a Field,
  25         /// and the value of the term should indicate the document's relative position in
  26         /// a given sort order.  The Field must be indexed, but should not be tokenized,
  27         /// and does not need to be stored (unless you happen to want it back with the
  28         /// rest of your document data).  In other words:
  29         ///
  30         /// <p><code>document.add (new Field ("byNumber", Integer.toString(x), Field.Store.NO, Field.Index.UN_TOKENIZED));</code></p>
  31         ///
  32         ///
  33         /// <p><h3>Valid Types of Values</h3>
  34         ///
  35         /// <p>There are three possible kinds of term values which may be put into
  36         /// sorting fields: Integers, Floats, or Strings.  Unless
  37         /// {@link SortField SortField} objects are specified, the type of value
  38         /// in the Field is determined by parsing the first term in the Field.
  39         ///
  40         /// <p>Integer term values should contain only digits and an optional
  41         /// preceeding negative sign.  Values must be base 10 and in the range
  42         /// <code>Integer.MIN_VALUE</code> and <code>Integer.MAX_VALUE</code> inclusive.
  43         /// Documents which should appear first in the sort
  44         /// should have low value integers, later documents high values
  45         /// (i.e. the documents should be numbered <code>1..n</code> where
  46         /// <code>1</code> is the first and <code>n</code> the last).
  47         ///
  48         /// <p>Float term values should conform to values accepted by
  49         /// {@link Float Float.valueOf(String)} (except that <code>NaN</code>
  50         /// and <code>Infinity</code> are not supported).
  51         /// Documents which should appear first in the sort
  52         /// should have low values, later documents high values.
  53         ///
  54         /// <p>String term values can contain any valid String, but should
  55         /// not be tokenized.  The values are sorted according to their
  56         /// {@link Comparable natural order}.  Note that using this type
  57         /// of term value has higher memory requirements than the other
  58         /// two types.
  59         ///
  60         /// <p><h3>Object Reuse</h3>
  61         ///
  62         /// <p>One of these objects can be
  63         /// used multiple times and the sort order changed between usages.
  64         ///
  65         /// <p>This class is thread safe.
  66         ///
  67         /// <p><h3>Memory Usage</h3>
  68         ///
  69         /// <p>Sorting uses of caches of term values maintained by the
  70         /// internal HitQueue(s).  The cache is static and contains an integer
  71         /// or float array of length <code>IndexReader.maxDoc()</code> for each Field
  72         /// name for which a sort is performed.  In other words, the size of the
  73         /// cache in bytes is:
  74         ///
  75         /// <p><code>4 * IndexReader.maxDoc() * (# of different fields actually used to sort)</code>
  76         ///
  77         /// <p>For String fields, the cache is larger: in addition to the
  78         /// above array, the value of every term in the Field is kept in memory.
  79         /// If there are many unique terms in the Field, this could
  80         /// be quite large.
  81         ///
  82         /// <p>Note that the size of the cache is not affected by how many
  83         /// fields are in the index and <i>might</i> be used to sort - only by
  84         /// the ones actually used to sort a result set.
  85         ///
  86         /// <p>The cache is cleared each time a new <code>IndexReader</code> is
  87         /// passed in, or if the value returned by <code>maxDoc()</code>
  88         /// changes for the current IndexReader.  This class is not set up to
  89         /// be able to efficiently sort hits from more than one index
  90         /// simultaneously.
  91         ///
  92         /// <p>Created: Feb 12, 2004 10:53:57 AM
  93         ///
  94         /// </summary>
  95         /// <author>   Tim Jones (Nacimiento Software)
  96         /// </author>
  97         /// <since>   lucene 1.4
  98         /// </since>
  99         /// <version>  $Id: Sort.cs,v 1.2 2005/10/06 19:29:57 dsd Exp $
 100         /// </version>
 101         [Serializable]
 102         public class Sort
 103         {
 104
 105         /// <summary> Represents sorting by computed relevance. Using this sort criteria returns
 106         /// the same results as calling
 107         /// {@link Searcher#Search(Query) Searcher#search()}without a sort criteria,
 108         /// only with slightly more overhead.
 109         /// </summary>
 110         public static readonly Sort RELEVANCE = new Sort();
 111
 112                 /// <summary>Represents sorting by index order. </summary>
 113                 public static readonly Sort INDEXORDER;
 114
 115                 // internal representation of the sort criteria
 116                 internal SortField[] fields;
 117
 118         /// <summary> Sorts by computed relevance. This is the same sort criteria as calling
 119         /// {@link Searcher#Search(Query) Searcher#search()}without a sort criteria,
 120         /// only with slightly more overhead.
 121         /// </summary>
 122         public Sort() : this(new SortField[]{SortField.FIELD_SCORE, SortField.FIELD_DOC})
 123         {
 124         }
 125
 126         /// <summary> Sorts by the terms in <code>field</code> then by index order (document
 127         /// number). The type of value in <code>field</code> is determined
 128         /// automatically.
 129         ///
 130         /// </summary>
 131         /// <seealso cref="SortField#AUTO">
 132         /// </seealso>
 133         public Sort(System.String field)
 134                 {
 135                         SetSort(field, false);
 136                 }
 137
 138         /// <summary> Sorts possibly in reverse by the terms in <code>field</code> then by
 139         /// index order (document number). The type of value in <code>field</code> is
 140         /// determined automatically.
 141         ///
 142         /// </summary>
 143         /// <seealso cref="SortField#AUTO">
 144         /// </seealso>
 145         public Sort(System.String field, bool reverse)
 146                 {
 147                         SetSort(field, reverse);
 148                 }
 149
 150         /// <summary> Sorts in succession by the terms in each field. The type of value in
 151         /// <code>field</code> is determined automatically.
 152         ///
 153         /// </summary>
 154         /// <seealso cref="SortField#AUTO">
 155         /// </seealso>
 156         public Sort(System.String[] fields)
 157                 {
 158                         SetSort(fields);
 159                 }
 160
 161                 /// <summary>Sorts by the criteria in the given SortField. </summary>
 162                 public Sort(SortField field)
 163                 {
 164                         SetSort(field);
 165                 }
 166
 167                 /// <summary>Sorts in succession by the criteria in each SortField. </summary>
 168                 public Sort(SortField[] fields)
 169                 {
 170                         SetSort(fields);
 171                 }
 172
 173                 /// <summary> Sets the sort to the terms in <code>Field</code> then by index order
 174                 /// (document number).
 175                 /// </summary>
 176                 public void  SetSort(System.String field)
 177                 {
 178                         SetSort(field, false);
 179                 }
 180
 181                 /// <summary> Sets the sort to the terms in <code>Field</code> possibly in reverse,
 182                 /// then by index order (document number).
 183                 /// </summary>
 184                 public virtual void  SetSort(System.String field, bool reverse)
 185                 {
 186                         SortField[] nfields = new SortField[]{new SortField(field, SortField.AUTO, reverse), SortField.FIELD_DOC};
 187                         fields = nfields;
 188                 }
 189
 190                 /// <summary>Sets the sort to the terms in each Field in succession. </summary>
 191                 public virtual void  SetSort(System.String[] fieldnames)
 192                 {
 193                         int n = fieldnames.Length;
 194                         SortField[] nfields = new SortField[n];
 195                         for (int i = 0; i < n; ++i)
 196                         {
 197                                 nfields[i] = new SortField(fieldnames[i], SortField.AUTO);
 198                         }
 199                         fields = nfields;
 200                 }
 201
 202                 /// <summary>Sets the sort to the given criteria. </summary>
 203                 public virtual void  SetSort(SortField field)
 204                 {
 205                         this.fields = new SortField[]{field};
 206                 }
 207
 208                 /// <summary>Sets the sort to the given criteria in succession. </summary>
 209                 public virtual void  SetSort(SortField[] fields)
 210                 {
 211                         this.fields = fields;
 212                 }
 213
 214         /// <summary> Representation of the sort criteria.</summary>
 215         /// <returns> Array of SortField objects used in this sort criteria
 216         /// </returns>
 217         public virtual SortField[] GetSort()
 218         {
 219             return fields;
 220         }
 221
 222         public override System.String ToString()
 223                 {
 224                         System.Text.StringBuilder buffer = new System.Text.StringBuilder();
 225
 226                         for (int i = 0; i < fields.Length; i++)
 227                         {
 228                                 buffer.Append(fields[i].ToString());
 229                                 if ((i + 1) < fields.Length)
 230                                         buffer.Append(',');
 231                         }
 232
 233                         return buffer.ToString();
 234                 }
 235                 static Sort()
 236                 {
 237                         INDEXORDER = new Sort(SortField.FIELD_DOC);
 238                 }
 239         }
 240 }