Profunctor Family

Signature

/// A profunctor is contravariant in its first argument and covariant in its second.
pub trait Profunctor: HKT2 {
    fn dimap<A: 'static, B: 'static, C, D>(
        f: impl Fn(C) -> A + 'static,
        g: impl Fn(B) -> D + 'static,
        pab: Self::P<A, B>,
    ) -> Self::P<C, D>;

    fn lmap<A: 'static, B: 'static, C>(
        f: impl Fn(C) -> A + 'static,
        pab: Self::P<A, B>,
    ) -> Self::P<C, B> { ... }

    fn rmap<A: 'static, B: 'static, D>(
        g: impl Fn(B) -> D + 'static,
        pab: Self::P<A, B>,
    ) -> Self::P<A, D> { ... }
}

dimap is the fundamental operation. It takes a function f: C -> A that pre-processes the input (contravariant -- note the reversed direction) and a function g: B -> D that post-processes the output (covariant), then adapts the profunctor P<A, B> into P<C, D>.

The convenience methods lmap and rmap have default implementations in terms of dimap:

• lmap(f, pab) -- pre-process the input only. Equivalent to dimap(f, |b| b, pab).
• rmap(g, pab) -- post-process the output only. Equivalent to dimap(|a| a, g, pab).

Laws

P::dimap(|a| a, |b| b, pab) == pab

P::dimap(|a| f(g(a)), |b| h(i(b)), pab)
    == P::dimap(g, h, P::dimap(f, i, pab))

Instances

Examples

use karpal_profunctor::{Profunctor, FnP};

// A simple doubling function as a profunctor value
let double: Box<dyn Fn(i32) -> i32> = Box::new(|x| x * 2);

// dimap: parse a string to i32 on the input side,
//        format the i32 result to a string on the output side
let f = FnP::dimap(
    |s: &str| s.len() as i32,  // contravariant: &str -> i32
    |n: i32| n.to_string(),     // covariant: i32 -> String
    double,
);
assert_eq!(f("hello"), "10"); // len("hello") = 5, doubled = 10

// lmap: only pre-process the input
let negate: Box<dyn Fn(i32) -> i32> = Box::new(|x| -x);
let neg_len = FnP::lmap(|s: &str| s.len() as i32, negate);
assert_eq!(neg_len("hi"), -2);

// rmap: only post-process the output
let add_one: Box<dyn Fn(i32) -> i32> = Box::new(|x| x + 1);
let as_string = FnP::rmap(|n: i32| format!("result: {}", n), add_one);
assert_eq!(as_string(9), "result: 10");

Signature

pub trait Strong: Profunctor {
    fn first<A, B, C>(pab: Self::P<A, B>) -> Self::P<(A, C), (B, C)>
    where
        A: 'static,
        B: 'static,
        C: 'static;

    fn second<A, B, C>(pab: Self::P<A, B>) -> Self::P<(C, A), (C, B)>
    where
        A: 'static,
        B: 'static,
        C: 'static;
}

first takes a profunctor P<A, B> and lifts it to operate on the first component of a tuple, passing the second component C through unchanged. second does the mirror image -- it operates on the second component and passes the first through.

Laws

P::lmap(|(a, _)| a, P::first(pab))
    == P::rmap(|b| (b, ()), pab)  // up to isomorphism with unit

P::first(P::first(pab))
    == P::dimap(
        |((a, c1), c2)| (a, (c1, c2)),  // reassociate in
        |(b, (c1, c2))| ((b, c1), c2),  // reassociate out
        P::first(pab),
    )

Instances

TaggedF is deliberately not Strong. This enforces at the type level that write-only optics (like Review) cannot be used for reading -- Strong requires producing a (B, C) from a B, but TaggedF has no way to produce the C.

Connection to Lens

A Lens is defined as a function that works for all profunctors that are Strong. The lens transform method takes a P<A, B> and returns a P<S, T> by using Strong::first (or second) together with Profunctor::dimap to focus on a part of a structure:

// Conceptually, a lens from S to A (with update types T and B) is:
//   for all P: Strong, P<A, B> -> P<S, T>
//
// Implemented as:
//   dimap(getter_and_context, setter, first(pab))
//
// where:
//   getter_and_context: S -> (A, Context)
//   setter: (B, Context) -> T

Strong::first lifts the profunctor to work on a tuple (A, Context), and dimap adapts the outer structure S/T to and from that tuple. This is how profunctor optics achieve composability -- lens composition is just function composition of these transforms.

Examples

use karpal_profunctor::{Strong, FnP};

let double: Box<dyn Fn(i32) -> i32> = Box::new(|x| x * 2);

