Struct Prism 

pub struct Prism<S, T, A, B> { /* private fields */ }

A prism focuses on one variant of a sum type.

S — source type, T — modified source type, A — focus type (the variant’s inner value), B — replacement type.

Where a Lens uses Strong to decompose products, a Prism uses Choice to decompose coproducts.

For simple (monomorphic) prisms, use SimplePrism.

Implementations

impl<S, T, A, B> Prism<S, T, A, B>

pub fn new( match_: fn(S) -> Result<A, T>, build: fn(B) -> T, ) -> Prism<S, T, A, B>

Examples found in repository

examples/domain_model_optics.rs (lines 92-98)

fn credit_card_prism() -> SimplePrism<Payment, (String, String)> {
    Prism::new(
        |p| match p {
            Payment::CreditCard { last4, exp } => Ok((last4, exp)),
            other => Err(other),
        },
        |(last4, exp)| Payment::CreditCard { last4, exp },
    )
}

fn wallet_prism() -> SimplePrism<Payment, (String, i64)> {
    Prism::new(
        |p| match p {
            Payment::Wallet {
                provider,
                balance_cents,
            } => Ok((provider, balance_cents)),
            other => Err(other),
        },
        |(provider, balance_cents)| Payment::Wallet {
            provider,
            balance_cents,
        },
    )
}

fn bank_transfer_prism() -> SimplePrism<Payment, String> {
    Prism::new(
        |p| match p {
            Payment::BankTransfer { iban } => Ok(iban),
            other => Err(other),
        },
        |iban| Payment::BankTransfer { iban },
    )
}

pub fn preview(&self, s: &S) -> Option<A>

where S: Clone,

Try to extract the focus. Returns Some(a) if the variant matches.

Examples found in repository

examples/domain_model_optics.rs (line 208)

