rinq 0.1.0

Type-safe, zero-cost LINQ-inspired query engine for Rust — filter, sort, aggregate, window analytics, parallel execution, and statistical extensions.
Documentation 
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
121
122
123
124
125
126
127
128
129
130

//! # rinq — Rust Integrated Query
//!
//! A type-safe, zero-cost LINQ-inspired query engine for Rust.
//!
//! `rinq` lets you compose filter → sort → aggregate pipelines over any
//! in-memory collection using a fluent builder API.  The type-state pattern
//! encodes the valid operation order at compile time, so invalid chains
//! (e.g. calling `order_by` after `select`) are rejected without runtime
//! overhead.
//!
//! ## Quick Start
//!
//! ```rust
//! use rinq::QueryBuilder;
//!
//! let total: i32 = QueryBuilder::from(vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
//!     .where_(|x| x % 2 == 0)   // keep evens
//!     .order_by(|x| *x)          // sort ascending
//!     .sum();                    // terminal — evaluates the pipeline
//!
//! assert_eq!(total, 30);
//! ```
//!
//! ## State Machine
//!
//! Every `QueryBuilder<T, State>` carries a compile-time state that restricts
//! which methods are available:
//!
//! | State | Available transitions |
//! |---|---|
//! | [`Initial`] | `where_`, `take`, `skip`, `flat_map`, `order_by`, `group_by`, … |
//! | [`Filtered`] | same as `Initial` plus `select` |
//! | [`Sorted`] | `then_by`, `then_by_descending`, plus all terminal ops |
//! | [`Projected<U>`] | `collect()` only |
//!
//! ## Feature Flags
//!
//! | Feature | What it enables |
//! |---|---|
//! | `parallel` | [`ParallelQueryBuilder`] via [rayon](https://docs.rs/rayon) |
//! | `serde` | [`QueryBuilder::from_json`] deserialization via [serde_json](https://docs.rs/serde_json) |
//!
//! Enable features in your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! rinq = { version = "3", features = ["parallel", "serde"] }
//! ```
//!
//! ## Statistical Extensions
//!
//! For descriptive statistics, correlation, regression, sampling, and
//! validation, see the companion crate
//! [`rinq-stats`](https://docs.rs/rinq-stats).

#![warn(missing_docs)]

/// Internal support module for code generated by `rinq_syntax::query!`.
///
/// **Do not use directly.** This module is `pub` only to allow generated code
/// to access it via `::rinq::__macro_support::from(...)`.
#[doc(hidden)]
pub mod __macro_support;
pub mod core;
/// Convenience macros: [`rinq_explain!`] for timing and [`pred!`] for predicate shorthand.
pub mod macros;
pub mod metrics;
#[cfg(feature = "parallel")]
pub mod parallel;
#[cfg(feature = "serde")]
pub mod serde;

pub use core::builder::{IntoQuery, QueryBuilder, Queryable};
pub use core::error::{RinqError, RinqResult};
pub use core::state::{Filtered, Initial, Projected, Sorted};
pub use core::try_builder::TryQueryBuilder;
pub use metrics::builder::MetricsQueryBuilder;
pub use metrics::collector::MetricsCollector;
#[cfg(feature = "parallel")]
pub use parallel::ParallelQueryBuilder;

/// A query in the initial state, created directly from a collection.
///
/// This is the starting point for building a query pipeline.
/// From here you can call `where_`, `order_by`, `flat_map`, and other operations.
///
/// # Examples
///
/// ```rust
/// use rinq::{QueryBuilder, InitialQuery};
///
/// fn make_range(start: i32, end: i32) -> InitialQuery<i32> {
///     QueryBuilder::range(start..end)
/// }
///
/// let result: Vec<i32> = make_range(1, 6).where_(|x| x % 2 == 0).collect();
/// assert_eq!(result, vec![2, 4]);
/// ```
pub type InitialQuery<T> = QueryBuilder<T, Initial>;

/// A query in the filtered (chainable intermediate) state.
///
/// Most operations return a `FilteredQuery<T>`. This state supports
/// `where_`, `select`, `order_by`, and all terminal operations.
///
/// # Examples
///
/// ```rust
/// use rinq::{QueryBuilder, FilteredQuery};
///
/// fn get_adults(users: Vec<u32>) -> FilteredQuery<u32> {
///     QueryBuilder::from(users).where_(|&age| age >= 18)
/// }
///
/// let result: Vec<u32> = get_adults(vec![10, 18, 25, 15]).collect();
/// assert_eq!(result, vec![18, 25]);
/// ```
pub type FilteredQuery<T> = QueryBuilder<T, Filtered>;

/// A query in the sorted state.
///
/// Created after calling `order_by` or `order_by_descending`. From here
/// you can call `then_by`, `then_by_descending`, or any terminal operation.
pub type SortedQuery<T> = QueryBuilder<T, Sorted>;

/// A query in the projected state, ready for final collection.
///
/// Created after calling `select`. The only available operation is `collect()`.
/// The type parameter `U` is the projected (output) element type.
pub type ProjectedQuery<U> = QueryBuilder<U, Projected<U>>;