// first: apply to the first element of a tuple
let f = FnP::first::<i32, i32, &str>(double);
assert_eq!(f((5, "hi")), (10, "hi"));

// second: apply to the second element of a tuple
let triple: Box<dyn Fn(i32) -> i32> = Box::new(|x| x * 3);
let g = FnP::second::<i32, i32, &str>(triple);
assert_eq!(g(("hi", 5)), ("hi", 15));

Signature

pub trait Choice: Profunctor {
    fn left<A, B, C>(pab: Self::P<A, B>) -> Self::P<Result<A, C>, Result<B, C>>
    where
        A: 'static,
        B: 'static,
        C: 'static;

    fn right<A, B, C>(pab: Self::P<A, B>) -> Self::P<Result<C, A>, Result<C, B>>
    where
        A: 'static,
        B: 'static,
        C: 'static;
}

Karpal uses Result<L, R> as the sum type rather than a custom Either -- this is idiomatic Rust and avoids an unnecessary new type. left lifts a profunctor to operate on the Ok branch of a Result, passing the Err branch through unchanged. right does the mirror image, operating on the Err branch.

Laws

P::lmap(|a| Ok(a), P::left(pab))
    == P::rmap(|b| Ok(b), pab)

P::left(P::left(pab))
    == P::dimap(
        |r| match r {                       // reassociate in
            Ok(Ok(a))  => Ok(a),
            Ok(Err(c)) => Err(Ok(c)),
            Err(d)     => Err(Err(d)),
        },
        |r| match r {                       // reassociate out
            Ok(b)      => Ok(Ok(b)),
            Err(Ok(c)) => Ok(Err(c)),
            Err(Err(d)) => Err(d),
        },
        P::left(pab),
    )

Instances

ForgetF's Choice impl requires R: Monoid because the miss case needs a default value (R::empty()). Its Strong impl has no such restriction -- products always have the focus available.

Connection to Prism

A Prism is defined as a function that works for all profunctors that are Choice. The prism transform method takes a P<A, B> and returns a P<S, T> by using Choice::right together with Profunctor::dimap to focus on one variant of a sum type:

// Conceptually, a prism from S to A (with update types T and B) is:
//   for all P: Choice, P<A, B> -> P<S, T>
//
// Implemented as:
//   dimap(match_, merge, right(pab))
//
// where:
//   match_: S -> Result<T, A>   (try to extract A, or return T unchanged)
//   merge:  Result<T, B> -> T   (re-inject the modified value)

When the match_ function successfully extracts an A, the profunctor processes it into a B; otherwise the original T passes through untouched. Choice::right ensures that only the matched branch is transformed. This is the dual of how Strong powers lenses: lenses focus through products, prisms focus through sums.

Examples

use karpal_profunctor::{Choice, FnP};

let double: Box<dyn Fn(i32) -> i32> = Box::new(|x| x * 2);

// left: apply to the Ok branch
let f = FnP::left::<i32, i32, &str>(double);
assert_eq!(f(Ok(5)), Ok(10));
assert_eq!(f(Err("nope")), Err("nope"));

// right: apply to the Err branch
let triple: Box<dyn Fn(i32) -> i32> = Box::new(|x| x * 3);
let g = FnP::right::<i32, i32, &str>(triple);
assert_eq!(g(Err(5)), Err(15));
assert_eq!(g(Ok("yep")), Ok("yep"));

Definition

pub struct FnP;

impl HKT2 for FnP {
    type P<A, B> = Box<dyn Fn(A) -> B>;
}

FnP is a zero-sized marker type. It has no fields and no runtime cost -- it exists solely to carry the HKT2 type-level association between the marker and the concrete type Box<dyn Fn(A) -> B>.

This is the function arrow profunctor (sometimes written (->) in Haskell). It is the most natural profunctor: a function from A to B can be pre-composed with a function C -> A (contravariant input) and post-composed with a function B -> D (covariant output) to yield a function C -> D.

Feature gate

FnP requires the alloc feature because Box<dyn Fn> requires heap allocation. It is not available in no_std environments without an allocator. The Profunctor, Strong, and Choice traits themselves are no_std-compatible -- only the FnP instance needs alloc.

Implemented traits

Role in optics

FnP is the profunctor that optics use at the value level. When you call lens.set() or lens.over(), Karpal internally constructs a Box<dyn Fn(A) -> B> and passes it through the lens's transform method, which threads it through Strong::first and Profunctor::dimap. The result is a Box<dyn Fn(S) -> T> that performs the focused update on the whole structure. The same mechanism applies to prisms via Choice.

