Improve Range Minimum Query Implementation (TheAlgorithms#834)

ref: improve rmq Co-authored-by: Piotr Idzik <65706193+vil02@users.noreply.github.com>

Author: sozelfist

src/data_structures/range_minimum_query.rs

@@ -1,133 +1,194 @@
-/*
- A RangeMinimumQuery, is a data structure for answering range-minimum-queries of an array.
- For a given array A[], of elements for which an ordering exists, we want to find the
- minimum value A[x] of a subarray A[i..j], where i and j are the query parameters.
-
- Precomputation complexity: O(n log(n))
- Query complexity: O(1)
-
- Wikipedia: <https://en.wikipedia.org/wiki/Range_minimum_query>
-*/
+//! Range Minimum Query (RMQ) Implementation
+//!
+//! This module provides an efficient implementation of a Range Minimum Query data structure using a
+//! sparse table approach. It allows for quick retrieval of the minimum value within a specified subdata
+//! of a given data after an initial preprocessing phase.
+//!
+//! The RMQ is particularly useful in scenarios requiring multiple queries on static data, as it
+//! allows querying in constant time after an O(n log(n)) preprocessing time.
+//!
+//! References: [Wikipedia](https://en.wikipedia.org/wiki/Range_minimum_query)
 
 use std::cmp::PartialOrd;
-use std::fmt;
 
-/// Custom error for invalid range
-#[derive(Debug, PartialEq)]
-pub struct RangeError;
-
-impl fmt::Display for RangeError {
- fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
- write!(f, "Invalid range")
- }
+/// Custom error type for invalid range queries.
+#[derive(Debug, PartialEq, Eq)]
+pub enum RangeError {
+ /// Indicates that the provided range is invalid (start index is not less than end index).
+ InvalidRange,
+ /// Indicates that one or more indices are out of bounds for the data.
+ IndexOutOfBound,
 }
 
+/// A data structure for efficiently answering range minimum queries on static data.
 pub struct RangeMinimumQuery<T: PartialOrd + Copy> {
- // the current version makes a copy of the input array, but this could be changed
- // to references if needed (in that case, we dont need T to implement the Copy trait)
- array: Vec<T>,
+ /// The original input data on which range queries are performed.
+ data: Vec<T>,
+ /// The sparse table for storing preprocessed range minimum information. Each entry
+ /// contains the index of the minimum element in the range starting at `j` and having a length of `2^i`.
  sparse_table: Vec<Vec<usize>>,
 }
 
 impl<T: PartialOrd + Copy> RangeMinimumQuery<T> {
+ /// Creates a new `RangeMinimumQuery` instance with the provided input data.
+ ///
+ /// # Arguments
+ ///
+ /// * `input` - A slice of elements of type `T` that implement `PartialOrd` and `Copy`.
+ ///
+ /// # Returns
+ ///
+ /// A `RangeMinimumQuery` instance that can be used to perform range minimum queries.
  pub fn new(input: &[T]) -> RangeMinimumQuery<T> {
  RangeMinimumQuery {
- array: input.to_vec(),
+ data: input.to_vec(),
  sparse_table: build_sparse_table(input),
  }
  }
 
+ /// Retrieves the minimum value in the specified range [start, end).
+ ///
+ /// # Arguments
+ ///
+ /// * `start` - The starting index of the range (inclusive).
+ /// * `end` - The ending index of the range (exclusive).
+ ///
+ /// # Returns
+ ///
+ /// * `Ok(T)` - The minimum value found in the specified range.
+ /// * `Err(RangeError)` - An error indicating the reason for failure, such as an invalid range
+ /// or indices out of bounds.
  pub fn get_range_min(&self, start: usize, end: usize) -> Result<T, RangeError> {
- if start >= end || start >= self.array.len() || end > self.array.len() {
- return Err(RangeError);
+ // Validate range
+ if start >= end {
+ return Err(RangeError::InvalidRange);
  }
- let loglen = (end - start).ilog2() as usize;
- let idx: usize = end - (1 << loglen);
- let a = self.sparse_table[loglen][start];
- let b = self.sparse_table[loglen][idx];
- if self.array[a] < self.array[b] {
- return Ok(self.array[a]);
+ if start >= self.data.len() || end > self.data.len() {
+ return Err(RangeError::IndexOutOfBound);
+ }
+
+ // Calculate the log length and the index for the sparse table
+ let log_len = (end - start).ilog2() as usize;
+ let idx: usize = end - (1 << log_len);
+
+ // Retrieve the indices of the minimum values from the sparse table
+ let min_idx_start = self.sparse_table[log_len][start];
+ let min_idx_end = self.sparse_table[log_len][idx];
+
+ // Compare the values at the retrieved indices and return the minimum
+ if self.data[min_idx_start] < self.data[min_idx_end] {
+ Ok(self.data[min_idx_start])
+ } else {
+ Ok(self.data[min_idx_end])
  }
- Ok(self.array[b])
  }
 }
 
-fn build_sparse_table<T: PartialOrd>(array: &[T]) -> Vec<Vec<usize>> {
- let mut table: Vec<Vec<usize>> = vec![(0..array.len()).collect()];
- let len = array.len();
+/// Builds a sparse table for the provided data to support range minimum queries.
+///
+/// # Arguments
+///
+/// * `data` - A slice of elements of type `T` that implement `PartialOrd`.
+///
+/// # Returns
+///
+/// A 2D vector representing the sparse table, where each entry contains the index of the minimum
+/// element in the range defined by the starting index and the power of two lengths.
+fn build_sparse_table<T: PartialOrd>(data: &[T]) -> Vec<Vec<usize>> {
+ let mut sparse_table: Vec<Vec<usize>> = vec![(0..data.len()).collect()];
+ let len = data.len();
 
- for loglen in 1..=len.ilog2() {
+ // Fill the sparse table
+ for log_len in 1..=len.ilog2() {
  let mut row = Vec::new();
- for i in 0..=len - (1 << loglen) {
- let a = table[table.len() - 1][i];
- let b = table[table.len() - 1][i + (1 << (loglen - 1))];
- if array[a] < array[b] {
- row.push(a);
+ for idx in 0..=len - (1 << log_len) {
+ let min_idx_start = sparse_table[sparse_table.len() - 1][idx];
+ let min_idx_end = sparse_table[sparse_table.len() - 1][idx + (1 << (log_len - 1))];
+ if data[min_idx_start] < data[min_idx_end] {
+ row.push(min_idx_start);
  } else {
- row.push(b);
+ row.push(min_idx_end);
  }
  }
- table.push(row);
+ sparse_table.push(row);
  }
- table
+
+ sparse_table
 }
 
 #[cfg(test)]
 mod tests {
- use super::build_sparse_table;
+ use super::*;
+
  macro_rules! test_build_sparse_table {
  ($($name:ident: $inputs:expr,)*) => {
- $(
- #[test]
- fn $name() {
- let (array, expected) = $inputs;
- assert_eq!(build_sparse_table(&array), expected);
- }
- )*
+  $(
+  #[test]
+  fn $name() {
+  let (data, expected) = $inputs;
+  assert_eq!(build_sparse_table(&data), expected);
+  }
+  )*
  }
  }
+
  test_build_sparse_table! {
- small: ([1, 6, 3], vec![vec![0, 1, 2], vec![0, 2]]),
- tc_1: ([1, 3, 6, 123, 7, 235, 3, -4, 6, 2], vec![
- vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
- vec![0, 1, 2, 4, 4, 6, 7, 7, 9],
- vec![0, 1, 2, 6, 7, 7, 7],
- vec![7, 7, 7]
- ]),
- tc_2: ([
- 20, 13, -13, 2, 3634, -2, 56, 3, 67, 8, 23, 0, -23, 1, 5, 85, 3, 24, 5, -10, 3, 4, 20,
- ], vec![
- vec![
- 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21,
- 22
- ],
- vec![1, 2, 2, 3, 5, 5, 7, 7, 9, 9, 11, 12, 12, 13, 14, 16, 16, 18, 19, 19, 20, 21],
- vec![2, 2, 2, 5, 5, 5, 7, 7, 11, 12, 12, 12, 12, 13, 16, 16, 19, 19, 19, 19],
- vec![2, 2, 2, 5, 5, 12, 12, 12, 12, 12, 12, 12, 12, 19, 19, 19],
- vec![12, 12, 12, 12, 12, 12, 12, 12]
- ]),
+ small: (
+ [1, 6, 3],
+ vec![
+ vec![0, 1, 2],
+ vec![0, 2]
+ ]
+ ),
+ medium: (
+ [1, 3, 6, 123, 7, 235, 3, -4, 6, 2],
+ vec![
+ vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+ vec![0, 1, 2, 4, 4, 6, 7, 7, 9],
+ vec![0, 1, 2, 6, 7, 7, 7],
+ vec![7, 7, 7]
+ ]
+ ),
+ large: (
+ [20, 13, -13, 2, 3634, -2, 56, 3, 67, 8, 23, 0, -23, 1, 5, 85, 3, 24, 5, -10, 3, 4, 20],
+ vec![
+ vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22],
+ vec![1, 2, 2, 3, 5, 5, 7, 7, 9, 9, 11, 12, 12, 13, 14, 16, 16, 18, 19, 19, 20, 21],
+ vec![2, 2, 2, 5, 5, 5, 7, 7, 11, 12, 12, 12, 12, 13, 16, 16, 19, 19, 19, 19],
+ vec![2, 2, 2, 5, 5, 12, 12, 12, 12, 12, 12, 12, 12, 19, 19, 19],
+ vec![12, 12, 12, 12, 12, 12, 12, 12]
+ ]
+ ),
  }
 
  #[test]
  fn simple_query_tests() {
- let v1 = vec![1, 3, 6, 123, 7, 235, 3, -4, 6, 2];
- let sparse_v1 = super::RangeMinimumQuery::new(&v1);
-
- assert_eq!(Ok(3), sparse_v1.get_range_min(1, 6));
- assert_eq!(Ok(-4), sparse_v1.get_range_min(0, 10));
- assert_eq!(Ok(6), sparse_v1.get_range_min(8, 9));
- assert!(sparse_v1.get_range_min(4, 3).is_err());
- assert!(sparse_v1.get_range_min(0, 1000).is_err());
- assert!(sparse_v1.get_range_min(1000, 1001).is_err());
+ let rmq = RangeMinimumQuery::new(&[1, 3, 6, 123, 7, 235, 3, -4, 6, 2]);
+
+ assert_eq!(rmq.get_range_min(1, 6), Ok(3));
+ assert_eq!(rmq.get_range_min(0, 10), Ok(-4));
+ assert_eq!(rmq.get_range_min(8, 9), Ok(6));
+ assert_eq!(rmq.get_range_min(4, 3), Err(RangeError::InvalidRange));
+ assert_eq!(rmq.get_range_min(0, 1000), Err(RangeError::IndexOutOfBound));
+ assert_eq!(
+ rmq.get_range_min(1000, 1001),
+ Err(RangeError::IndexOutOfBound)
+ );
  }
 
  #[test]
  fn float_query_tests() {
- let sparse_v1 = super::RangeMinimumQuery::new(&[0.4, -2.3, 0.0, 234.22, 12.2, -3.0]);
+ let rmq = RangeMinimumQuery::new(&[0.4, -2.3, 0.0, 234.22, 12.2, -3.0]);
 
- assert_eq!(Ok(-3.0), sparse_v1.get_range_min(0, 6));
- assert_eq!(Ok(-2.3), sparse_v1.get_range_min(0, 4));
- assert_eq!(Ok(12.2), sparse_v1.get_range_min(3, 5));
- assert_eq!(Ok(0.0), sparse_v1.get_range_min(2, 3));
+ assert_eq!(rmq.get_range_min(0, 6), Ok(-3.0));
+ assert_eq!(rmq.get_range_min(0, 4), Ok(-2.3));
+ assert_eq!(rmq.get_range_min(3, 5), Ok(12.2));
+ assert_eq!(rmq.get_range_min(2, 3), Ok(0.0));
+ assert_eq!(rmq.get_range_min(4, 3), Err(RangeError::InvalidRange));
+ assert_eq!(rmq.get_range_min(0, 1000), Err(RangeError::IndexOutOfBound));
+ assert_eq!(
+ rmq.get_range_min(1000, 1001),
+ Err(RangeError::IndexOutOfBound)
+ );
  }
 }