darwen 1.3.0

A relational algebra library for Rust
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
131
132
133
134

//! Darwen is an in-memory engine for relational algebra.
//!
//! The project is inspired by *The Third Manifesto* by Date, Codd, and
//! Darwen, and focuses on a compact in-memory model for experimenting with
//! relational operators.
//!
//! # Example
//!
//! ```rust
//! use darwen::{
//!     heading,
//!     tuple,
//!     prelude::{
//!         AttributeName, HeadingBuilder, Predicate, RelationBuilder, Scalar,
//!         ScalarType, TupleBuilder,
//!     },
//! };
//!
//! let users = RelationBuilder::new()
//!     .with_heading(heading!(name = ScalarType::String, age = ScalarType::Integer)?)
//!     .with_body(vec![
//!         tuple!(name = "Monica", age = 18)?,
//!         tuple!(name = "Erica", age = 19)?,
//!         tuple!(name = "Rita", age = 20)?,
//!         tuple!(name = "Tina", age = 21)?,
//!         tuple!(name = "Sandra", age = 22)?,
//!         tuple!(name = "Mary", age = 23)?,
//!         tuple!(name = "Jessica", age = 18)?,
//!     ])
//!     .build()?;
//!
//! let adults = users.restrict(&Predicate::gt(
//!     AttributeName::from("age"),
//!     Scalar::Integer(20),
//! ))?;
//!
//! let expected = RelationBuilder::new()
//!     .with_heading(heading!(name = ScalarType::String, age = ScalarType::Integer)?)
//!     .with_body(vec![
//!         tuple!(name = "Tina", age = 21)?,
//!         tuple!(name = "Sandra", age = 22)?,
//!         tuple!(name = "Mary", age = 23)?,
//!     ])
//!     .build()?;
//!
//! assert_eq!(adults, expected);
//! # Ok::<(), darwen::prelude::Error>(())
//! ```
//!
//! # Predicates
//!
//! Darwen supports six predicate forms:
//!
//! - [`Predicate::Not`] / [`Predicate::not`] negates another predicate.
//! - [`Predicate::And`] / [`Predicate::and`] performs logical conjunction;
//!   both sides are always evaluated and errors are not hidden.
//! - [`Predicate::Or`] / [`Predicate::or`] performs logical disjunction;
//!   both sides are always evaluated and errors are not hidden.
//! - [`Predicate::Eq`] / [`Predicate::eq`] compares two operands for equality;
//!   only `INTEGER = INTEGER`, `BOOLEAN = BOOLEAN`, `STRING = STRING`, and
//!   `BINARY = BINARY` are valid. Mixed-type comparisons return an error.
//! - [`Predicate::Gt`] / [`Predicate::gt`] compares two operands with `>`;
//!   only `INTEGER > INTEGER` is valid. All other comparisons return an error.
//! - [`Predicate::Lt`] / [`Predicate::lt`] compares two operands with `<`;
//!   only `INTEGER < INTEGER` is valid. All other comparisons return an error.
//!
//! # Operators
//!
//! ## Restrict
//!
//! [`Relation::restrict`] implements selection (`σ`) and returns only tuples
//! that satisfy a [`Predicate`].
//!
//! ## Project
//!
//! [`Relation::project`] implements projection (`π`) and keeps only the
//! requested attributes.
//!
//! ## Rename
//!
//! [`Relation::rename`] implements renaming (`ρ`) and changes attribute names
//! according to a mapping.
//!
//! ## Union
//!
//! [`Relation::union`] implements union (`⋃`) for relations with identical
//! headings.
//!
//! ## Difference
//!
//! [`Relation::difference`] implements difference (`−`) for relations with
//! identical headings.
//!
//! ## Product
//!
//! [`Relation::product`] implements Cartesian product (`×`) for relations with
//! disjoint headings.
//!
//! ## Join
//!
//! [`Relation::join`] implements natural join (`⋈`) on shared attributes.
//!
//! ## Intersect
//!
//! [`Relation::intersect`] implements intersection (`∩`) for relations with
//! identical headings.
//!
//! ## Divide
//!
//! [`Relation::divide`] implements relational division (`÷`).
mod error;
mod ops;
mod types;

pub use crate::types::heading::{Heading, HeadingBuilder};
pub use crate::types::predicate::{Expression, Predicate};
pub use crate::types::relation::{Relation, RelationBuilder};
pub use crate::types::scalar::{Scalar, ScalarType};
pub use crate::types::tuple::{Tuple, TupleBuilder};
pub use crate::types::AttributeName;

pub use crate::error::Error;

/// Convenient re-exports for the public relational algebra API.
pub mod prelude {
    pub use crate::types::heading::{Heading, HeadingBuilder};
    pub use crate::types::predicate::{Expression, Predicate};
    pub use crate::types::relation::{Relation, RelationBuilder};
    pub use crate::types::scalar::{Scalar, ScalarType};
    pub use crate::types::tuple::{Tuple, TupleBuilder};
    pub use crate::types::AttributeName;

    pub use crate::error::Error;
}