fp_library/lib.rs
1#![forbid(unsafe_code)]
2#![warn(missing_docs)]
3#![allow(clippy::tabs_in_doc_comments)]
4
5//! # fp-library
6//!
7//! A functional programming library for Rust featuring your favourite higher-kinded types and type classes.
8//!
9//! ## Motivation
10//!
11//! Rust is a multi-paradigm language with strong functional programming features like iterators, closures, and algebraic data types. However, it lacks native support for **Higher-Kinded Types (HKT)**, which limits the ability to write generic code that abstracts over type constructors (e.g., writing a function that works for any `Monad`, whether it's `Option`, `Result`, or `Vec`).
12//!
13//! `fp-library` aims to bridge this gap by providing:
14//!
15//! 1. A robust encoding of HKTs in stable Rust.
16//! 2. A comprehensive set of standard type classes (`Functor`, `Monad`, `Traversable`, etc.).
17//! 3. Zero-cost abstractions that respect Rust's performance characteristics.
18//!
19//! ## Examples
20//!
21//! ### Using `Functor` with `Option`
22//!
23//! The brand is inferred automatically from the container type:
24//!
25//! ```
26//! use fp_library::functions::*;
27//!
28//! // Brand inferred from Option<i32>
29//! let y = map(|i: i32| i * 2, Some(5));
30//! assert_eq!(y, Some(10));
31//!
32//! // Brand inferred from &Vec<i32> (by-reference dispatch)
33//! let v = vec![1, 2, 3];
34//! let y = map(|i: &i32| *i + 10, &v);
35//! assert_eq!(y, vec![11, 12, 13]);
36//! ```
37//!
38//! For types with multiple brands (e.g., `Result`), use the `explicit` variant:
39//!
40//! ```
41//! use fp_library::{
42//! brands::*,
43//! functions::explicit::*,
44//! };
45//!
46//! let y = map::<ResultErrAppliedBrand<&str>, _, _, _, _>(|i| i * 2, Ok::<i32, &str>(5));
47//! assert_eq!(y, Ok(10));
48//! ```
49//!
50//! ### Monadic Do-Notation with `m_do!`
51//!
52//! The `m_do!` macro provides Haskell/PureScript-style do-notation for flat monadic code.
53//! It desugars `<-` binds into nested [`bind`](functions::bind) calls.
54//!
55//! ```
56//! use fp_library::{brands::*, functions::*, m_do};
57//!
58//! // Inferred mode: brand inferred from container types
59//! let result = m_do!({
60//! x <- Some(5);
61//! y <- Some(x + 1);
62//! let z = x * y;
63//! Some(z)
64//! });
65//! assert_eq!(result, Some(30));
66//!
67//! // Explicit mode: for ambiguous types or when pure() is needed
68//! let result = m_do!(VecBrand {
69//! x <- vec![1, 2];
70//! y <- vec![10, 20];
71//! pure(x + y)
72//! });
73//! assert_eq!(result, vec![11, 21, 12, 22]);
74//! ```
75#![doc = include_str!("../docs/features.md")]
76//!
77//! ## How it Works
78#![doc = include_str!("../docs/hkt.md")]
79#![doc = include_str!("../docs/brand-inference.md")]
80#![doc = include_str!("../docs/dispatch.md")]
81#![doc = include_str!("../docs/zero-cost.md")]
82#![doc = include_str!("../docs/pointer-abstraction.md")]
83#![doc = include_str!("../docs/lazy-evaluation.md")]
84#![doc = include_str!("../docs/parallelism.md")]
85//!
86//! ## Crate Features
87//!
88//! - **`rayon`**: Enables true parallel execution for `par_*` functions using the [rayon](https://github.com/rayon-rs/rayon) library. Without this feature, `par_*` functions fall back to sequential equivalents.
89//! - **`serde`**: Enables serialization and deserialization support for pure data types using the [serde](https://github.com/serde-rs/serde) library.
90//! - **`stacker`**: Enables adaptive stack growth for deep `Coyoneda`, `RcCoyoneda`, and `ArcCoyoneda` map chains via the [stacker](https://github.com/rust-lang/stacker) crate. Without this feature, deeply chained maps can overflow the stack.
91
92extern crate fp_macros;
93
94pub mod brands;
95pub mod classes;
96pub mod dispatch;
97pub mod functions;
98pub mod kinds;
99pub mod types;
100pub(crate) mod utils;
101
102pub use fp_macros::*;