slice: utility 'enforce_embedding' (2) (#788)

Summary:
Pull Request resolved: #788

i messed this up in D79751839. as the name `enforce` suggests, i was intending to provide a fluent-api for this function, fixed by this diff. now you can say e.g. `view.enforce_embedded(&base)?.len()` for example for "on-the-fly" enforcement (à la  https://erdani.org/publications/cuj-06-2003.php.html).

ghstack-source-id: 301394706
exported-using-ghexport

Reviewed By: pzhan9

Differential Revision: D79805718

fbshipit-source-id: 7bcc5c900882db0fe860a6afb6b683dd9b811c73

Author: shayne-fletcher

ndslice/src/slice.rs

@@ -655,15 +655,30 @@ impl Slice {
         })
     }
 
-    /// Ensures that every storage offset used by `other` is valid in
-    /// `self`.
+    /// Ensures that every storage offset used by `self` is valid in
+    /// `other`.
     ///
-    /// That is, for all p ∈ other:
-    /// `self.coordinates(other.location(p))` is defined.
-    pub fn enforce_embedding(&self, other: &Slice) -> Result<(), SliceError> {
-        other
-            .iter()
-            .try_for_each(|loc| self.coordinates(loc).map(|_| ()))
+    /// That is, for all p ∈ self:
+    /// `other.coordinates(self.location(p))` is defined.
+    ///
+    /// Returns `self` on success, enabling fluent chaining.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use ndslice::Slice;
+    ///
+    /// let base = Slice::new(0, vec![4, 4], vec![4, 1]).unwrap();
+    /// let view = base.subview(&[1, 1], &[2, 2]).unwrap();
+    /// assert_eq!(view.enforce_embedding(&base).unwrap().len(), 4);
+    ///
+    /// let small = Slice::new(0, vec![2, 2], vec![2, 1]).unwrap();
+    /// assert!(view.enforce_embedding(&small).is_err());
+    ///  ```
+    pub fn enforce_embedding<'a>(&'a self, other: &'_ Slice) -> Result<&'a Slice, SliceError> {
+        self.iter()
+            .try_for_each(|loc| other.coordinates(loc).map(|_| ()))?;
+        Ok(self)
     }
 }
 
@@ -1092,14 +1107,14 @@ mod tests {
         let base = Slice::new(0, vec![4, 4], vec![4, 1]).unwrap(); // 4×4 matrix, row-major
         let view = Slice::new(5, vec![2, 2], vec![4, 1]).unwrap(); // a 2×2 submatrix starting at (1,1)
 
-        assert!(base.enforce_embedding(&view).is_ok());
+        assert!(view.enforce_embedding(&base).is_ok());
     }
 
     #[test]
     fn embedding_fails_for_out_of_bounds_view() {
         let base = Slice::new(0, vec![4, 4], vec![4, 1]).unwrap(); // 4×4 matrix
         let view = Slice::new(14, vec![2, 2], vec![4, 1]).unwrap(); // starts at (3,2), accesses (4,3)
 
-        assert!(base.enforce_embedding(&view).is_err());
+        assert!(view.enforce_embedding(&base).is_err());
     }
 }