Skip to content

Commit 6c862f4

Browse files
montegouldingmontegoulding
committed
[Bug 11323] Add docs and release note
1 parent 330ef89 commit 6c862f4

5 files changed

Lines changed: 182 additions & 6 deletions

File tree

‎docs/dictionary/command/difference.lcdoc‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
Name: difference
2+
3+
Type: command
4+
5+
Syntax: difference <targetArray> with <templateArray> [into <destinationArray>]
6+
7+
Summary:
8+
Removes <element(glossary)|elements> from an <array> which have a
9+
corresponding <element(keyword)> in another <array>, and leaves all
10+
others alone.
11+
12+
Introduced: 9.0
13+
14+
OS: mac, windows, linux, ios, android
15+
16+
Platforms: desktop, server, mobile
17+
18+
Example:
19+
local tLeft, tRight
20+
put "green" into tLeft["color"]
21+
put "left" into tLeft["align"]
22+
23+
put "blue" into tRight["color"]
24+
put "100" into tRight["width"]
25+
26+
difference tLeft with tRight
27+
28+
# RESULT
29+
# the keys of tLeft = "align"
30+
# tRight unchanged
31+
32+
Parameters:
33+
targetArray (array):
34+
The value to modify.
35+
36+
37+
templateArray (array):
38+
The array to difference <targetArray> with.
39+
40+
destinationArray (optional array):
41+
A variable to set as the destination instead of mutating <targetArray>
42+
43+
Description:
44+
Use the <difference> <command> to filter out <element(glossary)|elements>
45+
from an <array> according to the contents of another <array>.
46+
47+
Each key of <targetArray> is checked to see whether there is a matching
48+
<key> in <templateArray>. The <element(glossary)|elements> of
49+
<targetArray> that match an <element(keyword)> of the <templateArray>
50+
are removed from <targetArray>.
51+
52+
The content of individual elements of the <templateArray> does not
53+
affect the final result. Only which <element(glossary)|elements> exist
54+
in the <templateArray>, not their content, controls which
55+
<element(glossary)|elements> of <targetArray> are retained and which are
56+
removed.
57+
58+
If the into clause is used the operation of the commands is the same as
59+
the non-into form except that <targetArray> does not have to be a
60+
variable, and the result of the operation is placed into
61+
<destinationArray> rather than mutating <targetArray>.
62+
63+
References: split (command), union (command), element (glossary),
64+
array (glossary), command (glossary), key (glossary), element (keyword),
65+
intersect (command), symmetric difference (command)
66+
67+
Tags: properties

‎docs/dictionary/command/intersect.lcdoc‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ Name: intersect
22

33
Type: command
44

5-
Syntax: intersect <targetArray> with <templateArray> [recursively]
5+
Syntax: intersect <targetArray> with <templateArray> [recursively] [into <destinationArray>]
66

77
Summary:
88
Removes <element(glossary)|elements> from an <array> if they have no
@@ -80,6 +80,8 @@ The value to modify.
8080
templateArray (array):
8181
The array to intersect <array> with.
8282

83+
destinationArray (optional array):
84+
A variable to set as the destination instead of mutating <targetArray>
8385

8486
Description:
8587
Use the <intersect> <command> to filter out <element(glossary)|elements>
@@ -106,8 +108,16 @@ removed. If <targetArray> and <templateArray> have the same set of
106108
<element(keyword)>, the <intersect> <command> does not change the value
107109
of <targetArray>.
108110

111+
If the into clause is used the operation of the commands is the same as
112+
the non-into form except that <targetArray> does not have to be a
113+
variable, and the result of the operation is placed into
114+
<destinationArray> rather than mutating <targetArray>.
115+
116+
Changes:
117+
The `into` clause was added in LiveCode 9.
118+
109119
References: split (command), union (command), element (glossary),
110-
array (glossary), command (glossary), key (glossary), element (keyword)
120+
array (glossary), command (glossary), key (glossary), element (keyword),
121+
difference (command), symmetric difference (command)
111122

112123
Tags: properties
113-

