Add convenience functions for creating puzzle variables.

src/puzzle.rs

@@ -53,6 +53,58 @@ impl Puzzle {
         var
     }
 
+    /// Allocate a new puzzle variable, initialising it with potential
+    /// candidates.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut send_more_money = puzzle_solver::Puzzle::new();
+    /// send_more_money.new_var_with_candidates(&[0,1,2,3,4,5,6,7,8,9]);
+    /// ```
+    pub fn new_var_with_candidates(&mut self, candidates: &[Val]) -> VarToken {
+        let var = self.new_var();
+        self.insert_candidates(var, candidates);
+        var
+    }
+
+    /// Allocate a 1d vector of puzzle variables, each initialised to
+    /// have the same set of potential candidates.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut send_more_money = puzzle_solver::Puzzle::new();
+    /// send_more_money.new_vars_with_candidates_1d(8, &[0,1,2,3,4,5,6,7,8,9]);
+    /// ```
+    pub fn new_vars_with_candidates_1d(&mut self, n: usize, candidates: &[Val])
+            -> Vec<VarToken> {
+        let mut vars = Vec::with_capacity(n);
+        for _ in 0..n {
+            vars.push(self.new_var_with_candidates(candidates));
+        }
+        vars
+    }
+
+    /// Allocate a 2d array of puzzle variables, each initialised to
+    /// have the same set of potential candidates.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut magic_square = puzzle_solver::Puzzle::new();
+    /// magic_square.new_vars_with_candidates_2d(3, 3, &[1,2,3,4,5,6,7,8,9]);
+    /// ```
+    pub fn new_vars_with_candidates_2d(self: &mut Puzzle,
+            width: usize, height: usize, candidates: &[Val])
+            -> Vec<Vec<VarToken>> {
+        let mut vars = Vec::with_capacity(height);
+        for _ in 0..height {
+            vars.push(self.new_vars_with_candidates_1d(width, candidates));
+        }
+        vars
+    }
+
     /// Set a variable to a known value.
     ///
     /// This is useful when the variable is given as part of the
@@ -63,11 +115,10 @@ impl Puzzle {
     ///
     /// ```
     /// let mut magic_square = puzzle_solver::Puzzle::new();
-    /// let mut vars = Vec::new();
-    /// for _ in 0..9 {
-    ///     vars.push(magic_square.new_var());
-    /// }
-    /// magic_square.set_value(vars[4], 5);
+    /// let vars = magic_square.new_vars_with_candidates_2d(3, 3,
+    ///         &[1,2,3,4,5,6,7,8,9]);
+    ///
+    /// magic_square.set_value(vars[1][1], 5);
     /// ```
     pub fn set_value(&mut self, var: VarToken, value: Val) {
         let VarToken(idx) = var;
@@ -119,12 +170,8 @@ impl Puzzle {
     ///
     /// ```
     /// let mut send_more_money = puzzle_solver::Puzzle::new();
-    /// let mut vars = Vec::new();
-    /// for _ in 0..8 { // [s,e,n,d,m,o,r,y].
-    ///     let var = send_more_money.new_var();
-    ///     send_more_money.insert_candidates(var, &[0,1,2,3,4,5,6,7,8,9]);
-    ///     vars.push(var);
-    /// }
+    /// let vars = send_more_money.new_vars_with_candidates_1d(8,
+    ///         &[0,1,2,3,4,5,6,7,8,9]);
     ///
     /// let s = vars[0];
     /// let m = vars[4];
@@ -156,12 +203,8 @@ impl Puzzle {
     ///
     /// ```
     /// let mut send_more_money = puzzle_solver::Puzzle::new();
-    /// let mut vars = Vec::new();
-    /// for _ in 0..8 { // [s,e,n,d,m,o,r,y].
-    ///     let var = send_more_money.new_var();
-    ///     send_more_money.insert_candidates(var, &[0,1,2,3,4,5,6,7,8,9]);
-    ///     vars.push(var);
-    /// }
+    /// let vars = send_more_money.new_vars_with_candidates_1d(8,
+    ///         &[0,1,2,3,4,5,6,7,8,9]);
     ///
     /// let m = vars[4];
     /// send_more_money.intersect_candidates(m, &[0,1]);