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
Spans.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 System.Collections.Generic;
20 
21 namespace Lucene.Net.Search.Spans
22 {
23 
24  /// <summary>Expert: an enumeration of span matches. Used to implement span searching.
25  /// Each span represents a range of term positions within a document. Matches
26  /// are enumerated in order, by increasing document number, within that by
27  /// increasing start position and finally by increasing end position.
28  /// </summary>
29  public abstract class Spans
30  {
31  /// <summary>Move to the next match, returning true iff any such exists. </summary>
32  public abstract bool Next();
33 
34  /// <summary>Skips to the first match beyond the current, whose document number is
35  /// greater than or equal to <i>target</i>. <p/>Returns true iff there is such
36  /// a match. <p/>Behaves as if written: <code>
37  /// boolean skipTo(int target) {
38  /// do {
39  /// if (!next())
40  /// return false;
41  /// } while (target > doc());
42  /// return true;
43  /// }
44  /// </code>
45  /// Most implementations are considerably more efficient than that.
46  /// </summary>
47  public abstract bool SkipTo(int target);
48 
49  /// <summary>Returns the document number of the current match. Initially invalid. </summary>
50  public abstract int Doc();
51 
52  /// <summary>Returns the start position of the current match. Initially invalid. </summary>
53  public abstract int Start();
54 
55  /// <summary>Returns the end position of the current match. Initially invalid. </summary>
56  public abstract int End();
57 
58  /// <summary> Returns the payload data for the current span.
59  /// This is invalid until <see cref="Next()" /> is called for
60  /// the first time.
61  /// This method must not be called more than once after each call
62  /// of <see cref="Next()" />. However, most payloads are loaded lazily,
63  /// so if the payload data for the current position is not needed,
64  /// this method may not be called at all for performance reasons. An ordered
65  /// SpanQuery does not lazy load, so if you have payloads in your index and
66  /// you do not want ordered SpanNearQuerys to collect payloads, you can
67  /// disable collection with a constructor option.<br/>
68  ///
69  /// Note that the return type is a collection, thus the ordering should not be relied upon.
70  /// <br/>
71  /// <p/><font color="#FF0000">
72  /// WARNING: The status of the <b>Payloads</b> feature is experimental.
73  /// The APIs introduced here might change in the future and will not be
74  /// supported anymore in such a case.</font><p/>
75  ///
76  /// </summary>
77  /// <returns> a List of byte arrays containing the data of this payload, otherwise null if isPayloadAvailable is false </returns>
78  /// <throws> java.io.IOException </throws>
79  // TODO: Remove warning after API has been finalized
80  [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate")]
81  public abstract ICollection<byte[]> GetPayload();
82 
83  /// <summary> Checks if a payload can be loaded at this position.
84  /// <p/>
85  /// Payloads can only be loaded once per call to
86  /// <see cref="Next()" />.
87  ///
88  /// </summary>
89  /// <returns> true if there is a payload available at this position that can be loaded </returns>
90  public abstract bool IsPayloadAvailable();
91  }
92 }