Add Magic-method-Where

Basic/Magic-method-Where/.test.ps1

@@ -0,0 +1,17 @@
+
+task Test-1.magic-Where.ps1 {
+	($1, $2, $3, $4, $5, $6 = ./Test-1.magic-Where.ps1)
+	equals $1 'Collection`1'
+	equals $2 0
+	equals $3 'Collection`1'
+	equals $4 1
+	equals $5 'Collection`1'
+	equals $6 2
+}
+
+task Test-2.Where-Object.ps1 {
+	($1, $2, $3 = ./Test-2.Where-Object.ps1)
+	equals $1 $true
+	equals $2 String
+	equals $3 Object[]
+}

Basic/Magic-method-Where/README.md

@@ -0,0 +1,21 @@
+# Magic method `Where`
+
+The magic method `Where` is similar to the cmdlet `Where-Object` but not
+exactly the same. The differences may lead to subtle mistakes, e.g.
+on carelessly changing some code from using one to another.
+
+The magic method `Where` returns a collection of zero, one, or more items.
+The result type is always ``[System.Collections.ObjectModel.Collection`1[PSObject]]``.
+
+In same cases, i.e. with same input and script blocks, the cmdlet `Where-Object`
+returns either nothing (kind of null) or one item (the type depends on it)
+or an array of items. The result type is none, some, or `System.Object[]`.
+
+**Scripts**
+
+- [Test-1.magic-Where.ps1](Test-1.magic-Where.ps1)
+- [Test-2.Where-Object.ps1](Test-2.Where-Object.ps1)
+
+---
+
+- [ForEach and Where magic methods](https://powershellmagazine.com/2014/10/22/foreach-and-where-magic-methods/)

Basic/Magic-method-Where/Test-1.magic-Where.ps1

@@ -0,0 +1,16 @@
+$items = 'apple', 'banana', 'orange'
+
+# Empty collection
+$r = $items.Where({$_ -like 'foo*'})
+$r.GetType().Name
+$r.Count
+
+# Collection of 1 item
+$r = $items.Where({$_ -like 'ban*'})
+$r.GetType().Name
+$r.Count
+
+# Collection of 2 items
+$r = $items.Where({$_ -like '*an*'})
+$r.GetType().Name
+$r.Count

Basic/Magic-method-Where/Test-2.Where-Object.ps1

@@ -0,0 +1,13 @@
+$items = 'apple', 'banana', 'orange'
+
+# Nothing, kind of null
+$r = $items | Where-Object {$_ -like 'foo*'}
+$null -eq $r
+
+# String
+$r = $items | Where-Object {$_ -like 'ban*'}
+$r.GetType().Name
+
+# Array
+$r = $items | Where-Object {$_ -like '*an*'}
+$r.GetType().Name

README.md

@@ -46,6 +46,7 @@ to their directory. See also [TESTS]. Some scripts require
 - [Invocation with odd paths](Basic/Invocation-with-odd-paths)
 - [LastExitCode](Basic/LastExitCode)
 - [Local action preference variables](Basic/Local-ActionPreference)
+- [Magic method `Where`](Basic/Magic-method-Where)
 - [Misleading error location](Basic/Misleading-error-location)
 - [Missing ternary operator](Basic/Missing-ternary-operator)
 - [Negative number literal argument](Basic/Negative-number-literal-argument)