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
/*
* SPDX-License-Identifier: MIT
* Copyright (c) 2023 - 2026. The DeepCausality Authors and Contributors. All Rights Reserved.
*/
use crateHKT;
/// Witness capability: an [`HKT`] functor whose `Type<T>` can be cloned whenever the payload
/// `T: Clone`.
///
/// This is the [`Clone`] analogue of [`Functor`](crate::Functor) and the twin of
/// [`EqFunctor`](crate::EqFunctor) / [`DebugFunctor`](crate::DebugFunctor): the witness supplies the
/// structural clone of its container, which gives the recursive carriers `Free` and `Cofree` their
/// `Clone` instances without the trait-solver overflow a `#[derive]` (or a `Self::Type<..>: Clone`
/// field bound) hits on the GAT projection `Self::Type<Box<Free<F, A>>>` (see
/// [`EqFunctor`](crate::EqFunctor) for the mechanism).
///
/// # Opt-in
///
/// A witness opts in by implementing this trait; nothing existing changes and no instance appears
/// for a witness that does not. The crate's built-in single-hole functor witnesses
/// (`OptionWitness`, `VecWitness`, `BoxWitness`, `LinkedListWitness`, `VecDequeWitness`) implement it
/// — the body delegates to the container's own `Clone`.
///
/// Scoped to `HKT` because `Free`/`Cofree` require it.
///
/// # Law
///
/// `clone_type` is the container's structural clone: the returned container is equal to the input
/// (`clone_type(fa) == fa` whenever the witness is also an [`EqFunctor`](crate::EqFunctor)) and
/// preserves its `F`-shape.
/// The `Clone` it induces on `Free`/`Cofree` is then a structural copy by induction on the tree.
///
/// # Examples
///
/// ```rust
/// use deep_causality_haft::{CloneFunctor, OptionWitness};
///
/// let a: Option<i32> = Some(5);
/// let b = OptionWitness::clone_type(&a);
/// assert_eq!(a, b);
/// ```
///
/// The `Clone` on `Free`/`Cofree` is opt-in: a witness that does **not** implement `CloneFunctor`
/// gives no `Clone` for its programs.
///
/// ```compile_fail
/// use deep_causality_haft::{Free, HKT};
///
/// struct NoClone;
/// impl HKT for NoClone {
/// type Type<T> = Option<T>;
/// }
///
/// let a: Free<NoClone, i32> = Free::Pure(1);
/// let _ = a.clone(); // `NoClone: CloneFunctor` is not satisfied — does not compile.
/// ```