livecode · runrevmark · Jun 1, 2017 · May 12, 2017 · May 12, 2017 · May 12, 2017
diff --git a/docs/dictionary/command/difference.lcdoc b/docs/dictionary/command/difference.lcdoc
@@ -0,0 +1,67 @@
+Name: difference
+
+Type: command
+
+Syntax: difference <targetArray> with <templateArray> [into <destinationArray>]
+
+Summary:
+Removes <element(glossary)|elements> from an <array> which have a 
+corresponding <element(keyword)> in another <array>, and leaves all
+others alone.
+
+Introduced: 9.0
+
+OS: mac, windows, linux, ios, android
+
+Platforms: desktop, server, mobile
+
+Example:
+local tLeft, tRight
+put "green" into tLeft["color"]
+put "left" into tLeft["align"]
+
+put "blue" into tRight["color"]
+put "100" into tRight["width"]
+
+difference tLeft with tRight
+
+# RESULT
+# the keys of tLeft = "align"
+# tRight unchanged
+
+Parameters:
+targetArray (array):
+The value to modify.
+
+
+templateArray (array):
+The array to difference <targetArray> with.
+
+destinationArray (optional array):
+A variable to set as the destination instead of mutating <targetArray>
+
+Description:
+Use the <difference> <command> to filter out <element(glossary)|elements>
+from an <array> according to the contents of another <array>.
+
+Each key of <targetArray> is checked to see whether there is a matching
+<key> in <templateArray>. The <element(glossary)|elements> of
+<targetArray> that match an <element(keyword)> of the <templateArray>
+are removed from <targetArray>.
+
+The content of individual elements of the <templateArray> does not
+affect the final result. Only which <element(glossary)|elements> exist
+in the <templateArray>, not their content, controls which
+<element(glossary)|elements> of <targetArray> are retained and which are
+removed.
+
+If the into clause is used the operation of the commands is the same as
+the non-into form except that <targetArray> does not have to be a
+variable, and the result of the operation is placed into
+<destinationArray> rather than mutating <targetArray>.
+
+References: split (command), union (command), element (glossary),
+array (glossary), command (glossary), key (glossary), element (keyword),
+intersect (command), symmetric difference (command)
+
+Tags: properties
diff --git a/docs/dictionary/command/intersect.lcdoc b/docs/dictionary/command/intersect.lcdoc
@@ -2,7 +2,7 @@ Name: intersect
 
 Type: command
 
-Syntax: intersect <targetArray> with <templateArray> [recursively]
+Syntax: intersect <targetArray> with <templateArray> [recursively] [into <destinationArray>]
 
 Summary:
 Removes <element(glossary)|elements> from an <array> if they have no
@@ -80,6 +80,8 @@ The value to modify.
 templateArray (array):
 The array to intersect <array> with.
 
+destinationArray (optional array):
+A variable to set as the destination instead of mutating <targetArray>
 
 Description:
 Use the <intersect> <command> to filter out <element(glossary)|elements>
@@ -106,8 +108,16 @@ removed. If <targetArray> and <templateArray> have the same set of
 <element(keyword)>, the <intersect> <command> does not change the value
 of <targetArray>.
 
+If the into clause is used the operation of the commands is the same as
+the non-into form except that <targetArray> does not have to be a
+variable, and the result of the operation is placed into
+<destinationArray> rather than mutating <targetArray>.
+
+Changes:
+The `into` clause was added in LiveCode 9.
+
 References: split (command), union (command), element (glossary),
-array (glossary), command (glossary), key (glossary), element (keyword)
+array (glossary), command (glossary), key (glossary), element (keyword),
+difference (command), symmetric difference (command)
 
 Tags: properties
-
diff --git a/docs/dictionary/command/symmetric-difference.lcdoc b/docs/dictionary/command/symmetric-difference.lcdoc
@@ -0,0 +1,70 @@
+Name: symmetric difference
+
+Type: command
+
+Syntax: symmetric difference <targetArray> with <templateArray> [into <destinationArray>]
+
+Summary:
+Removes <element(glossary)|elements> from a target <array> which have a 
+corresponding <element(keyword)> in a template <array>, and adds 
+<element(glossary)|elements> from the template <array> that have no
+which have no corresponding <element(keyword)> in the target <array>.
+
+Introduced: 9.0
+
+OS: mac, windows, linux, ios, android
+
+Platforms: desktop, server, mobile
+
+Example:
+local tLeft, tRight
+put "green" into tLeft["color"]
+put "left" into tLeft["align"]
+
+put "blue" into tRight["color"]
+put "100" into tRight["width"]
+
+symmetric difference tLeft with tRight
+
+# RESULT
+# the keys of tLeft = "align" & "width"
+# tRight unchanged
+
+Parameters:
+targetArray (array):
+The value to modify.
+
+
+templateArray (array):
+The array to symmetric difference <targetArray> with.
+
+destinationArray (optional array):
+A variable to set as the destination instead of mutating <targetArray>
+
+Description:
+Use the <symmetric difference> <command> to set the <element(glossary)|elements>
+from an <array> according to the contents of another <array>.
+
+Each key of <targetArray> is checked to see whether there is a matching
+<key> in <templateArray>. The <element(glossary)|elements> of
+<targetArray> that match an <element(keyword)> of the <templateArray>
+are removed from <targetArray> while the <element(glossary)|elements> of
+the <templateArray> that have no corresponding <element(keyword)> in
+the <targetArray> are added to the <targetArray>.
+
+The content of individual elements of the <templateArray> does not
+affect the final result. Only which <element(glossary)|elements> exist
+in the <templateArray>, not their content, controls which
+<element(glossary)|elements> of <targetArray> are retained and which are
+removed.
+
+If the into clause is used the operation of the commands is the same as
+the non-into form except that <targetArray> does not have to be a
+variable, and the result of the operation is placed into
+<destinationArray> rather than mutating <targetArray>.
+
+References: split (command), union (command), element (glossary),
+array (glossary), command (glossary), key (glossary), element (keyword),
+intersect (command), difference (command)
+
+Tags: properties
diff --git a/docs/dictionary/command/union.lcdoc b/docs/dictionary/command/union.lcdoc
@@ -2,7 +2,7 @@ Name: union
 
 Type: command
 