fn main() {
    println!("=== Domain Model with Optics Example ===\n");

    let order = sample_order();

    // 1. Lens: get/set/over
    println!("--- Lens: basic get/set/over ---");
    let customer = customer_lens();
    let address = address_lens();
    let city = city_lens();

    println!("  Customer name: {}", name_lens().get(&order.customer));
    println!("  City: {}", city.get(&address.get(&customer.get(&order))));

    // 2. Composed Lens: deep access with .then()
    println!("\n--- ComposedLens: deep access with .then() ---");
    let order_city = customer_lens().then(address_lens()).then(city_lens());
    let order_zip = customer_lens().then(address_lens()).then(zip_lens());

    println!("  Order city: {}", order_city.get(&order));
    println!("  Order zip:  {}", order_zip.get(&order));

    // Deep set
    let updated = order_city.set(order.clone(), "Shelbyville".into());
    println!("  After city update: {}", order_city.get(&updated));
    println!("  Original unchanged: {}", order_city.get(&order));

    // Deep over (modify)
    let uppercased = order_city.over(order.clone(), |c| c.to_uppercase());
    println!("  Uppercased city: {}", order_city.get(&uppercased));

    // 3. Lens::transform — reusable update function
    println!("\n--- Lens::transform — reusable update function ---");
    let normalize_city: Box<dyn Fn(String) -> String> = Box::new(|c| c.trim().to_uppercase());
    let normalize_order_city = city_lens().transform::<FnP>(normalize_city);
    let addr = Address {
        street: "456 Oak Ave".into(),
        city: "  new york  ".into(),
        zip: "10001".into(),
    };
    let normalized = normalize_order_city(addr);
    println!("  Normalized city: {:?}", normalized.city);

    // 4. Prism: sum type focus
    println!("\n--- Prism: sum type focus ---");
    let cc = credit_card_prism();
    let wallet = wallet_prism();
    let bank = bank_transfer_prism();

    println!("  Credit card last4: {:?}", cc.preview(&order.payment));
    println!("  Wallet preview:    {:?}", wallet.preview(&order.payment));

    // Prism::review — construct a variant
    let new_payment = wallet.review(("PayPal".into(), 5000));
    println!("  New wallet payment: {:?}", new_payment);

    // Prism::over — modify only if matched
    let updated_payment = cc.over(order.payment.clone(), |(last4, _exp)| {
        (last4, "01/28".into())
    });
    println!("  Updated CC expiry: {:?}", updated_payment);

    // Prism on non-matching variant: passes through unchanged
    let unchanged = wallet.over(order.payment.clone(), |(prov, bal)| (prov, bal + 1000));
    println!("  Wallet over on CC (unchanged): {:?}", unchanged);

    // 5. Prism::transform — reusable pattern-matching function
    println!("\n--- Prism::transform — reusable variant modifier ---");
    let add_balance: Box<dyn Fn((String, i64)) -> (String, i64)> =
        Box::new(|(prov, bal)| (prov, bal + 2500));
    let add_wallet_balance = wallet.transform::<FnP>(add_balance);

    let wallet_payment = Payment::Wallet {
        provider: "PayPal".into(),
        balance_cents: 10000,
    };
    let topped_up = add_wallet_balance(wallet_payment);
    println!("  Topped up: {:?}", topped_up);

    // Apply same transform to non-wallet — passes through
    let still_cc = add_wallet_balance(order.payment.clone());
    println!("  CC unchanged: {:?}", still_cc);

    // 6. Summary: combine multiple optics
    println!("\n--- Combining lenses and prisms ---");
    let orders = vec![
        sample_order(),
        Order {
            id: 1002,
            customer: Customer {
                name: "Bob Jones".into(),
                address: Address {
                    street: "789 Elm St".into(),
                    city: "Capital City".into(),
                    zip: "12345".into(),
                },
            },
            items: vec![Item {
                name: "Mouse".into(),
                price_cents: 2999,
                quantity: 1,
            }],
            payment: Payment::Wallet {
                provider: "Stripe".into(),
                balance_cents: 50000,
            },
        },
        Order {
            id: 1003,
            customer: Customer {
                name: "Carol White".into(),
                address: Address {
                    street: "321 Pine Rd".into(),
                    city: "Springfield".into(),
                    zip: "62702".into(),
                },
            },
            items: vec![],
            payment: Payment::BankTransfer {
                iban: "DE89370400440532013000".into(),
            },
        },
    ];

    let order_city_lens = customer_lens().then(address_lens()).then(city_lens());
    println!("  All cities:");
    for o in &orders {
        let payment_type = match &o.payment {
            Payment::CreditCard { .. } => "CC",
            Payment::BankTransfer { .. } => "Bank",
            Payment::Wallet { .. } => "Wallet",
        };
        println!(
            "    Order #{}: {} ({}, pays via {})",
            o.id,
            order_city_lens.get(o),
            name_lens().get(&o.customer),
            payment_type
        );
    }

    // Find all bank IBANs using Prism
    println!("\n  Bank IBANs:");
    for o in &orders {
        if let Some(iban) = bank.preview(&o.payment) {
            println!("    Order #{}: {}", o.id, iban);
        }
    }
}

pub fn review(&self, b: B) -> T

Construct a T from a replacement value (inject/construct).

Examples found in repository

examples/domain_model_optics.rs (line 212)