‎docs/dictionary/command/symmetric-difference.lcdoc‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
Name: symmetric difference
2+
3+
Type: command
4+
5+
Syntax: symmetric difference <targetArray> with <templateArray> [into <destinationArray>]
6+
7+
Summary:
8+
Removes <element(glossary)|elements> from a target <array> which have a
9+
corresponding <element(keyword)> in a template <array>, and adds
10+
<element(glossary)|elements> from the template <array> that have no
11+
which have no corresponding <element(keyword)> in the target <array>.
12+
13+
Introduced: 9.0
14+
15+
OS: mac, windows, linux, ios, android
16+
17+
Platforms: desktop, server, mobile
18+
19+
Example:
20+
local tLeft, tRight
21+
put "green" into tLeft["color"]
22+
put "left" into tLeft["align"]
23+
24+
put "blue" into tRight["color"]
25+
put "100" into tRight["width"]
26+
27+
symmetric difference tLeft with tRight
28+
29+
# RESULT
30+
# the keys of tLeft = "align" & "width"
31+
# tRight unchanged
32+
33+
Parameters:
34+
targetArray (array):
35+
The value to modify.
36+
37+
38+
templateArray (array):
39+
The array to symmetric difference <targetArray> with.
40+
41+
destinationArray (optional array):
42+
A variable to set as the destination instead of mutating <targetArray>
43+
44+
Description:
45+
Use the <symmetric difference> <command> to set the <element(glossary)|elements>
46+
from an <array> according to the contents of another <array>.
47+
48+
Each key of <targetArray> is checked to see whether there is a matching
49+
<key> in <templateArray>. The <element(glossary)|elements> of
50+
<targetArray> that match an <element(keyword)> of the <templateArray>
51+
are removed from <targetArray> while the <element(glossary)|elements> of
52+
the <templateArray> that have no corresponding <element(keyword)> in
53+
the <targetArray> are added to the <targetArray>.
54+
55+
The content of individual elements of the <templateArray> does not
56+
affect the final result. Only which <element(glossary)|elements> exist
57+
in the <templateArray>, not their content, controls which
58+
<element(glossary)|elements> of <targetArray> are retained and which are
59+
removed.
60+
61+
If the into clause is used the operation of the commands is the same as
62+
the non-into form except that <targetArray> does not have to be a
63+
variable, and the result of the operation is placed into
64+
<destinationArray> rather than mutating <targetArray>.
65+
66+
References: split (command), union (command), element (glossary),
67+
array (glossary), command (glossary), key (glossary), element (keyword),
68+
intersect (command), difference (command)
69+
70+
Tags: properties

‎docs/dictionary/command/union.lcdoc‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ Name: union
22

33
Type: command
44

5-
Syntax: union <targetArray> with <templateArray> [recursively]
5+
Syntax: union <targetArray> with <templateArray> [recursively] [into <destinationArray>]
66

77
Summary:
88
Combines two arrays.
@@ -79,6 +79,8 @@ The value to modify.
7979
templateArray (array):
8080
The array to intersect <array> with.
8181

82+
destinationArray (optional array):
83+
A variable to set as the destination instead of mutating <targetArray>
8284

8385
Description:
8486
Use the <union> <command> to combine two <array|arrays>, eliminating
@@ -106,9 +108,17 @@ in the <templateArray>, not their content, controls which
106108
<keys> but different content in each <element(keyword)>, the <union>
107109
<command> does not change the value of <targetArray>.
108110

111+
If the into clause is used the operation of the commands is the same as
112+
the non-into form except that <targetArray> does not have to be a
113+
variable, and the result of the operation is placed into
114+
<destinationArray> rather than mutating <targetArray>.
115+
116+
Changes:
117+
The `into` clause was added in LiveCode 9.
118+
109119
References: add (command), intersect (command), keys (function),
110120
element (glossary), key (glossary), command (glossary), array (glossary),
111-
execute (glossary), element (keyword), + (operator)
121+
execute (glossary), element (keyword), + (operator),
122+
difference (command), symmetric difference (command)
112123

113124
Tags: properties
114-

‎docs/notes/bugfix-11323.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# New array commands `difference` and `symmetric difference`
2+
3+
The `difference` command removes all keys from the destination
4+
which are present in the source, and leaves all others alone.
5+
6+
The `symmetric difference` command removes all keys from the
7+
destination which are present in the source, and adds all keys
8+
from the source which are not present in the destination.
9+
10+
Additionally the `into` clause has been added to all array set
11+
set operations (`union`, `intersect`, `difference`, `symmetric difference`)
12+
allowing commands such as:
13+
14+
intersect tLeft with tRight into tResult
15+
16+
The operation of the commands is the same as the non-into form
17+
except that tLeft does not have to be a variable, and the result
18+
of the operation is placed into tResult rather than mutating
19+
tLeft.

0 commit comments

Comments
 (0)