union

Typecommand
DictionaryLCS
LibraryLiveCode Script
Syntax
union <targetArray> with <templateArray> [recursively] [into <destinationArray>]
Summary

Combines two arrays.

Introduced1.1
Changes

The into clause was added in LiveCode 9.

OSmac, windows, linux, ios, android
Platformsdesktop, server, mobile
Parameters
NameTypeDescription
targetArray

The value to modify.

templateArray

The array to intersect array with.

destinationArray

A variable to set as the destination instead of mutating targetArray

Example
local tLeft, tRight
put "green" into tLeft["color"]
put "left" into tLeft["align"]

put "blue" into tRight["color"]
put "100" into tRight["width"]

union tLeft with tRight

# RESULT
# tLeft["colour"] = "green"
# tLeft["align"] = "left"
# tLeft["width"] = "100"

# tRight unchanged
local tLeft, tRight
put "a" into tLeft[1][1]
put "z" into tRight[1][2]

union tLeft with tRight -- tLeft unchanged

union tLeft with tRight recursively
# RESULT
# tLeft[1][1] = "a"
# tLeft[1][2] = "z"
# tRight unchanged
function ScriptUnion pLeft, pRight, pRecursive
    repeat for each key tKey in pRight
        if tKey is not among the keys of pLeft then
            put pRight[tKey] into pLeft[tKey]
        else if pRecursive then
            put ScriptUnion(pLeft[tKey], pRight[tKey], true) into pLeft[tKey]
        end if
    end repeat

    return pLeft
end ScriptUnion

function EngineUnion pLeft, pRight, pRecursive
    if pRecursive then
        union pLeft with pRight recursively
    else
        union pLeft with pRight
    end if

    return pLeft
end EngineUnion

-- This function should return true for all inputs.
function CheckUnion pLeft, pRight, pRecursive
    return ScriptUnion(pLeft, pRight, pRecursive) is EngineUnion(pLeft, pRight, pRecursive)
end CheckUnion
RelatedKeyword: element
Operator: +
Command: add, intersect, difference, symmetric difference
Function: keys
Glossary: element, key, command, array, execute
Description

Use the union command to combine two arrays, eliminating duplicate elements.

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

The union command combines targetArray and templateArray. Each key of targetArray is checked to see whether there is already an element with that key in templateArray. If there is, that element of targetArray is unchanged. If not, the corresponding element of the templateArray is placed in targetArray.

After the union command is executed, the keys of targetArray consists of the logical union of the keys of the original targetArray and the keys of templateArray.

The content of individual elements of the templateArray does not control the final result. Only which elements exist in the templateArray, not their content, controls which elements of the templateArray are placed in targetArray. If targetArray and templateArray have the same set of keys but different content in each element, 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.

Tagsproperties