From 4f60067ad2504a3f79c6200a347485ed138eb593 Mon Sep 17 00:00:00 2001
From: Roman Kuzmin <nightroman@gmail.com>
Date: Sun, 29 Sep 2024 07:20:16 +0000
Subject: [PATCH] Add Magic-method-Where

---
 Basic/Magic-method-Where/.test.ps1            | 17 +++++++++++++++
 Basic/Magic-method-Where/README.md            | 21 +++++++++++++++++++
 .../Magic-method-Where/Test-1.magic-Where.ps1 | 16 ++++++++++++++
 .../Test-2.Where-Object.ps1                   | 13 ++++++++++++
 README.md                                     |  1 +
 5 files changed, 68 insertions(+)
 create mode 100644 Basic/Magic-method-Where/.test.ps1
 create mode 100644 Basic/Magic-method-Where/README.md
 create mode 100644 Basic/Magic-method-Where/Test-1.magic-Where.ps1
 create mode 100644 Basic/Magic-method-Where/Test-2.Where-Object.ps1

diff --git a/Basic/Magic-method-Where/.test.ps1 b/Basic/Magic-method-Where/.test.ps1
new file mode 100644
index 0000000..1a1c109
--- /dev/null
+++ b/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[]
+}
diff --git a/Basic/Magic-method-Where/README.md b/Basic/Magic-method-Where/README.md
new file mode 100644
index 0000000..27c7625
--- /dev/null
+++ b/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/)
diff --git a/Basic/Magic-method-Where/Test-1.magic-Where.ps1 b/Basic/Magic-method-Where/Test-1.magic-Where.ps1
new file mode 100644
index 0000000..90d12d0
--- /dev/null
+++ b/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
diff --git a/Basic/Magic-method-Where/Test-2.Where-Object.ps1 b/Basic/Magic-method-Where/Test-2.Where-Object.ps1
new file mode 100644
index 0000000..b772064
--- /dev/null
+++ b/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
diff --git a/README.md b/README.md
index 9d2e066..ad14875 100644
--- a/README.md
+++ b/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)