pmcgleenon commented on code in PR #204: URL: https://github.com/apache/datasketches-rust/pull/204#discussion_r3847029909
########## datasketches/src/req/sketch.rs: ########## @@ -0,0 +1,833 @@ +// 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. + +//! REQ sketch — generic over `T: ReqValue`. + +use std::fmt; + +use super::DEFAULT_K; +use super::MAX_K; +use super::MIN_K; +use super::RankAccuracy; +use super::SearchCriteria; +use super::compactor::Compactor; +use super::iter::ReqSketchIterator; +use super::sorted_view::SortedView; +use super::value::ReqValue; +use crate::error::Error; + +/// A Relative Error Quantiles sketch for approximate quantile estimation. +/// +/// See the [module-level documentation](super) for background. +#[derive(Debug, Clone)] +pub struct ReqSketch<T: ReqValue> { + pub(super) k: u16, + pub(super) rank_accuracy: RankAccuracy, + pub(super) n: u64, + pub(super) max_nom_size: u32, + pub(super) num_retained: u32, + pub(super) compactors: Vec<Compactor<T>>, + pub(super) promotion_buf: Vec<T>, + pub(super) min_item: Option<T>, + pub(super) max_item: Option<T>, +} + +impl<T: ReqValue> ReqSketch<T> { + /// Creates a new sketch with default parameters (`k = 12`, `RankAccuracy::HighRank`). + pub fn new() -> Self { + let mut s = Self { + k: DEFAULT_K, + rank_accuracy: RankAccuracy::HighRank, + n: 0, + max_nom_size: 0, + num_retained: 0, + compactors: Vec::new(), + promotion_buf: Vec::with_capacity(DEFAULT_K as usize), + min_item: None, + max_item: None, + }; + // C++ parity: an empty sketch has a level-0 compactor present from the start. + // This makes is_raw_items() and flags_byte() byte-compatible with the C++/Java + // wire format for the empty case. + s.grow(); + s + } + + /// Creates a new sketch with the given `k` and rank accuracy. + /// + /// # Errors + /// + /// Returns an error if `k` is odd or outside `[MIN_K, MAX_K]`. + pub fn try_new(k: u16, rank_accuracy: RankAccuracy) -> Result<Self, Error> { + if !(MIN_K..=MAX_K).contains(&k) { + return Err(Error::invalid_argument(format!( + "k must be in [{}, {}], got {k}", + MIN_K, MAX_K + ))); + } + if k % 2 != 0 { + return Err(Error::invalid_argument(format!("k must be even, got {k}"))); + } + let mut s = Self { + k, + rank_accuracy, + n: 0, + max_nom_size: 0, + num_retained: 0, + compactors: Vec::new(), + promotion_buf: Vec::with_capacity(k as usize), + min_item: None, + max_item: None, + }; + s.grow(); + Ok(s) + } + + /// Returns a builder for chained configuration. + pub fn builder() -> ReqSketchBuilder<T> { + ReqSketchBuilder::new() + } + + /// Returns the configured `k` parameter. + pub fn k(&self) -> u16 { + self.k + } + + /// Returns the configured rank accuracy. + pub fn rank_accuracy(&self) -> RankAccuracy { + self.rank_accuracy + } + + /// Returns the total number of items observed (matches C++ `get_n`). + pub fn n(&self) -> u64 { + self.n + } + + /// Returns true if the sketch has observed no items. + pub fn is_empty(&self) -> bool { + self.n == 0 + } + + /// Returns true if compaction has occurred. + pub fn is_estimation_mode(&self) -> bool { + self.compactors.len() > 1 + } + + /// Returns the number of items currently stored across all compactors. + pub fn num_retained(&self) -> u32 { + self.num_retained + } + + /// Returns the smallest item ever observed, or `None` if empty. + pub fn min_item(&self) -> Option<&T> { + self.min_item.as_ref() + } + + /// Returns the largest item ever observed, or `None` if empty. + pub fn max_item(&self) -> Option<&T> { + self.max_item.as_ref() + } + + /// Updates the sketch with a new item. + /// + /// NaN inputs are silently ignored for floating-point types, matching the behavior + /// of the Java reference implementation (`checkNaNUpdate`). This is intentional and + /// documented in the cross-language differences doc. Review Comment: Have removed the reference here https://github.com/apache/datasketches-rust/pull/204/changes/d5f9d2f08890160b4372f62ca0fa74d8c27e3296 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
