Clover Coverage Report
Coverage timestamp: Fri May 9 2008 10:54:27 EST
Overview   Package   File
    FRAMES   NO FRAMES     
../../../../img/srcFileCovDistChart6.png 74% of files have more coverage
23   219   16   1.77
6   60   0.7   13
13     1.23  
1    
 
  Sort       Line # 94 23 16 59.5% 0.5952381
 
  (25)
 
1    package org.apache.lucene.search;
2   
3    /**
4    * Copyright 2004 The Apache Software Foundation
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10    * http://www.apache.org/licenses/LICENSE-2.0
11    *
12    * Unless required by applicable law or agreed to in writing, software
13    * distributed under the License is distributed on an "AS IS" BASIS,
14    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15    * See the License for the specific language governing permissions and
16    * limitations under the License.
17    */
18   
19    import java.io.Serializable;
20   
21   
22    /**
23    * 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 Fieldable ("byNumber", Integer.toString(x), Fieldable.Store.NO, Fieldable.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>Created: Feb 12, 2004 10:53:57 AM
89    *
90    * @author Tim Jones (Nacimiento Software)
91    * @since lucene 1.4
92    * @version $Id: Sort.java 470109 2006-11-01 21:35:32Z yonik $
93    */
 
94    public class Sort
95    implements Serializable {
96   
97    /**
98    * Represents sorting by computed relevance. Using this sort criteria returns
99    * the same results as calling
100    * {@link Searcher#search(Query) Searcher#search()}without a sort criteria,
101    * only with slightly more overhead.
102    */
103    public static final Sort RELEVANCE = new Sort();
104   
105    /** Represents sorting by index order. */
106    public static final Sort INDEXORDER = new Sort(SortField.FIELD_DOC);
107   
108    // internal representation of the sort criteria
109    SortField[] fields;
110   
111    /**
112    * Sorts by computed relevance. This is the same sort criteria as calling
113    * {@link Searcher#search(Query) Searcher#search()}without a sort criteria,
114    * only with slightly more overhead.
115    */
 
116  28 toggle public Sort() {
117  28 this(new SortField[] { SortField.FIELD_SCORE, SortField.FIELD_DOC });
118    }
119   
120    /**
121    * Sorts by the terms in <code>field</code> then by index order (document
122    * number). The type of value in <code>field</code> is determined
123    * automatically.
124    *
125    * @see SortField#AUTO
126    */
 
127  1 toggle public Sort(String field) {
128  1 setSort(field, false);
129    }
130   
131    /**
132    * Sorts possibly in reverse by the terms in <code>field</code> then by
133    * index order (document number). The type of value in <code>field</code> is
134