Name: intersect

Type: command

Syntax: intersect <targetArray> with <templateArray> [recursively] [into <destinationArray>]

Summary:
Removes <element(glossary)|elements> from an <array> if they have no
corresponding <element(keyword)> in another <array>.

Introduced: 1.1

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"]

intersect tLeft with tRight

# RESULT
# the keys of tLeft = "colour"
# tLeft["colour"] = "green"
# tRight unchanged

Example:
local tLeft, tRight
put "a" into tLeft[1][1]
put "b" into tLeft[1][2]

put "y" into tRight[1][1]

intersect tLeft with tRight -- tLeft unchanged

intersect tLeft with tRight recursively
# RESULT
# tLeft[1][1] = "a"
# tLeft[1][2] empty
# tRight unchanged

Example:
function ScriptIntersect pLeft, pRight, pRecursive
    repeat for each key tKey in pLeft
        if tKey is not among the keys of pRight then
            delete variable pLeft[tKey]
        else if pRecursive then
            put ScriptIntersect(pLeft[tKey], pRight[tKey], true) into pLeft[tKey]
        end if
    end repeat

    return pLeft
end ScriptIntersect

function EngineIntersect pLeft, pRight, pRecursive
    if pRecursive then
        intersect pLeft with pRight recursively
    else
        intersect pLeft with pRight
    end if

    return pLeft
end EngineIntersect

-- This function should return true for all inputs.
function CheckIntersect pLeft, pRight, pRecursive
    return ScriptIntersect(pLeft, pRight, pRecursive) is EngineIntersect(pLeft, pRight, pRecursive)
end CheckIntersect

Parameters:
targetArray (array):
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>
from an <array> according to the contents of another <array>.

The recursively adverb controls whether the intersection recurses
through nested arrays or not.

Each key of <targetArray> is checked to see whether there is a matching
<key> in <templateArray>. The <element(glossary)|elements> of
<targetArray> that do not match an <element(keyword)> of the
<templateArray> are removed from <targetArray>.

After the <intersection> <command> is <execute|executed>, the <keys> of
<targetArray> consists of the logical intersection of the <keys> of the
original <targetArray> and the keys of <templateArray>.

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 <targetArray> and <templateArray> have the same set of
<element(glossary)|elements> but different content in each
<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),
difference (command), symmetric difference (command)

Tags: properties