-Syntax: union <targetArray> with <templateArray> [recursively]
+Syntax: union <targetArray> with <templateArray> [recursively] [into <destinationArray>]
 
 Summary:
 Combines two arrays.
@@ -79,6 +79,8 @@ The value to modify.
 templateArray (array):
 The array to intersect <array> with.
 
+destinationArray (optional array):
+A variable to set as the destination instead of mutating <targetArray>
 
 Description:
 Use the <union> <command> to combine two <array|arrays>, eliminating
@@ -106,9 +108,17 @@ in the <templateArray>, not their content, controls which
 <keys> but different content in each <element(keyword)>, the <union>
 <command> does not change the value of <targetArray>.
 
+If the into clause is used the operation of the commands is the same as
+the non-into form except that <targetArray> does not have to be a
+variable, and the result of the operation is placed into
+<destinationArray> rather than mutating <targetArray>.
+
+Changes:
+The `into` clause was added in LiveCode 9.
+
 References: add (command), intersect (command), keys (function),
 element (glossary), key (glossary), command (glossary), array (glossary),
-execute (glossary), element (keyword), + (operator)
+execute (glossary), element (keyword), + (operator),
+difference (command), symmetric difference (command)
 
 Tags: properties
-
diff --git a/docs/notes/bugfix-11323.md b/docs/notes/bugfix-11323.md
@@ -0,0 +1,19 @@
+# New array commands `difference` and `symmetric difference`
+
+The `difference` command removes all keys from the destination
+which are present in the source, and leaves all others alone.
+
+The `symmetric difference` command removes all keys from the
+destination which are present in the source, and adds all keys
+from the source which are not present in the destination.
+
+Additionally the `into` clause has been added to all array set
+set operations (`union`, `intersect`, `difference`, `symmetric difference`)
+allowing commands such as:
+
+   intersect tLeft with tRight into tResult
+
+The operation of the commands is the same as the non-into form
+except that tLeft does not have to be a variable, and the result
+of the operation is placed into tResult rather than mutating
+tLeft.
diff --git a/engine/src/cmds.h b/engine/src/cmds.h
@@ -23,6 +23,7 @@ along with LiveCode.  If not see <http://www.gnu.org/licenses/>.  */
 #include "regex.h"
 #include "util.h"
 #include "uidc.h"
+#include "variable.h"
 
 // general commands in cmds.cc
 
@@ -1756,41 +1757,35 @@ class MCSplit : public MCArrayOp
 
 class MCSetOp : public MCStatement
 {
-	MCVarref *destvar;
-	MCExpression *source;
-protected:
-	bool intersect : 1;
-    // MERG-2013-08-26: [[ RecursiveArrayOp ]] Support nested arrays in union and intersect
-    bool recursive : 1;
 public:
-	MCSetOp()
-	{
-		source = NULL;
-		destvar = NULL;
-	}
-	virtual ~MCSetOp();
+    enum Op
+    {
+        kOpNone,
+        kOpUnion,
+        kOpUnionRecursively,
+        kOpIntersect,
+        kOpIntersectRecursively,
+        kOpDifference,
+        kOpSymmetricDifference
+    };
+
+private:
+	MCAutoPointer<MCVarref> destvar;
+    MCAutoPointer<MCExpression> destexpr;
+	MCAutoPointer<MCExpression> source;
+    Op op = kOpNone;
+    bool is_into = false;
+
+public:
+    MCSetOp(Op p_op)
+        : op(p_op)
+    {
+    }
 	virtual Parse_stat parse(MCScriptPoint &);
     virtual void exec_ctxt(MCExecContext &ctxt);
 	virtual void compile(MCSyntaxFactoryRef);
 };
 
-class MCArrayIntersectCmd : public MCSetOp
-{
-public:
-	MCArrayIntersectCmd()
-	{
-		intersect = True;
-	}
-};
-
-class MCArrayUnionCmd : public MCSetOp
-{
-public:
-	MCArrayUnionCmd()
-	{
-		intersect = False;
-	}
-};
 
 // MCStack manipulation comands in cmdss.cc