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