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
DocIdSetIterator.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 namespace Lucene.Net.Search
19 {
20 
21  /// <summary> This abstract class defines methods to iterate over a set of non-decreasing
22  /// doc ids. Note that this class assumes it iterates on doc Ids, and therefore
23  /// <see cref="NO_MORE_DOCS" /> is set to Int32.MaxValue in order to be used as
24  /// a sentinel object. Implementations of this class are expected to consider
25  /// <see cref="int.MaxValue" /> as an invalid value.
26  /// </summary>
27  public abstract class DocIdSetIterator
28  {
29  private int doc = - 1;
30 
31  /// <summary> When returned by <see cref="NextDoc()" />, <see cref="Advance(int)" /> and
32  /// <see cref="DocID()" /> it means there are no more docs in the iterator.
33  /// </summary>
34  public static readonly int NO_MORE_DOCS = System.Int32.MaxValue;
35 
36  /// <summary> Returns the following:
37  /// <list type="bullet">
38  /// <item>-1 or <see cref="NO_MORE_DOCS" /> if <see cref="NextDoc()" /> or
39  /// <see cref="Advance(int)" /> were not called yet.</item>
40  /// <item><see cref="NO_MORE_DOCS" /> if the iterator has exhausted.</item>
41  /// <item>Otherwise it should return the doc ID it is currently on.</item>
42  /// </list>
43  /// <p/>
44  /// </summary>
45  public abstract int DocID();
46 
47  /// <summary> Advances to the next document in the set and returns the doc it is
48  /// currently on, or <see cref="NO_MORE_DOCS" /> if there are no more docs in the
49  /// set.<br/>
50  ///
51  /// <b>NOTE:</b> after the iterator has exhausted you should not call this
52  /// method, as it may result in unpredicted behavior.
53  ///
54  /// </summary>
55  public abstract int NextDoc();
56 
57  /// <summary> Advances to the first beyond the current whose document number is greater
58  /// than or equal to <i>target</i>. Returns the current document number or
59  /// <see cref="NO_MORE_DOCS" /> if there are no more docs in the set.
60  /// <p/>
61  /// Behaves as if written:
62  ///
63  /// <code>
64  /// int advance(int target) {
65  /// int doc;
66  /// while ((doc = nextDoc()) &lt; target) {
67  /// }
68  /// return doc;
69  /// }
70  /// </code>
71  ///
72  /// Some implementations are considerably more efficient than that.
73  /// <p/>
74  /// <b>NOTE:</b> certain implemenations may return a different value (each
75  /// time) if called several times in a row with the same target.
76  /// <p/>
77  /// <b>NOTE:</b> this method may be called with <see cref="NO_MORE_DOCS"/> for
78  /// efficiency by some Scorers. If your implementation cannot efficiently
79  /// determine that it should exhaust, it is recommended that you check for that
80  /// value in each call to this method.
81  /// <p/>
82  /// <b>NOTE:</b> after the iterator has exhausted you should not call this
83  /// method, as it may result in unpredicted behavior.
84  /// <p/>
85  ///
86  /// </summary>
87  /// <since>2.9</since>
88  public abstract int Advance(int target);
89  }
90 }