rlucene 0.1.0-alpha.3

A Rust port of Apache Lucene, a full-text search engine library
Documentation
/*
 * 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::util::access::SharedAccessVec;
use crate::core::util::error::lucene_error::LuceneError;
use crate::core::util::error::lucene_error::Result;
use crate::core::util::{Comparator, HashCode, ToInt};
use crate::with_other;
use std::cmp::Ordering;
use std::fmt;
use std::fmt::{Display, Formatter};
use std::hash::{Hash, Hasher};
use std::sync::Arc;
/// A generic, slice-like reference over an integer array with offset and
/// length.
///
/// `IntsRef<AV>` provides a flexible abstraction for referencing a sub-slice of
/// integers, where `AV` is a container implementing [`SharedAccessVec<i32>`].
///
/// This design supports different memory access models:
///
/// - **Single-threaded, shared ownership:**   Use `Rc<RefCell<Vec<i32>>>` as
///   the `AV` type. This allows multiple parts of the program to mutate the
///   same underlying data safely in a single-threaded context.
///
/// - **Multi-threaded, locked access:** Use `Arc<Mutex<Vec<i32>>>` for
///   safe concurrent access and mutation across threads.
///
/// - **No sharing / performance-focused:**   Use plain `Vec<i32>` if the data
///   is owned locally and doesn’t need to be shared. This offers the best
///   performance with no synchronization overhead.
///
/// The generic `AccessVec` trait provides unified access for all three
/// modes, abstracting over access, mutation, cloning, and construction.
/// Represents an `i32` slice as an offset and length into an existing buffer.
#[derive(Debug)]
pub struct IntsRef<AV> {
  /// The contents of the IntsRef
  pub ints: AV,
  /// Offset of first valid integer.
  pub offset: usize,
  /// Length of used ints.
  pub length: usize,
}
impl<AV> Default for IntsRef<AV>
where
  AV: SharedAccessVec<i32>,
{
  fn default() -> Self {
    Self::new()
  }
}
impl IntsRef<Arc<Vec<i32>>> {
  /// compare: same bytes reference, same offset, same length
  pub fn equals(a: &IntsRef<Arc<Vec<i32>>>, b: &IntsRef<Arc<Vec<i32>>>) -> bool {
    let v = Arc::ptr_eq(&a.ints, &b.ints);
    // Check reference equality: if the backing array reference is the same,
    // then offset and length must also be equal.
    debug_assert!({
      if v {
        a.offset == b.offset && a.length == b.length
      } else {
        !v
      }
    });
    v
  }
}

impl<AV> IntsRef<AV>
where
  AV: SharedAccessVec<i32>,
{
  /// Create an IntsRef with `EMPTY_INTS`.
  pub fn new() -> Self {
    IntsRef {
      ints: AV::new(),
      offset: 0,
      length: 0,
    }
  }

  /// Create an IntsRef pointing to a new array of size `capacity`.
  pub fn with_capacity(capacity: usize) -> Result<Self> {
    Ok(IntsRef {
      ints: AV::with_len(capacity, || 0)?,
      offset: 0,
      length: 0,
    })
  }
  pub fn from_slice(ints: AV, offset: usize, length: usize) -> Self {
    let instance = IntsRef {
      ints,
      offset,
      length,
    };
    #[cfg(debug_assertions)]
    debug_assert!(matches!(instance.is_valid(), Ok(true)));
    instance
  }
  /// Performs internal consistency checks. Always returns true (or Error)
  pub fn is_valid(&self) -> Result<bool> {
    self.ints.access(|ints| {
      if self.length > ints.len() {
        return Err(LuceneError::illegal_state(format!(
          "length is out of bounds: {}, ints.len()={}",
          self.length,
          ints.len()
        )));
      }
      if self.offset > ints.len() {
        return Err(LuceneError::illegal_state(format!(
          "offset out of bounds: {}, ints.len()={}",
          self.offset,
          ints.len()
        )));
      }
      if self.length > ints.len() - self.offset {
        return Err(LuceneError::illegal_state(format!(
          "offset+length out of bounds: offset={}, length={}, ints.len()={}",
          self.offset,
          self.length,
          ints.len()
        )));
      }
      Ok(true)
    })
  }
  pub fn ints_equals(&self, other: &IntsRef<AV>) -> bool {
    with_other!(self.ints, other.ints, |ints_bytes, other_bytes| {
      let self_slice = &ints_bytes[self.offset..(self.offset + self.length)];
      let other_slice = &other_bytes[other.offset..(other.offset + other.length)];
      self_slice == other_slice
    })
  }
  /// Creates a new IntsRef that points to a copy of the ints from `other`
  ///
  /// The returned IntsRef will have a length of `other.length` and an offset
  /// of zero.
  pub fn deep_copy_of(other: &IntsRef<AV>) -> Self {
    let ints = other.ints.slice_clone(other.offset, other.length);
    IntsRef {
      ints,
      offset: 0,
      length: other.length,
    }
  }
}
impl<AV> Clone for IntsRef<AV>
where
  AV: Clone,
{
  /// Clones this instance and its backing container.
  ///
  /// Whether the underlying ints are copied or shared is determined by
  /// `AV::clone` (for example, `Vec` copies while `Arc` shares).
  fn clone(&self) -> Self {
    IntsRef {
      ints: self.ints.clone(),
      offset: self.offset,
      length: self.length,
    }
  }
}
impl<AV> PartialOrd for IntsRef<AV>
where
  AV: SharedAccessVec<i32>,
{
  fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
    Some(self.cmp(other))
  }
}
impl<AV> Ord for IntsRef<AV>
where
  AV: SharedAccessVec<i32>,
{
  fn cmp(&self, other: &Self) -> Ordering {
    with_other!(self.ints, other.ints, |ints_bytes, other_bytes| {
      let self_slice = &ints_bytes[self.offset..(self.offset + self.length)];
      let other_slice = &other_bytes[other.offset..(other.offset + other.length)];
      self_slice.cmp(other_slice)
    })
  }
}
impl<AV> PartialEq for IntsRef<AV>
where
  AV: SharedAccessVec<i32>,
{
  fn eq(&self, other: &Self) -> bool {
    self.ints_equals(other)
  }
}
impl<AV> Eq for IntsRef<AV> where AV: SharedAccessVec<i32> {}
impl<AV> Hash for IntsRef<AV>
where
  AV: SharedAccessVec<i32>,
{
  fn hash<H>(&self, state: &mut H)
  where
    H: Hasher,
  {
    self.ints.access(|ints| {
      let slice = &ints[self.offset..(self.offset + self.length)];
      slice.hash(state);
    });
  }
}
impl<AV> Comparator<IntsRef<AV>> for IntsRef<AV>
where
  AV: SharedAccessVec<i32>,
{
  const TYPE: &'static str = "IntsRefComparator";

  fn compare(&self, a: &IntsRef<AV>, b: &IntsRef<AV>) -> Result<i32> {
    with_other!(a.ints, b.ints, |a_bytes, b_bytes| {
      let a_end = a
        .offset
        .checked_add(a.length)
        .ok_or_else(|| LuceneError::illegal_argument("offset + length overflow"))?;
      let a_slice = a_bytes.get(a.offset..a_end).ok_or_else(|| {
        LuceneError::array_index_out_of_bounds("Offset and length exceed vector bounds")
      })?;
      let b_end = b
        .offset
        .checked_add(b.length)
        .ok_or_else(|| LuceneError::illegal_argument("offset + length overflow"))?;
      let b_slice = b_bytes.get(b.offset..b_end).ok_or_else(|| {
        LuceneError::array_index_out_of_bounds("Offset and length exceed vector bounds")
      })?;
      Ok(a_slice.cmp(b_slice).to_int())
    })
  }
}
impl<AV> Display for IntsRef<AV>
where
  AV: SharedAccessVec<i32>,
{
  fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
    self.ints.access(|ints| {
      let slice = &ints[self.offset..(self.offset + self.length)];
      write!(f, "[")?;
      for (i, v) in slice.iter().enumerate() {
        if i > 0 {
          write!(f, " ")?;
        }
        write!(f, "{v:x}")?;
      }
      write!(f, "]")?;
      Ok(())
    })
  }
}
impl<AV> HashCode for IntsRef<AV>
where
  AV: SharedAccessVec<i32>,
{
  fn hash_code(&self) -> i32 {
    const PRIME: i32 = 31;
    let mut result: i32 = 0;
    for i in self.offset..self.offset + self.length {
      self.ints.access(|ints| {
        result = result.wrapping_mul(PRIME).wrapping_add(ints[i]);
      });
    }
    result
  }
}