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
HitQueue.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.Util;
20 
21 namespace Lucene.Net.Search
22 {
23 
24  public sealed class HitQueue : PriorityQueue<ScoreDoc>
25  {
26 
27  private bool prePopulate;
28 
29  /// <summary> Creates a new instance with <c>size</c> elements. If
30  /// <c>prePopulate</c> is set to true, the queue will pre-populate itself
31  /// with sentinel objects and set its <see cref="PriorityQueue{T}.Size()" /> to <c>size</c>. In
32  /// that case, you should not rely on <see cref="PriorityQueue{T}.Size()" /> to get the number of
33  /// actual elements that were added to the queue, but keep track yourself.<br/>
34  /// <b>NOTE:</b> in case <c>prePopulate</c> is true, you should pop
35  /// elements from the queue using the following code example:
36  ///
37  /// <code>
38  /// PriorityQueue pq = new HitQueue(10, true); // pre-populate.
39  /// ScoreDoc top = pq.top();
40  ///
41  /// // Add/Update one element.
42  /// top.score = 1.0f;
43  /// top.doc = 0;
44  /// top = (ScoreDoc) pq.updateTop();
45  /// int totalHits = 1;
46  ///
47  /// // Now pop only the elements that were *truly* inserted.
48  /// // First, pop all the sentinel elements (there are pq.size() - totalHits).
49  /// for (int i = pq.size() - totalHits; i &gt; 0; i--) pq.pop();
50  ///
51  /// // Now pop the truly added elements.
52  /// ScoreDoc[] results = new ScoreDoc[totalHits];
53  /// for (int i = totalHits - 1; i &gt;= 0; i--) {
54  /// results[i] = (ScoreDoc) pq.pop();
55  /// }
56  /// </code>
57  ///
58  /// <p/><b>NOTE</b>: This class pre-allocate a full array of
59  /// length <c>size</c>.
60  ///
61  /// </summary>
62  /// <param name="size">the requested size of this queue.
63  /// </param>
64  /// <param name="prePopulate">specifies whether to pre-populate the queue with sentinel values.
65  /// </param>
66  /// <seealso cref="SentinelObject">
67  /// </seealso>
68  public /*internal*/ HitQueue(int size, bool prePopulate)
69  {
70  this.prePopulate = prePopulate;
71  Initialize(size);
72  }
73 
74  // Returns null if prePopulate is false.
75 
76  protected internal override ScoreDoc SentinelObject
77  {
78  get
79  {
80  // Always set the doc Id to MAX_VALUE so that it won't be favored by
81  // lessThan. This generally should not happen since if score is not NEG_INF,
82  // TopScoreDocCollector will always add the object to the queue.
83  return !prePopulate ? null : new ScoreDoc(System.Int32.MaxValue, System.Single.NegativeInfinity);
84  }
85  }
86 
87  public override bool LessThan(ScoreDoc hitA, ScoreDoc hitB)
88  {
89  if (hitA.Score == hitB.Score)
90  return hitA.Doc > hitB.Doc;
91  else
92  return hitA.Score < hitB.Score;
93  }
94  }
95 }