fn main() {
    println!("=== Domain Model with Optics Example ===\n");

    let order = sample_order();

    // 1. Lens: get/set/over
    println!("--- Lens: basic get/set/over ---");
    let customer = customer_lens();
    let address = address_lens();
    let city = city_lens();

    println!("  Customer name: {}", name_lens().get(&order.customer));
    println!("  City: {}", city.get(&address.get(&customer.get(&order))));

    // 2. Composed Lens: deep access with .then()
    println!("\n--- ComposedLens: deep access with .then() ---");
    let order_city = customer_lens().then(address_lens()).then(city_lens());
    let order_zip = customer_lens().then(address_lens()).then(zip_lens());

    println!("  Order city: {}", order_city.get(&order));
    println!("  Order zip:  {}", order_zip.get(&order));

    // Deep set
    let updated = order_city.set(order.clone(), "Shelbyville".into());
    println!("  After city update: {}", order_city.get(&updated));
    println!("  Original unchanged: {}", order_city.get(&order));

    // Deep over (modify)
    let uppercased = order_city.over(order.clone(), |c| c.to_uppercase());
    println!("  Uppercased city: {}", order_city.get(&uppercased));

    // 3. Lens::transform — reusable update function
    println!("\n--- Lens::transform — reusable update function ---");
    let normalize_city: Box<dyn Fn(String) -> String> = Box::new(|c| c.trim().to_uppercase());
    let normalize_order_city = city_lens().transform::<FnP>(normalize_city);
    let addr = Address {
        street: "456 Oak Ave".into(),
        city: "  new york  ".into(),
        zip: "10001".into(),
    };
    let normalized = normalize_order_city(addr);
    println!("  Normalized city: {:?}", normalized.city);

    // 4. Prism: sum type focus
    println!("\n--- Prism: sum type focus ---");
    let cc = credit_card_prism();
    let wallet = wallet_prism();
    let bank = bank_transfer_prism();

    println!("  Credit card last4: {:?}", cc.preview(&order.payment));
    println!("  Wallet preview:    {:?}", wallet.preview(&order.payment));

    // Prism::review — construct a variant
    let new_payment = wallet.review(("PayPal".into(), 5000));
    println!("  New wallet payment: {:?}", new_payment);

    // Prism::over — modify only if matched
    let updated_payment = cc.over(order.payment.clone(), |(last4, _exp)| {
        (last4, "01/28".into())
    });
    println!("  Updated CC expiry: {:?}", updated_payment);

    // Prism on non-matching variant: passes through unchanged
    let unchanged = wallet.over(order.payment.clone(), |(prov, bal)| (prov, bal + 1000));
    println!("  Wallet over on CC (unchanged): {:?}", unchanged);

    // 5. Prism::transform — reusable pattern-matching function
    println!("\n--- Prism::transform — reusable variant modifier ---");
    let add_balance: Box<dyn Fn((String, i64)) -> (String, i64)> =
        Box::new(|(prov, bal)| (prov, bal + 2500));
    let add_wallet_balance = wallet.transform::<FnP>(add_balance);

    let wallet_payment = Payment::Wallet {
        provider: "PayPal".into(),
        balance_cents: 10000,
    };
    let topped_up = add_wallet_balance(wallet_payment);
    println!("  Topped up: {:?}", topped_up);

    // Apply same transform to non-wallet — passes through
    let still_cc = add_wallet_balance(order.payment.clone());
    println!("  CC unchanged: {:?}", still_cc);

    // 6. Summary: combine multiple optics
    println!("\n--- Combining lenses and prisms ---");
    let orders = vec![
        sample_order(),
        Order {
            id: 1002,
            customer: Customer {
                name: "Bob Jones".into(),
                address: Address {
                    street: "789 Elm St".into(),
                    city: "Capital City".into(),
                    zip: "12345".into(),
                },
            },
            items: vec![Item {
                name: "Mouse".into(),
                price_cents: 2999,
                quantity: 1,
            }],
            payment: Payment::Wallet {
                provider: "Stripe".into(),
                balance_cents: 50000,
            },
        },
        Order {
            id: 1003,
            customer: Customer {
                name: "Carol White".into(),
                address: Address {
                    street: "321 Pine Rd".into(),
                    city: "Springfield".into(),
                    zip: "62702".into(),
                },
            },
            items: vec![],
            payment: Payment::BankTransfer {
                iban: "DE89370400440532013000".into(),
            },
        },
    ];

    let order_city_lens = customer_lens().then(address_lens()).then(city_lens());
    println!("  All cities:");
    for o in &orders {
        let payment_type = match &o.payment {
            Payment::CreditCard { .. } => "CC",
            Payment::BankTransfer { .. } => "Bank",
            Payment::Wallet { .. } => "Wallet",
        };
        println!(
            "    Order #{}: {} ({}, pays via {})",
            o.id,
            order_city_lens.get(o),
            name_lens().get(&o.customer),
            payment_type
        );
    }

    // Find all bank IBANs using Prism
    println!("\n  Bank IBANs:");
    for o in &orders {
        if let Some(iban) = bank.preview(&o.payment) {
            println!("    Order #{}: {}", o.id, iban);
        }
    }
}

