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
/*
* 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::index::{BytesRef, BytesRefValue};
use crate::core::util::error::lucene_error::{LuceneError, Result};
pub trait BytesRefIterator {
type Value<'a>: BytesRefValue<'a>
where
Self: 'a;
/// The returned [`BytesRef`] may be re-used across calls to `next`. After
/// this method returns `None`, do not call it again as the results are
/// undefined.
///
/// # Returns
/// The next [`BytesRef`] in the iterator or `None` if the end of the
/// iterator is reached.
///
/// # Note
/// In some scenarios, we need to return a reference to the [`BytesRef`] to
/// avoid frequent copying operations.
/// Like in [`TermsDict`](crate::core::codecs::lucene90::lucene90_doc_values_producer::TermsDict), this method can be used
/// when reusing internal buffers to reduce allocations and improve
/// performance.
///
/// To simplify the API and allow both owned and borrowed variants
/// in a unified way, it is recommended to use
/// [`Cow<BytesRef>`](std::borrow::Cow). This enables returning either:
///
/// - `Cow::Borrowed(&BytesRef)` when the data is internally reusable,
/// avoiding clone costs
/// - `Cow::Owned(BytesRef)` when a fresh copy is required
///
/// This approach provides flexibility to the implementor and clarity to the
/// caller, while preserving performance by avoiding unnecessary
/// allocations. # Errors
/// Returns an `std::io::Error` if there is a low-level I/O error.
fn next(&mut self) -> Result<Option<Self::Value<'_>>> {
Err(LuceneError::need_implemented("this method need implement"))
}
fn set_next(&mut self) -> Result<bool> {
Err(LuceneError::need_implemented("this method need implement"))
}
}
pub struct EmptyBytesRefIterator;
impl BytesRefIterator for EmptyBytesRefIterator {
type Value<'a> = &'a BytesRef<Vec<u8>>;
fn next(&mut self) -> Result<Option<Self::Value<'_>>> {
Ok(None)
}
}
impl EmptyBytesRefIterator {
pub const EMPTY: Self = EmptyBytesRefIterator;
}
impl<T> BytesRefIterator for &mut T
where
T: BytesRefIterator,
{
type Value<'a>
= T::Value<'a>
where
Self: 'a;
#[inline]
fn next(&mut self) -> Result<Option<Self::Value<'_>>> {
(**self).next()
}
#[inline]
fn set_next(&mut self) -> Result<bool> {
(**self).set_next()
}
}