Merge pull request #1130 from hannobraun/ready/partial

Start changing builder API into a partial object API

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

@@ -161,7 +161,10 @@ mod tests {
 
         let surface = Surface::xz_plane();
         let curve = Curve::builder(&stores, surface).build_u_axis();
-        let vertex = Vertex::builder([0.], curve).build();
+        let vertex = Vertex::partial()
+            .with_position([0.])
+            .with_curve(curve)
+            .build();
 
         let half_edge = (vertex, surface).sweep([0., 0., 1.], &stores);
 

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

@@ -83,7 +83,7 @@ impl<'a> CycleBuilder<'a> {
         self
     }
 
-    /// Create a polygon from a list of points
+    /// Finish building the [`Cycle`]
     pub fn build(self) -> Cycle {
         Cycle::new(self.surface, self.half_edges)
     }

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

@@ -60,8 +60,9 @@ impl<'a> HalfEdgeBuilder<'a> {
             let [a_curve, b_curve] =
                 [Scalar::ZERO, Scalar::TAU].map(|coord| Point::from([coord]));
 
-            let global_vertex = GlobalVertex::builder()
-                .build_from_curve_and_position(&curve, a_curve);
+            let global_vertex = GlobalVertex::partial()
+                .from_curve_and_position(&curve, a_curve)
+                .build();
 
             let surface_vertices = [a_curve, b_curve].map(|point_curve| {
                 let point_surface =
@@ -98,8 +99,9 @@ impl<'a> HalfEdgeBuilder<'a> {
         let points = points.map(Into::into);
 
         let global_vertices = points.map(|position| {
-            GlobalVertex::builder()
-                .build_from_surface_and_position(&self.surface, position)
+            GlobalVertex::partial()
+                .from_surface_and_position(&self.surface, position)
+                .build()
         });
 
         let surface_vertices = {

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

@@ -7,7 +7,6 @@ mod face;
 mod shell;
 mod sketch;
 mod solid;
-mod vertex;
 
 pub use self::{
     curve::{CurveBuilder, GlobalCurveBuilder},
@@ -17,5 +16,4 @@ pub use self::{
     shell::ShellBuilder,
     sketch::SketchBuilder,
     solid::SolidBuilder,
-    vertex::{GlobalVertexBuilder, SurfaceVertexBuilder, VertexBuilder},
 };

crates/fj-kernel/src/lib.rs

@@ -91,5 +91,6 @@ pub mod algorithms;
 pub mod builder;
 pub mod iter;
 pub mod objects;
+pub mod partial;
 pub mod path;
 pub mod stores;

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

@@ -1,8 +1,8 @@
 use fj_math::Point;
 use pretty_assertions::assert_eq;
 
-use crate::builder::{
-    GlobalVertexBuilder, SurfaceVertexBuilder, VertexBuilder,
+use crate::partial::{
+    PartialGlobalVertex, PartialSurfaceVertex, PartialVertex,
 };
 
 use super::{Curve, Surface};
@@ -21,17 +21,12 @@ pub struct Vertex {
 }
 
 impl Vertex {
-    /// Build a `Vertex` using [`VertexBuilder`]
-    pub fn builder(
-        position: impl Into<Point<1>>,
-        curve: Curve,
-    ) -> VertexBuilder {
-        VertexBuilder {
-            position: position.into(),
-            curve,
-            surface_form: None,
-            global_form: None,
-        }
+    /// 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`
@@ -90,16 +85,12 @@ pub struct SurfaceVertex {
 }
 
 impl SurfaceVertex {
-    /// Build a `SurfaceVertex` using [`SurfaceVertexBuilder`]
-    pub fn builder(
-        position: impl Into<Point<2>>,
-        surface: Surface,
-    ) -> SurfaceVertexBuilder {
-        SurfaceVertexBuilder {
-            position: position.into(),
-            surface,
-            global_form: None,
-        }
+    /// 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`
@@ -156,12 +147,15 @@ pub struct GlobalVertex {
 }
 
 impl GlobalVertex {
-    /// Build a `GlobalVertex` using [`GlobalVertexBuilder`]
-    pub fn builder() -> GlobalVertexBuilder {
-        GlobalVertexBuilder
+    /// 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 point
+    /// Construct a `GlobalVertex` from a position
     pub fn from_position(position: impl Into<Point<3>>) -> Self {
         let position = position.into();
         Self { position }

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

@@ -0,0 +1,32 @@
+//! Partial objects
+//!
+//! This module contains type that represent partial objects. This is useful
+//! when building objects, as it's often possible to provide just some the data
+//! they own or objects they reference, while computing the rest.
+//!
+//! More generally speaking, there are situations where different parts of a new
+//! objects are available at different times, and provided from different
+//! places. Partial objects can be used to represent such partially constructed
+//! objects whenever that is required.
+//!
+//! The API for partial objects follows a specific style:
+//!
+//! - Partial objects are structs with fields that mirror the fields of the full
+//!   object structs, but all fields are optional.
+//! - Partial object structs implement [`Default`], but a `partial` method is
+//!   also available on the respective full object struct, as a perhaps more
+//!   convenient and readable way to construct a partial object.
+//! - Partial object structs have `with_*` methods to provide values for each of
+//!   their fields.
+//! - Partial object structs may have other methods with prefixes like `as_*`,
+//!   `from_*`, or similar, if one or more of their fields can be initialized by
+//!   providing alternative data.
+//! - Partial object structs have a `build` method to build a full object.
+//! - All `with_*`, `as_*`, and `build` methods can be chained, to provide a
+//!   convenient API.
+
+mod vertex;
+
+pub use self::vertex::{
+    PartialGlobalVertex, PartialSurfaceVertex, PartialVertex,
+};