pub fn set(&self, s: S, b: B) -> T

Replace the focus if the variant matches; otherwise pass through.

pub fn over(&self, s: S, f: impl FnOnce(A) -> B) -> T

Modify the focus if the variant matches; otherwise pass through.

Examples found in repository

examples/domain_model_optics.rs (lines 216-218)

fn main() {
    println!("=== Domain Model with Optics Example ===\n");

    let order = sample_order();

    // 1. Lens: get/set/over
    println!("--- Lens: basic get/set/over ---");
    let customer = customer_lens();
    let address = address_lens();
    let city = city_lens();

    println!("  Customer name: {}", name_lens().get(&order.customer));
    println!("  City: {}", city.get(&address.get(&customer.get(&order))));

    // 2. Composed Lens: deep access with .then()
    println!("\n--- ComposedLens: deep access with .then() ---");
    let order_city = customer_lens().then(address_lens()).then(city_lens());
    let order_zip = customer_lens().then(address_lens()).then(zip_lens());

    println!("  Order city: {}", order_city.get(&order));
    println!("  Order zip:  {}", order_zip.get(&order));

    // Deep set
    let updated = order_city.set(order.clone(), "Shelbyville".into());
    println!("  After city update: {}", order_city.get(&updated));
    println!("  Original unchanged: {}", order_city.get(&order));

    // Deep over (modify)
    let uppercased = order_city.over(order.clone(), |c| c.to_uppercase());
    println!("  Uppercased city: {}", order_city.get(&uppercased));

    // 3. Lens::transform — reusable update function
    println!("\n--- Lens::transform — reusable update function ---");
    let normalize_city: Box<dyn Fn(String) -> String> = Box::new(|c| c.trim().to_uppercase());
    let normalize_order_city = city_lens().transform::<FnP>(normalize_city);
    let addr = Address {
        street: "456 Oak Ave".into(),
        city: "  new york  ".into(),
        zip: "10001".into(),
    };
    let normalized = normalize_order_city(addr);
    println!("  Normalized city: {:?}", normalized.city);

    // 4. Prism: sum type focus
    println!("\n--- Prism: sum type focus ---");
    let cc = credit_card_prism();
    let wallet = wallet_prism();
    let bank = bank_transfer_prism();

    println!("  Credit card last4: {:?}", cc.preview(&order.payment));
    println!("  Wallet preview:    {:?}", wallet.preview(&order.payment));

    // Prism::review — construct a variant
    let new_payment = wallet.review(("PayPal".into(), 5000));
    println!("  New wallet payment: {:?}", new_payment);

    // Prism::over — modify only if matched
    let updated_payment = cc.over(order.payment.clone(), |(last4, _exp)| {
        (last4, "01/28".into())
    });
    println!("  Updated CC expiry: {:?}", updated_payment);

    // Prism on non-matching variant: passes through unchanged
    let unchanged = wallet.over(order.payment.clone(), |(prov, bal)| (prov, bal + 1000));
    println!("  Wallet over on CC (unchanged): {:?}", unchanged);

    // 5. Prism::transform — reusable pattern-matching function
    println!("\n--- Prism::transform — reusable variant modifier ---");
    let add_balance: Box<dyn Fn((String, i64)) -> (String, i64)> =
        Box::new(|(prov, bal)| (prov, bal + 2500));
    let add_wallet_balance = wallet.transform::<FnP>(add_balance);

    let wallet_payment = Payment::Wallet {
        provider: "PayPal".into(),
        balance_cents: 10000,
    };
    let topped_up = add_wallet_balance(wallet_payment);
    println!("  Topped up: {:?}", topped_up);

    // Apply same transform to non-wallet — passes through
    let still_cc = add_wallet_balance(order.payment.clone());
    println!("  CC unchanged: {:?}", still_cc);

    // 6. Summary: combine multiple optics
    println!("\n--- Combining lenses and prisms ---");
    let orders = vec![
        sample_order(),
        Order {
            id: 1002,
            customer: Customer {
                name: "Bob Jones".into(),
                address: Address {
                    street: "789 Elm St".into(),
                    city: "Capital City".into(),
                    zip: "12345".into(),
                },
            },
            items: vec![Item {
                name: "Mouse".into(),
                price_cents: 2999,
                quantity: 1,
            }],
            payment: Payment::Wallet {
                provider: "Stripe".into(),
                balance_cents: 50000,
            },
        },
        Order {
            id: 1003,
            customer: Customer {
                name: "Carol White".into(),
                address: Address {
                    street: "321 Pine Rd".into(),
                    city: "Springfield".into(),
                    zip: "62702".into(),
                },
            },
            items: vec![],
            payment: Payment::BankTransfer {
                iban: "DE89370400440532013000".into(),
            },
        },
    ];

    let order_city_lens = customer_lens().then(address_lens()).then(city_lens());
    println!("  All cities:");
    for o in &orders {
        let payment_type = match &o.payment {
            Payment::CreditCard { .. } => "CC",
            Payment::BankTransfer { .. } => "Bank",
            Payment::Wallet { .. } => "Wallet",
        };
        println!(
            "    Order #{}: {} ({}, pays via {})",
            o.id,
            order_city_lens.get(o),
            name_lens().get(&o.customer),
            payment_type
        );
    }

    // Find all bank IBANs using Prism
    println!("\n  Bank IBANs:");
    for o in &orders {
        if let Some(iban) = bank.preview(&o.payment) {
            println!("    Order #{}: {}", o.id, iban);
        }
    }
}

