1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
use crate::core::search::doc_id_set_iterator::NO_MORE_DOCS;
use crate::core::util::error::lucene_error::Result;
/// Skipper for DocValues.
///
/// A skipper has a position that can only be advanced via
/// [`advance(target)`](DocValuesSkipper::advance). The next advance position
/// must be greater than [`max_doc_id(0)`](DocValuesSkipper::max_doc_id_with_level).
/// A skipper's position, along with a `level`, determines the interval at which
/// the skipper is currently situated.
pub trait DocValuesSkipper {
/// Advance this skipper so that all levels contain the next document on or
/// after `target`.
///
/// NOTE: The behavior is undefined if `target` is less than or equal to
/// `max_doc_id(0)`.
///
/// NOTE: `min_doc_id(0)` may return a doc ID that is greater than `target`
/// if the target document doesn't have a value.
fn advance(&mut self, target: i32) -> Result<()>;
/// Return the number of levels. This number may change when moving to a
/// different interval.
fn num_levels(&self) -> usize;
/// Return the minimum doc ID of the interval on the given level, inclusive.
///
/// This returns `-1` if [`advance(target)`](DocValuesSkipper::advance) has
/// not been called yet and [`NO_MORE_DOCS`] if the iterator is exhausted.
/// This method is non-increasing when `level` increases.
/// In other words: `min_doc_id(level+1) <= min_doc_id(level)`.
fn min_doc_id_with_level(&self, level: usize) -> i32;
/// Return the maximum doc ID of the interval on the given level, inclusive.
///
/// This returns `-1` if [`advance(target)`](DocValuesSkipper::advance) has
/// not been called yet and [`NO_MORE_DOCS`] if the iterator is
/// exhausted. This method is non-decreasing when `level` decreases.
/// In other words: `max_doc_id(level+1) >= max_doc_id(level)`.
fn max_doc_id_with_level(&self, level: usize) -> i32;
/// Return the minimum value of the interval at the given level, inclusive.
///
/// NOTE: It is only guaranteed that values in this interval are greater
/// than or equal to the returned value. There is no guarantee that one
/// document actually has this value.
fn min_value_with_level(&self, level: usize) -> i64;
/// Return the maximum value of the interval at the given level, inclusive.
///
/// NOTE: It is only guaranteed that values in this interval are less than
/// or equal to the returned value. There is no guarantee that one
/// document actually has this value.
fn max_value_with_level(&self, level: usize) -> i64;
/// Return the number of documents that have a value in the interval
/// associated with the given level.
fn doc_count_with_level(&self, level: usize) -> i32;
/// Return the global minimum value.
///
/// NOTE: It is only guaranteed that values are greater than or equal to the
/// returned value. There is no guarantee that one document actually has
/// this value.
fn min_value(&self) -> i64;
/// Return the global maximum value.
///
/// NOTE: It is only guaranteed that values are less than or equal to the
/// returned value. There is no guarantee that one document actually has
/// this value.
fn max_value(&self) -> i64;
/// Return the global number of documents with a value for the field.
fn doc_count(&self) -> i32;
/// Advance this skipper so that all levels intersect the range given by
/// `min_value` and `max_value`. If there are no intersecting levels,
/// the skipper is exhausted.
fn advance_with_range(&mut self, min_value: i64, max_value: i64) -> Result<()> {
if self.min_doc_id_with_level(0) == -1 {
// `advance` has not been called yet
self.advance(0)?;
}
// check if the current interval intersects the provided range
while self.min_doc_id_with_level(0) != NO_MORE_DOCS
&& (self.min_value_with_level(0) > max_value || self.max_value_with_level(0) < min_value)
{
let mut max_doc_id = self.max_doc_id_with_level(0);
let mut next_level = 1;
// check if the next levels intersect to skip as many docs as
// possible
while next_level < self.num_levels()
&& (self.min_value_with_level(next_level) > max_value
|| self.max_value_with_level(next_level) < min_value)
{
max_doc_id = self.max_doc_id_with_level(next_level);
next_level += 1;
}
self.advance(max_doc_id + 1)?;
}
Ok(())
}
}