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>>> {