pub fn to_review(&self) -> Review<T, B>

Convert to a Review (write-only, construction).

pub fn to_setter(&self) -> Setter<S, T, A, B>

where S: 'static, T: 'static, A: 'static, B: 'static,

Convert to a Setter (modify-only).

pub fn to_traversal(&self) -> Traversal<S, T, A, B>

where S: Clone + 'static, T: 'static, A: 'static, B: 'static,

Convert to a Traversal (0-or-1 element focus).

pub fn to_fold(&self) -> Fold<S, A>

where S: Clone + 'static, T: 'static, A: 'static,

Convert to a Fold (0-or-1 element, read-only).

pub fn transform<P>(&self, pab: <P as HKT2>::P<A, B>) -> <P as HKT2>::P<S, T>

where P: Choice, S: 'static, T: 'static, A: 'static, B: 'static,

Profunctor encoding: transform a P<A, B> into a P<S, T> via this prism.

This connects prisms to the profunctor hierarchy through Choice. Given any Choice profunctor P and a value pab: P<A, B>, transform produces P<S, T> by:

1. right(pab) lifts to P<Result<T, A>, Result<T, B>>
2. dimap pre-composes with match_ (swapping arms) and post-composes with build (reassembling)

The arm-swapping (Ok→Err, Err→Ok in the pre-composition) is necessary because Choice::right acts on the Err branch of Result.

Examples found in repository

examples/domain_model_optics.rs (line 229)