Because all the profunctor operations compose (they are just function wrapping), lens composition and prism composition are both achieved by chaining transform calls -- no special composition machinery is needed.

Example: building a pipeline with dimap

use karpal_profunctor::{Profunctor, FnP};

// Start with a base function: parse a number and add 1
let inc: Box<dyn Fn(i32) -> i32> = Box::new(|x| x + 1);

// Adapt it: input is a string (parse it), output is a string (format it)
let pipeline = FnP::dimap(
    |s: &str| s.parse::<i32>().unwrap_or(0),
    |n: i32| format!("result = {}", n),
    inc,
);

assert_eq!(pipeline("41"), "result = 42");
assert_eq!(pipeline("not a number"), "result = 1");

Signature

pub trait Traversing: Strong + Choice {
    fn wander<S, T, A, B>(
        get_all: impl Fn(&S) -> Vec<A> + 'static,
        modify_all: impl Fn(S, &dyn Fn(A) -> B) -> T + 'static,
        pab: Self::P<A, B>,
    ) -> Self::P<S, T>
    where
        S: 'static, T: 'static, A: 'static, B: 'static;
}

Traversing extends Strong + Choice with the ability to handle multiple foci. The wander method takes two functions instead of a single polymorphic traversal function, because Rust lacks rank-2 types:

• get_all -- extracts all foci (used by read-only profunctors like ForgetF)
• modify_all -- applies a function to every focus in-place (used by read-write profunctors like FnP)

Instances

Connection to Traversal

A Traversal is defined as a function that works for all profunctors that are Traversing. The traversal's transform method calls P::wander(get_all, modify_all, pab) -- each profunctor instance decides how to interpret the traversal.

Example

use karpal_profunctor::{Traversing, FnP, ForgetF};

// wander with FnP: modify each element
let double: Box<dyn Fn(i32) -> i32> = Box::new(|x| x * 2);
let f = FnP::wander(
    |v: &Vec<i32>| v.clone(),
    |v: Vec<i32>, f: &dyn Fn(i32) -> i32| v.into_iter().map(f).collect(),
    double,
);
assert_eq!(f(vec![1, 2, 3]), vec![2, 4, 6]);

// wander with ForgetF: accumulate with Monoid
let to_str: Box<dyn Fn(i32) -> String> = Box::new(|x| x.to_string());
let g = <ForgetF<String> as Traversing>::wander(
    |v: &Vec<i32>| v.clone(),
    |v: Vec<i32>, f: &dyn Fn(i32) -> String| { let _ = v; let _ = f; String::new() },
    to_str,
);
assert_eq!(g(vec![1, 2, 3]), "123"); // String Monoid concatenates

Definition

pub struct ForgetF<R>(PhantomData<R>);

impl<R: 'static> HKT2 for ForgetF<R> {
    type P<A, B> = Box<dyn Fn(A) -> R>;
}

ForgetF<R> "forgets" the output type B entirely -- the second type parameter is phantom. A ForgetF<R>::P<A, B> is just a function from A to R, regardless of what B is. This makes it ideal for read-only operations that extract or summarize data.

Implemented traits

Feature gate

Requires alloc (uses Box<dyn Fn> and Vec).

Role in optics

ForgetF is the profunctor behind read-only optics. When you use a Traversal with ForgetF<R>, you get a function S -> R that extracts and combines data from all foci using a Monoid. This is how Fold's fold_map works conceptually.

use karpal_profunctor::ForgetF;

// ForgetF ignores the B parameter completely
let extract: Box<dyn Fn(i32) -> String> = Box::new(|x| format!("got {x}"));

// B can be anything -- it's never used
let _: <ForgetF<String> as HKT2>::P<i32, Vec<u8>> = extract;

Definition

pub struct TaggedF;

impl HKT2 for TaggedF {
    type P<A, B> = B;
}

TaggedF "forgets" the input type A entirely -- the first type parameter is phantom. A TaggedF::P<A, B> is just B, regardless of what A is. This makes it ideal for construction-only operations.

Implemented traits

TaggedF is deliberately not Strong and not Traversing. This is a deliberate design decision: Strong::first would need to produce a (B, C) from just a B, which is impossible without access to C. By not implementing Strong, the type system enforces that write-only optics like Review cannot be used for reading.

Feature gate

None -- TaggedF is no_std-compatible with no allocator requirement.

Role in optics

TaggedF is the profunctor behind write-only optics. A Review conceptually transforms a TaggedF::P<A, B> (which is just B) into a TaggedF::P<S, T> (which is just T) -- construction from a value.