Merge pull request #1148 from hannobraun/ready/partial

Clean up partial object API, update its documentation

crates/fj-kernel/src/algorithms/approx/curve.rs

@@ -198,6 +198,7 @@ mod tests {
     use crate::{
         algorithms::approx::{path::RangeOnPath, Approx, ApproxPoint},
         objects::{Curve, Surface},
+        partial::HasPartial,
         path::GlobalPath,
         stores::Stores,
     };

crates/fj-kernel/src/algorithms/intersect/curve_edge.rs

@@ -76,6 +76,7 @@ mod tests {
 
     use crate::{
         objects::{Curve, HalfEdge, Surface},
+        partial::HasPartial,
         stores::Stores,
     };
 

crates/fj-kernel/src/algorithms/intersect/curve_face.rs

@@ -157,6 +157,7 @@ where
 mod tests {
     use crate::{
         objects::{Curve, Face, Surface},
+        partial::HasPartial,
         stores::Stores,
     };
 

crates/fj-kernel/src/algorithms/intersect/face_face.rs

@@ -65,6 +65,7 @@ mod tests {
     use crate::{
         algorithms::intersect::CurveFaceIntersection,
         objects::{Curve, Face, Surface},
+        partial::HasPartial,
         stores::Stores,
     };
 

crates/fj-kernel/src/algorithms/intersect/surface_surface.rs

@@ -159,6 +159,7 @@ mod tests {
     use crate::{
         algorithms::transform::TransformObject,
         objects::{Curve, Surface},
+        partial::HasPartial,
         stores::Stores,
     };
 

crates/fj-kernel/src/algorithms/sweep/edge.rs

@@ -184,6 +184,7 @@ mod tests {
     use crate::{
         algorithms::{reverse::Reverse, sweep::Sweep},
         objects::{Cycle, Face, HalfEdge, Surface},
+        partial::HasPartial,
         stores::Stores,
     };
 

crates/fj-kernel/src/algorithms/sweep/face.rs

@@ -75,6 +75,7 @@ mod tests {
     use crate::{
         algorithms::{reverse::Reverse, transform::TransformObject},
         objects::{Face, HalfEdge, Sketch, Surface},
+        partial::HasPartial,
         stores::Stores,
     };
 

crates/fj-kernel/src/algorithms/sweep/vertex.rs

@@ -5,8 +5,9 @@ use crate::{
         Curve, GlobalCurve, GlobalEdge, GlobalVertex, HalfEdge, Surface,
         SurfaceVertex, Vertex,
     },
+    partial::HasPartial,
     path::SurfacePath,
-    stores::Stores,
+    stores::{Handle, Stores},
 };
 
 use super::Sweep;
@@ -137,7 +138,7 @@ impl Sweep for GlobalVertex {
         let a = self;
         let b = GlobalVertex::from_position(self.position() + path.into());
 
-        let curve = GlobalCurve::partial()
+        let curve = Handle::<GlobalCurve>::partial()
             .as_line_from_points([a.position(), b.position()])
             .build(stores);
 
@@ -153,7 +154,8 @@ mod tests {
             Curve, GlobalCurve, GlobalEdge, GlobalVertex, HalfEdge, Surface,
             Vertex,
         },
-        stores::Stores,
+        partial::HasPartial,
+        stores::{Handle, Stores},
     };
 
     #[test]
@@ -186,7 +188,7 @@ mod tests {
             .sweep([0., 0., 1.], &stores);
 
         let expected_edge = GlobalEdge::new(
-            GlobalCurve::partial().as_z_axis().build(&stores),
+            Handle::<GlobalCurve>::partial().as_z_axis().build(&stores),
             [[0., 0., 0.], [0., 0., 1.]].map(GlobalVertex::from_position),
         );
         assert_eq!(edge, expected_edge);

crates/fj-kernel/src/algorithms/validate/mod.rs

@@ -164,6 +164,7 @@ mod tests {
             Curve, GlobalCurve, GlobalEdge, GlobalVertex, HalfEdge, Surface,
             SurfaceVertex, Vertex,
         },
+        partial::HasPartial,
         path::{GlobalPath, SurfacePath},
         stores::Stores,
     };

crates/fj-kernel/src/builder/cycle.rs

@@ -2,6 +2,7 @@ use fj_math::Point;
 
 use crate::{
     objects::{Curve, Cycle, HalfEdge, Surface, SurfaceVertex, Vertex},
+    partial::HasPartial,
     stores::Stores,
 };
 

crates/fj-kernel/src/builder/shell.rs

@@ -5,6 +5,7 @@ use crate::{
     objects::{
         Curve, Cycle, Face, HalfEdge, Shell, Surface, SurfaceVertex, Vertex,
     },
+    partial::HasPartial,
     stores::Stores,
 };
 

crates/fj-kernel/src/iter.rs

@@ -364,7 +364,8 @@ mod tests {
             Curve, Cycle, Face, GlobalCurve, GlobalVertex, HalfEdge, Shell,
             Sketch, Solid, Surface, SurfaceVertex, Vertex,
         },
-        stores::Stores,
+        partial::HasPartial,
+        stores::{Handle, Stores},
     };
 
     use super::ObjectIters as _;
@@ -440,7 +441,8 @@ mod tests {
     fn global_curve() {
         let stores = Stores::new();
 
-        let object = GlobalCurve::partial().as_x_axis().build(&stores);
+        let object =
+            Handle::<GlobalCurve>::partial().as_x_axis().build(&stores);
 
         assert_eq!(0, object.curve_iter().count());
         assert_eq!(0, object.cycle_iter().count());

crates/fj-kernel/src/objects/curve.rs

@@ -1,5 +1,4 @@
 use crate::{
-    partial::{PartialCurve, PartialGlobalCurve},
     path::{GlobalPath, SurfacePath},
     stores::Handle,
 };
@@ -15,14 +14,6 @@ pub struct Curve {
 }
 
 impl Curve {
-    /// Create a [`PartialCurve`]
-    ///
-    /// This function exists just for convenience, and will just return a
-    /// default [`PartialCurve`].
-    pub fn partial() -> PartialCurve {
-        PartialCurve::default()
-    }
-
     /// Construct a new instance of `Curve`
     pub fn new(
         surface: Surface,
@@ -59,14 +50,6 @@ pub struct GlobalCurve {
 }
 
 impl GlobalCurve {
-    /// Create a [`PartialGlobalCurve`]
-    ///
-    /// This function exists just for convenience, and will just return a
-    /// default [`PartialGlobalCurve`].
-    pub fn partial() -> PartialGlobalCurve {
-        PartialGlobalCurve::default()
-    }
-
     /// Construct a `GlobalCurve` from the path that defines it
     pub fn from_path(path: GlobalPath) -> Self {
         Self { path }

crates/fj-kernel/src/objects/edge.rs

@@ -1,9 +1,6 @@
 use std::fmt;
 
-use crate::{
-    partial::{PartialGlobalEdge, PartialHalfEdge},
-    stores::Handle,
-};
+use crate::stores::Handle;
 
 use super::{Curve, GlobalCurve, GlobalVertex, Vertex};
 
@@ -16,14 +13,6 @@ pub struct HalfEdge {
 }
 
 impl HalfEdge {
-    /// Create a [`PartialHalfEdge`]
-    ///
-    /// This function exists just for convenience, and will just return a
-    /// default [`PartialHalfEdge`].
-    pub fn partial() -> PartialHalfEdge {
-        PartialHalfEdge::default()
-    }
-
     /// Create a new instance of `HalfEdge`
     ///
     /// # Panics
@@ -124,14 +113,6 @@ pub struct GlobalEdge {
 }
 
 impl GlobalEdge {
-    /// Create a [`PartialGlobalEdge`]
-    ///
-    /// This function exists just for convenience, and will just return a
-    /// default [`PartialGlobalEdge`].
-    pub fn partial() -> PartialGlobalEdge {
-        PartialGlobalEdge::default()
-    }
-
     /// Create a new instance
     pub fn new(
         curve: Handle<GlobalCurve>,

crates/fj-kernel/src/objects/vertex.rs

@@ -1,10 +1,6 @@
 use fj_math::Point;
 use pretty_assertions::assert_eq;
 
-use crate::partial::{
-    PartialGlobalVertex, PartialSurfaceVertex, PartialVertex,
-};
-
 use super::{Curve, Surface};
 
 /// A vertex
@@ -21,14 +17,6 @@ pub struct Vertex {
 }
 
 impl Vertex {
-    /// Create a [`PartialVertex`]
-    ///
-    /// This function exists just for convenience, and will just return a
-    /// default [`PartialVertex`].
-    pub fn partial() -> PartialVertex {
-        PartialVertex::default()
-    }
-
     /// Construct an instance of `Vertex`
     ///
     /// Panics, if `curve` and `surface_form` are not defined on the same
@@ -85,14 +73,6 @@ pub struct SurfaceVertex {
 }
 
 impl SurfaceVertex {
-    /// Create a [`PartialSurfaceVertex`]
-    ///
-    /// This function exists just for convenience, and will just return a
-    /// default [`PartialSurfaceVertex`].
-    pub fn partial() -> PartialSurfaceVertex {
-        PartialSurfaceVertex::default()
-    }
-
     /// Construct a new instance of `SurfaceVertex`
     pub fn new(
         position: impl Into<Point<2>>,
@@ -147,14 +127,6 @@ pub struct GlobalVertex {
 }
 
 impl GlobalVertex {
-    /// Create a [`PartialGlobalVertex`]
-    ///
-    /// This function exists just for convenience, and will just return a
-    /// default [`PartialGlobalVertex`].
-    pub fn partial() -> PartialGlobalVertex {
-        PartialGlobalVertex::default()
-    }
-
     /// Construct a `GlobalVertex` from a position
     pub fn from_position(position: impl Into<Point<3>>) -> Self {
         let position = position.into();

crates/fj-kernel/src/partial/maybe_partial.rs

@@ -5,47 +5,78 @@ use crate::{
     stores::{Handle, Stores},
 };
 
-use super::HasPartialForm;
+use super::{HasPartial, Partial};
 
-/// Either a partial object or a full one
+/// Can be used everywhere either a partial or full objects are accepted
+///
+/// Some convenience methods are available for specific instances of
+/// `MaybePartial` (like, `MaybePartial<Curve>`, or `MaybePartial<Vertex>`).
+///
+/// # Implementation Note
+///
+/// The set of available convenience methods is far from complete. Please feel
+/// free to just add more, if you need them.
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash, Ord, PartialOrd)]
-pub enum MaybePartial<T: HasPartialForm> {
+pub enum MaybePartial<T: HasPartial> {
     /// A full object
     Full(T),
 
     /// A partial object
-    Partial(T::PartialForm),
+    Partial(T::Partial),
 }
 
-impl<T: HasPartialForm> MaybePartial<T> {
+impl<T: HasPartial> MaybePartial<T> {
     /// If this is a partial object, update it
+    ///
+    /// This is useful whenever a partial object can infer something about its
+    /// parts from other parts, and wants to update what was inferred, in case
+    /// it *can* be updated.
     pub fn update_partial(
         self,
-        f: impl FnOnce(T::PartialForm) -> T::PartialForm,
+        f: impl FnOnce(T::Partial) -> T::Partial,
     ) -> Self {
         match self {
             Self::Partial(partial) => Self::Partial(f(partial)),
             _ => self,
         }
     }
 
-    /// Return the full object, either directly or by building it
+    /// Return or build a full object
+    ///
+    /// If this already is a full object, it is returned. If this is a partial
+    /// object, the full object is built from it, using [`Partial::build`].
     pub fn into_full(self, stores: &Stores) -> T {
         match self {
-            Self::Partial(partial) => T::from_partial(partial, stores),
+            Self::Partial(partial) => partial.build(stores),
             Self::Full(full) => full,
         }
     }
 
-    /// Return the partial object, either directly or via conversion
-    pub fn into_partial(self) -> T::PartialForm {
+    /// Return or convert a partial object
+    ///
+    /// If this already is a partial object, is is returned. If this is a full
+    /// object, it is converted into a partial object using
+    /// [`HasPartial::to_partial`].
+    pub fn into_partial(self) -> T::Partial {
         match self {
             Self::Partial(partial) => partial,
-            Self::Full(full) => full.into(),
+            Self::Full(full) => full.to_partial(),
         }
     }
 }
 
+impl<T> From<T> for MaybePartial<T>
+where
+    T: HasPartial,
+{
+    fn from(full: T) -> Self {
+        Self::Full(full)
+    }
+}
+
+// Unfortunately, we can't add a blanket implementation from `T::Partial` for
+// `MaybePartial<T>`, as that would conflict.
+
 impl MaybePartial<Curve> {
     /// Access the global form
     pub fn global_form(&self) -> Option<MaybePartial<Handle<GlobalCurve>>> {