fn main() {
    println!("=== Domain Model with Optics Example ===\n");

    let order = sample_order();

    // 1. Lens: get/set/over
    println!("--- Lens: basic get/set/over ---");
    let customer = customer_lens();
    let address = address_lens();
    let city = city_lens();

    println!("  Customer name: {}", name_lens().get(&order.customer));
    println!("  City: {}", city.get(&address.get(&customer.get(&order))));

    // 2. Composed Lens: deep access with .then()
    println!("\n--- ComposedLens: deep access with .then() ---");
    let order_city = customer_lens().then(address_lens()).then(city_lens());
    let order_zip = customer_lens().then(address_lens()).then(zip_lens());

    println!("  Order city: {}", order_city.get(&order));
    println!("  Order zip:  {}", order_zip.get(&order));

    // Deep set
    let updated = order_city.set(order.clone(), "Shelbyville".into());
    println!("  After city update: {}", order_city.get(&updated));
    println!("  Original unchanged: {}", order_city.get(&order));

    // Deep over (modify)
    let uppercased = order_city.over(order.clone(), |c| c.to_uppercase());
    println!("  Uppercased city: {}", order_city.get(&uppercased));

    // 3. Lens::transform — reusable update function
    println!("\n--- Lens::transform — reusable update function ---");
    let normalize_city: Box<dyn Fn(String) -> String> = Box::new(|c| c.trim().to_uppercase());
    let normalize_order_city = city_lens().transform::<FnP>(normalize_city);
    let addr = Address {
        street: "456 Oak Ave".into(),
        city: "  new york  ".into(),
        zip: "10001".into(),
    };
    let normalized = normalize_order_city(addr);
    println!("  Normalized city: {:?}", normalized.city);

    // 4. Prism: sum type focus
    println!("\n--- Prism: sum type focus ---");
    let cc = credit_card_prism();
    let wallet = wallet_prism();
    let bank = bank_transfer_prism();

    println!("  Credit card last4: {:?}", cc.preview(&order.payment));
    println!("  Wallet preview:    {:?}", wallet.preview(&order.payment));

    // Prism::review — construct a variant
    let new_payment = wallet.review(("PayPal".into(), 5000));
    println!("  New wallet payment: {:?}", new_payment);

    // Prism::over — modify only if matched
    let updated_payment = cc.over(order.payment.clone(), |(last4, _exp)| {
        (last4, "01/28".into())
    });
    println!("  Updated CC expiry: {:?}", updated_payment);

    // Prism on non-matching variant: passes through unchanged
    let unchanged = wallet.over(order.payment.clone(), |(prov, bal)| (prov, bal + 1000));
    println!("  Wallet over on CC (unchanged): {:?}", unchanged);

    // 5. Prism::transform — reusable pattern-matching function
    println!("\n--- Prism::transform — reusable variant modifier ---");
    let add_balance: Box<dyn Fn((String, i64)) -> (String, i64)> =
        Box::new(|(prov, bal)| (prov, bal + 2500));
    let add_wallet_balance = wallet.transform::<FnP>(add_balance);

    let wallet_payment = Payment::Wallet {
        provider: "PayPal".into(),
        balance_cents: 10000,
    };
    let topped_up = add_wallet_balance(wallet_payment);
    println!("  Topped up: {:?}", topped_up);

    // Apply same transform to non-wallet — passes through
    let still_cc = add_wallet_balance(order.payment.clone());
    println!("  CC unchanged: {:?}", still_cc);

    // 6. Summary: combine multiple optics
    println!("\n--- Combining lenses and prisms ---");
    let orders = vec![
        sample_order(),
        Order {
            id: 1002,
            customer: Customer {
                name: "Bob Jones".into(),
                address: Address {
                    street: "789 Elm St".into(),
                    city: "Capital City".into(),
                    zip: "12345".into(),
                },
            },
            items: vec![Item {
                name: "Mouse".into(),
                price_cents: 2999,
                quantity: 1,
            }],
            payment: Payment::Wallet {
                provider: "Stripe".into(),
                balance_cents: 50000,
            },
        },
        Order {
            id: 1003,
            customer: Customer {
                name: "Carol White".into(),
                address: Address {
                    street: "321 Pine Rd".into(),
                    city: "Springfield".into(),
                    zip: "62702".into(),
                },
            },
            items: vec![],
            payment: Payment::BankTransfer {
                iban: "DE89370400440532013000".into(),
            },
        },
    ];

    let order_city_lens = customer_lens().then(address_lens()).then(city_lens());
    println!("  All cities:");
    for o in &orders {
        let payment_type = match &o.payment {
            Payment::CreditCard { .. } => "CC",
            Payment::BankTransfer { .. } => "Bank",
            Payment::Wallet { .. } => "Wallet",
        };
        println!(
            "    Order #{}: {} ({}, pays via {})",
            o.id,
            order_city_lens.get(o),
            name_lens().get(&o.customer),
            payment_type
        );
    }

    // Find all bank IBANs using Prism
    println!("\n  Bank IBANs:");
    for o in &orders {
        if let Some(iban) = bank.preview(&o.payment) {
            println!("    Order #{}: {}", o.id, iban);
        }
    }
}

Trait Implementations

impl<S, T, A, B> Optic for Prism<S, T, A, B>