Provide example for singleton arrays (#10941)

reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md

@@ -1,7 +1,7 @@
 ---
 description: Describes arrays, which are data structures designed to store collections of items.
 Locale: en-US
-ms.date: 01/17/2023
+ms.date: 03/07/2024
 no-loc: [Count, Length, LongLength, Rank, ForEach, Clear, Default, First, Last, SkipUntil, Until, Split, Tuple]
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_arrays?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
@@ -894,38 +894,78 @@ In Windows PowerShell, objects created by casting a **Hashtable** to
 `[pscustomobject]` do not have the **Length** or **Count** properties.
 Attempting to access these members returns `$null`.
 
-The following examples demonstrate this feature.
-
-### Zero objects
+The following example shows that a variable that contains no objects has a
+**Count** and **Length** of 0.
 
 ```powershell
-$a = $null
-$a.Count
-$a.Length
-```
-
-```Output
+PS> $a = $null
+PS> $a.Count
 0
+PS> $a.Length
 0
 ```
 
-### One object
+The following example shows that a variable that contains one object has a
+**Count** and **Length** of 1. You can also use array indexing to access the
+value of the object.
 
 ```powershell
-$a = 4
-$a.Count
-$a.Length
-$a[0]
-$a[-1]
+PS> $a = 4
+PS> $a.Count
+1
+PS> $a.Length
+1
+PS> $a[0]
+4
+PS> $a[-1]
+4
 ```
 
-```Output
-1
+When you run a command that could return a collection or a single object, you
+can use array indexing to access the value of the object without having to test
+the **Count** or **Length** properties. However, if the result is a single
+object (singleton), and that object has a **Count** or **Length** property, the
+value of those properties belong to the singleton object and don't represent
+the number of items in the collection.
+
+In the following example, the command returns a single string object. The
+**Length** of that string is `4`.
+
+```powershell
+PS> $result = 'one','two','three','four' | Where-Object {$_ -like 'f*'}
+PS> $result.GetType().FullName
+System.String
+PS> $result
+four
+PS> $result.Count
 1
+PS❯ $result.Length
 4
+```
+
+If you want `$result` to be an array of strings, you need to declare the
+variable as an array.
+
+In this example, `$result` is an array of strings. The **Count** and **Length**
+of the array is `1`, and the **Length** of the first element is `4`.
+
+```powershell
+PS> [string[]]$result = 'one','two','three','four' |
+    Where-Object {$_ -like 'f*'}
+PS> $result.GetType().FullName
+System.String[]
+PS> $result
+four
+PS> $result.Count
+1
+PS> $result.Length
+1
+PS> $result[0].Length
 4
 ```
 
+
+
 ## Indexing .NET types that implement `IDictionary<TKey, TValue>`
 
 PowerShell doesn't call a type's true indexer for types that implement the

reference/5.1/Microsoft.PowerShell.Core/About/about_Variables.md

@@ -1,7 +1,7 @@
 ---
 description: Describes how variables store values that can be used in PowerShell.
 Locale: en-US
-ms.date: 08/28/2021
+ms.date: 03/07/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_variables?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Variables
@@ -26,7 +26,7 @@ such as `$a`, `$process`, or `$my_var`.
 Variable names aren't case-sensitive, and can include spaces and special
 characters. But, variable names that include special characters and spaces are
 difficult to use and should be avoided. For more information, see
-[Variable names that include special characters](#variable-names-that-include-special-characters).
+[Variable names that include special characters][01].
 
 There are several different types of variables in PowerShell.
 
@@ -44,7 +44,7 @@ There are several different types of variables in PowerShell.
   PowerShell installation directory.
 
   For more information, a list, and a description of the automatic variables,
-  see [about_Automatic_Variables](about_Automatic_Variables.md).
+  see [about_Automatic_Variables][04].
 
 - Preference variables: Preference variables store user preferences for
   PowerShell. These variables are created by PowerShell and are populated with
@@ -53,7 +53,7 @@ There are several different types of variables in PowerShell.
   in the session history.
 
   For more information, a list, and a description of the preference variables,
-  see [about_Preference_Variables](about_Preference_Variables.md).
+  see [about_Preference_Variables][08].
 
 ## Working with variables
 
@@ -142,8 +142,7 @@ Clear-Variable -Name MyVariable
 $MyVariable = $null
 ```
 
-To delete the variable, use [Remove-Variable](xref:Microsoft.PowerShell.Utility.Remove-Variable)
-or [Remove-Item](xref:Microsoft.PowerShell.Management.Remove-Item).
+To delete the variable, use [Remove-Variable][16] or [Remove-Item][14].
 
 ```powershell
 Remove-Variable -Name MyVariable
@@ -168,7 +167,7 @@ $i,$j = 10, "red", $true       # $i is 10, $j is [object[]], Length 2
 ```
 
 For more detailed information, see the **Assigning multiple variables** section
-of [about_Assignment_Operators](about_assignment_operators.md#assigning-multiple-variables).
+of [about_Assignment_Operators][03].
 
 ## Types of variables
 
@@ -181,8 +180,7 @@ a particular type of object. A single variable can even contain a collection,
 or array, of different types of objects at the same time.
 
 The data type of a variable is determined by the .NET types of the values of
-the variable. To view a variable's object type, use
-[Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member).
+the variable. To view a variable's object type, use [Get-Member][15].
 
 For example:
 
@@ -212,8 +210,8 @@ $number = "Hello"
 ```
 
 ```Output
-Cannot convert value "Hello" to type "System.Int32". Error: "Input string was
- not in a correct format."
+Cannot convert value "Hello" to type "System.Int32". Error: "Input string
+was not in a correct format."
 At line:1 char:1
 + $number = "Hello"
 + ~~~~~~~~~~~~~~~~~
@@ -264,7 +262,7 @@ If the variable name and dollar sign are enclosed in single quotation (`'`)
 marks, the variable name is used in the expression.
 
 For more information about using quotation marks in PowerShell, see
-[about_Quoting_Rules](about_Quoting_Rules.md).
+[about_Quoting_Rules][10].
 
 This example gets the value of the `$PROFILE` variable, which is the path to
 the PowerShell user profile file in the PowerShell console.
@@ -274,7 +272,7 @@ $PROFILE
 ```
 
 ```Output
-C:\Users\User01\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
+C:\Users\User01\Documents\PowerShell\Microsoft.PowerShell_profile.ps1
 ```
 
 In this example, two commands are shown that can open the PowerShell profile in
@@ -324,7 +322,7 @@ Alphanumeric variable names can contain these characters:
 - Question mark (`?`) character.
 
 The following list contains the Unicode category descriptions. For more
-information, see [UnicodeCategory](/dotnet/api/system.globalization.unicodecategory).
+information, see [UnicodeCategory][17].
 
 - **Lu** - UppercaseLetter
 - **Ll** - LowercaseLetter
@@ -347,7 +345,7 @@ Special character variable names can contain these characters:
 
 PowerShell has reserved variables such as `$$`, `$?`, `$^`, and `$_` that
 contain alphanumeric and special characters. For more information, see
-[about_Automatic_Variables](about_automatic_variables.md).
+[about_Automatic_Variables][04].
 
 For example, the following command creates the variable named `save-items`. The
 curly braces (`{}`) are needed because variable name includes a hyphen (`-`)
@@ -391,7 +389,7 @@ By default, variables are only available in the scope in which they're created.
 For example, a variable that you create in a function is available only within
 the function. A variable that you create in a script is available only within
 the script. If you dot-source the script, the variable is added to the current
-scope. For more information, see [about_Scopes](about_Scopes.md).
+scope. For more information, see [about_Scopes][12].
 
 You can use a scope modifier to change the default scope of the variable. The
 following expression creates a variable named `Computers`. The variable has a
@@ -405,7 +403,7 @@ For any script or command that executes out of session, you need the `Using`
 scope modifier to embed variable values from the calling session scope, so that
 out of session code can access them.
 
-For more information, see [about_Remote_Variables](about_Remote_Variables.md).
+For more information, see [about_Remote_Variables][11].
 
 ## Saving variables
 
@@ -424,7 +422,7 @@ $VerbosePreference = "Continue"
 
 You can add this command to your PowerShell profile by opening the `$PROFILE`
 file in a text editor, such as **notepad.exe**. For more information about
-PowerShell profiles, see [about_Profiles](about_Profiles.md).
+PowerShell profiles, see [about_Profiles][09].
 
 ## The Variable: drive
 
@@ -469,16 +467,15 @@ Get-Help Variable
 ## Variable syntax with provider paths
 
 You can prefix a provider path with the dollar (`$`) sign, and access the
-content of any provider that implements the
-[IContentCmdletProvider](/dotnet/api/system.management.automation.provider.icontentcmdletprovider)
+content of any provider that implements the [IContentCmdletProvider][18]
 interface.
 
 The following built-in PowerShell providers support this notation:
 
-- [about_Environment_Provider](about_Environment_Provider.md)
-- [about_Variable_Provider](about_Variable_Provider.md)
-- [about_Function_Provider](about_Function_Provider.md)
-- [about_Alias_Provider](about_Alias_Provider.md)
+- [about_Environment_Provider][05]
+- [about_Variable_Provider][13]
+- [about_Function_Provider][07]
+- [about_Alias_Provider][02]
 
 ## The variable cmdlets
 
@@ -496,8 +493,8 @@ To get help for a specific cmdlet, type:
 Get-Help <cmdlet-name>
 ```
 
-| Cmdlet Name       | Description                                |
-| ---------------   | ------------------------------------------ |
+|    Cmdlet Name    |                Description                 |
+| ----------------- | ------------------------------------------ |
 | `Clear-Variable`  | Deletes the value of a variable.           |
 | `Get-Variable`    | Gets the variables in the current console. |
 | `New-Variable`    | Creates a new variable.                    |
@@ -506,10 +503,30 @@ Get-Help <cmdlet-name>
 
 ## See also
 
-- [about_Automatic_Variables](about_Automatic_Variables.md)
-- [about_Environment_Variables](about_Environment_Variables.md)
-- [about_Preference_Variables](about_Preference_Variables.md)
-- [about_Profiles](about_Profiles.md)
-- [about_Quoting_Rules](about_Quoting_Rules.md)
-- [about_Remote_Variables](about_Remote_Variables.md)
-- [about_Scopes](about_Scopes.md)
+- [about_Automatic_Variables][04]
+- [about_Environment_Variables][06]
+- [about_Preference_Variables][08]
+- [about_Profiles][09]
+- [about_Quoting_Rules][10]
+- [about_Remote_Variables][11]
+- [about_Scopes][12]
+
+<!-- link references -->
+[01]: #variable-names-that-include-special-characters
+[02]: about_Alias_Provider.md
+[03]: about_assignment_operators.md#assigning-multiple-variables
+[04]: about_Automatic_Variables.md
+[05]: about_Environment_Provider.md
+[06]: about_Environment_Variables.md
+[07]: about_Function_Provider.md
+[08]: about_Preference_Variables.md
+[09]: about_Profiles.md
+[10]: about_Quoting_Rules.md
+[11]: about_Remote_Variables.md
+[12]: about_Scopes.md
+[13]: about_Variable_Provider.md
+[14]: xref:Microsoft.PowerShell.Management.Remove-Item
+[15]: xref:Microsoft.PowerShell.Utility.Get-Member
+[16]: xref:Microsoft.PowerShell.Utility.Remove-Variable
+[17]: xref:System.Globalization.UnicodeCategory
+[18]: xref:System.Management.Automation.Provider.IContentCmdletProvider