#Scenario, we have 2 arrays. These arrays contain data for the same 1000 items, but each array only contains either the Shape or the Color of the object. We need to join these together.

#Lets create some test data in 2 arrays.
$ItemCount = 1000
$ShapeArray = @(0)*$ItemCount #Pre-initialize your arrays with a length
$ColorArray = @(0)*$ItemCount
$Shapes = @("Square", "Circle", "Ovale", "Rectangle")
$Colors = @("Red", "Green", "Blue", "Orange")

#Now we fill the arrays with random data
$Randomizer = [Random]::new()
for ($I = 0; $I -lt $ItemCount; $I++) {
    $ItemName = [GUID]::NewGuid().ToString()
    $ShapeArray[$I] = New-Object -TypeName PSObject -Property @{Name = $ItemName; Shape=($Shapes[$Randomizer.Next(0,$Shapes.Length)]);}
    #Lets make sure the arrays are not in the same order either
    $ColorArray[$ItemCount-1-$I] = New-Object -TypeName PSObject -Property @{Name = $ItemName; Color=($Colors[$Randomizer.Next(0,$Colors.Length)]);}
}

#Ok, now we have our data, it is in memory, but not in a way that can be quickly queried. Lets see how piping this data works using the normal | Where-Object {} pattern

$PipingMetrics = Measure-Command -Expression {
    foreach ($ObjectShape in $ShapeArray) {
        $ObjectColor = $ColorArray | Where-Object {$_.Name -eq $ObjectShape.Name}
    }
}
#For my test run, this comes to 7697.8312 ms... Pretty slow. 
#Lets turn the ColorArray into a hashtable to speed things up! Since we are linking these two arrays by name, the key in the hashtable will be the name

$ColorHashtable = @{}
foreach ($ObjectColor in $ColorArray) {
    $ColorHashtable.Add($ObjectColor.Name, $ObjectColor)
}

#Now the names of the items in the ColorArray have been index by the hashtable. Lets see how looking this up works now
$HashtableMetrics = Measure-Command -Expression {
    foreach ($ObjectShape in $ShapeArray) {
        $ObjectColor = $ColorHashtable[$ObjectShape.Name]
    }
}

#For my test run, this comes to 5.748 ms... WAAAY faster.

#Now lets join this data into the same array so we can save it as a CSV

$Results = @(0)*$ItemCount #Pre-initialize your arrays with a length
for ($I =0; $I -lt $ItemCount; $I++) {
    $Results[$I] = New-Object -TypeName PSObject -Property @{Name=$ShapeArray[$I].Name; Shape = $ShapeArray[$I].Shape; Color = $ColorHashtable[$ShapeArray[$I].Name].Color}
}

#And now we have a single array of completed objects. If you needed this for a report you could then export to a CSV
#$Results | Export-Csv -Path <SomePath> -NoTypeInformation