Clarify facts about intrinsic properties Count and Length (#11626)

Author: sdwheeler

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: 03/07/2024
+ms.date: 01/03/2025
 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
@@ -10,6 +10,7 @@ title: about_Arrays
 # about_Arrays
 
 ## Short description
+
 Describes arrays, which are data structures designed to store collections of
 items.
 
@@ -341,9 +342,25 @@ while($i -lt 4) {
 
 ### Count or Length or LongLength
 
-To determine how many items are in an array, use the **Length** property or its
-**Count** alias. **Longlength** is useful if the array contains more than
-2,147,483,647 elements.
+In PowerShell, arrays have three properties that indicate the number of items
+contained in the array.
+
+- **Count** - This property is the most commonly used property to determine the
+  number of items in any collection, not just an array. It's an `[Int32]` type
+  value. In Windows PowerShell 5.1 (and older) **Count** alias property for
+  **Length**.
+
+- **Length** - This property is an `[Int32]` type value. This contains the same
+  value as **Count**.
+
+  > [!NOTE]
+  > While **Count** and **Length** are equivalent for arrays, **Length** can
+  > have a different meaning for other types. For example, **Length** for a
+  > string is the number of characters in the string. But the **Count**
+  > property is always `1`.
+
+- **Longlength** - This property is an `[Int64]` type value. Use this property
+  for arrays containing more than 2,147,483,647 elements.
 
 ```powershell
 $a = 0..9
@@ -470,7 +487,7 @@ True
 In this example, `$intA` is explicitly typed to contain integers.
 
 ```powershell
-[int[]] $intA = 1, 2, 3
+[Int[]] $intA = 1, 2, 3
 $intA.Clear()
 $intA
 ```
@@ -488,7 +505,7 @@ for each element of the array.
 
 The `ForEach()` method has several overloads that perform different operations.
 
-```
+```Syntax
 ForEach(scriptblock expression)
 ForEach(scriptblock expression, object[] arguments)
 ForEach(type convertToType)
@@ -884,10 +901,11 @@ faster, especially for large arrays.
 
 ## Arrays of zero or one
 
-Beginning in Windows PowerShell 3.0, a collection of zero or one object has the
-**Count** and **Length** properties. Also, you can index into an array of one
-object. This feature helps you to avoid scripting errors that occur when a
-command that expects a collection gets fewer than two items.
+Beginning in Windows PowerShell 3.0, a scalar types and collection of zero or
+one objects has the **Count** and **Length** properties. Also, you can use
+array index notation to access the value of a singleton scalar object. This
+feature helps you to avoid scripting errors that occur when a command that
+expects a collection gets fewer than two items.
 
 > [!NOTE]
 In Windows PowerShell, objects created by casting a **Hashtable** to

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

@@ -1,7 +1,7 @@
 ---
 description: Describes automatic members in all PowerShell objects
 Locale: en-US
-ms.date: 01/10/2024
+ms.date: 01/03/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_Intrinsic_Members?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Intrinsic_Members
@@ -167,8 +167,15 @@ information on how to use these methods, see [about_Arrays][01].
 
 ## Properties
 
-The **Count** and **Length** properties are available to all PowerShell
-objects, not just collections. These are similar to each other but may work
+Not all scalar type have **Count** or **Length** properties in the base type.
+PowerShell adds the missing property as an intrinsic member for all scalar
+types.
+
+> [!NOTE]
+> Uninitialized variables are implicitly `$null`. `$null` is scalar and has an
+> intrinsic **Count** and **Length** of 0.
+
+While the **Count** and **Length** properties are similar, they may work
 differently depending on the data type. For example, the **Length** of a string
 is the number of characters in the string. The **Count** property is the number
 of instances of the object.

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

@@ -1,14 +1,15 @@
 ---
 description: Describes how to use object properties in PowerShell.
 Locale: en-US
-ms.date: 08/21/2023
+ms.date: 01/03/2025
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_properties?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Properties
 ---
 # about_Properties
 
 ## Short description
+
 Describes how to use object properties in PowerShell.
 
 ## Long description
@@ -32,7 +33,7 @@ it doesn't. A **DirectoryInfo** object, which represents a file system
 directory, has a **Parent** property that contains the path to the parent
 directory.
 
-### Object properties
+## Object properties
 
 To get the properties of an object, use the `Get-Member` cmdlet. For example,
 to get the properties of a **FileInfo** object, use the `Get-ChildItem` cmdlet
@@ -117,7 +118,7 @@ $a.CreationTime
 ```
 
 ```Output
-Saturday, June 5, 2021 7:07:00 AM
+Wednesday, January 24, 2024 1:18:29 AM
 ```
 
 You can also use the `Select-Object` and `Format-List` cmdlets to display the
@@ -144,10 +145,10 @@ Mode              : -a----
 VersionInfo       : File:             C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
                     InternalName:     POWERSHELL
                     OriginalFilename: PowerShell.EXE.MUI
-                    FileVersion:      10.0.22000.1 (WinBuild.160101.0800)
+                    FileVersion:      10.0.22621.1 (WinBuild.160101.0800)
                     FileDescription:  Windows PowerShell
-                    Product:          Microsoft? Windows? Operating System
-                    ProductVersion:   10.0.22000.1
+                    Product:          Microsoft® Windows® Operating System
+                    ProductVersion:   10.0.22621.1
                     Debug:            False
                     Patched:          False
                     PreRelease:       False
@@ -156,8 +157,8 @@ VersionInfo       : File:             C:\Windows\System32\WindowsPowerShell\v1.0
                     Language:         English (United States)
 
 BaseName          : powershell
-Target            : {C:\Windows\WinSxS\amd64_microsoft-windows-powershell-exe_31bf3856ad364e35_10.0.22000.1_none_bf599c
-                    5a06fbb6f4\powershell.exe}
+Target            : {C:\Windows\WinSxS\amd64_microsoft-windows-powershell-exe_31bf3856ad364e35_10.0.22621.3085_none_492
+                    e8ee57da24e0e\powershell.exe}
 LinkType          : HardLink
 Name              : powershell.exe
 Length            : 450560
@@ -167,20 +168,20 @@ IsReadOnly        : False
 Exists            : True
 FullName          : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
 Extension         : .exe
-CreationTime      : 6/5/2021 7:07:00 AM
-CreationTimeUtc   : 6/5/2021 12:07:00 PM
-LastAccessTime    : 7/18/2022 12:16:17 PM
-LastAccessTimeUtc : 7/18/2022 5:16:17 PM
-LastWriteTime     : 6/5/2021 7:07:00 AM
-LastWriteTimeUtc  : 6/5/2021 12:07:00 PM
+CreationTime      : 1/24/2024 1:18:29 AM
+CreationTimeUtc   : 1/24/2024 7:18:29 AM
+LastAccessTime    : 1/3/2025 1:36:20 PM
+LastAccessTimeUtc : 1/3/2025 7:36:20 PM
+LastWriteTime     : 1/24/2024 1:18:29 AM
+LastWriteTimeUtc  : 1/24/2024 7:18:29 AM
 Attributes        : Archive
 ```
 
-### Static properties
+## Static properties
 
 You can use the static properties of .NET classes in PowerShell. Static
-properties are properties of class, unlike standard properties, which are
-properties of an object.
+properties are properties of the class, unlike standard properties, which are
+properties of an object instance.
 
 To get the static properties of a class, use the **Static** parameter of the
 `Get-Member` cmdlet. For example, the following command gets the static
@@ -218,12 +219,8 @@ property of the `System.DateTime` class.
 ## Member-access enumeration
 
 Starting in PowerShell 3.0, when you use the member-access operator (`.`) to
-access a property that doesn't exist on a list collection, PowerShell
-automatically enumerates the items in the collection and returns the value of
-the property on each item. For more information, see
-[about_Member-Access_Enumeration](about_Member-Access_Enumeration.md).
-
-### Examples
+access a property that doesn't exist, PowerShell automatically enumerates the
+items in the collection and returns the value of the property for each item.
 
 This command returns the value of the **DisplayName** property of every service
 that `Get-Service` returns.
@@ -241,8 +238,8 @@ Application Information
 ...
 ```
 
-All collections have a **Count** property that returns the number of objects in
-the collection.
+Most collections in PowerShell have a **Count** property that returns the
+number items in the collection.
 
 ```powershell
 (Get-Service).Count
@@ -252,50 +249,40 @@ the collection.
 176
 ```
 
-Starting in PowerShell 3.0, you can get the **Count** or **Length** property of
-singleton objects that aren't collections.
+If a property exists on the individual objects and on the collection, only the
+collection's property is returned.
 
 ```powershell
-(Get-Service Audiosrv).Count
-```
-
-```Output
-1
-```
+PS> $collection = @(
+     [pscustomobject]@{Length = "foo"}
+     [pscustomobject]@{Length = "bar"}
+)
 
-However, some objects have a **Length** property. For example, the **Length**
-of a string is the number of characters in the string. The **Count** property
-is the number of instances of the object.
+# PowerShell returns the collection's Length.
+$collection.Length
+2
 
-```powershell
-PS> $str = 'string'
-PS> $str.Length
-6
-PS> $str.Count
-1
+# Get the length property of each item in the collection.
+PS> $collection.GetEnumerator().Length
+foo
+bar
 ```
 
-If a property exists on the individual objects and on the collection, only the
-collection's property is returned.
-
- ```powershell
- $collection = @(
-     [pscustomobject]@{length = "foo"}
-     [pscustomobject]@{length = "bar"}
-)
- # PowerShell returns the collection's Length.
- $collection.length
- ```
-
- ```Output
- 2
- ```
+For more information, see [about_Member-Access_Enumeration][01].
 
 ## See also
 
-- [about_Objects](about_Objects.md)
-- [about_Member-Access_Enumeration](about_Member-Access_Enumeration.md)
-- [about_Methods](about_Methods.md)
-- [Format-List](xref:Microsoft.PowerShell.Utility.Format-List)
-- [Get-Member](xref:Microsoft.PowerShell.Utility.Get-Member)
-- [Select-Object](xref:Microsoft.PowerShell.Utility.Select-Object)
+- [about_Objects][03]
+- [about_Member-Access_Enumeration][01]
+- [about_Methods][02]
+- [Format-List][04]
+- [Get-Member][05]
+- [Select-Object][06]
+
+<!-- link references -->
+[01]: about_Member-Access_Enumeration.md
+[02]: about_Methods.md
+[03]: about_Objects.md
+[04]: xref:Microsoft.PowerShell.Utility.Format-List
+[05]: xref:Microsoft.PowerShell.Utility.Get-Member
+[06]: xref:Microsoft.PowerShell.Utility.Select-Object

reference/7.4/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: 03/07/2024
+ms.date: 01/03/2025
 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-7.4&WT.mc_id=ps-gethelp
 schema: 2.0.0
@@ -10,6 +10,7 @@ title: about_Arrays
 # about_Arrays
 
 ## Short description
+
 Describes arrays, which are data structures designed to store collections of
 items.
 
@@ -67,7 +68,7 @@ values of a particular type, cast the variable as an array type, such as
 variable name with an array type enclosed in brackets. For example:
 
 ```powershell
-[int32[]]$ia = 1500, 2230, 3350, 4000
+[Int32[]]$ia = 1500, 2230, 3350, 4000
 ```
 
 As a result, the `$ia` array can contain only integers.
@@ -341,9 +342,25 @@ while($i -lt 4) {
 
 ### Count or Length or LongLength
 
-To determine how many items are in an array, use the **Length** property or its
-**Count** alias. **Longlength** is useful if the array contains more than
-2,147,483,647 elements.
+In PowerShell, arrays have three properties that indicate the number of items
+contained in the array.
+
+- **Count** - This property is the most commonly used property to determine the
+  number of items in any collection, not just an array. It's an `[Int32]` type
+  value. In Windows PowerShell 5.1 (and older) **Count** alias property for
+  **Length**.
+
+- **Length** - This property is an `[Int32]` type value. This contains the same
+  value as **Count**.
+
+  > [!NOTE]
+  > While **Count** and **Length** are equivalent for arrays, **Length** can
+  > have a different meaning for other types. For example, **Length** for a
+  > string is the number of characters in the string. But the **Count**
+  > property is always `1`.
+
+- **Longlength** - This property is an `[Int64]` type value. Use this property
+  for arrays containing more than 2,147,483,647 elements.
 
 ```powershell
 $a = 0..9
@@ -470,7 +487,7 @@ True
 In this example, `$intA` is explicitly typed to contain integers.
 
 ```powershell
-[int[]] $intA = 1, 2, 3
+[Int[]] $intA = 1, 2, 3
 $intA.Clear()
 $intA
 ```
@@ -488,7 +505,7 @@ for each element of the array.
 
 The `ForEach()` method has several overloads that perform different operations.
 
-```
+```Syntax
 ForEach(scriptblock expression)
 ForEach(scriptblock expression, object[] arguments)
 ForEach(type convertToType)
@@ -884,10 +901,11 @@ faster, especially for large arrays.
 
 ## Arrays of zero or one
 
-Beginning in Windows PowerShell 3.0, a collection of zero or one object has the
-**Count** and **Length** properties. Also, you can index into an array of one
-object. This feature helps you to avoid scripting errors that occur when a
-command that expects a collection gets fewer than two items.
+Beginning in Windows PowerShell 3.0, a scalar types and collection of zero or
+one objects has the **Count** and **Length** properties. Also, you can use
+array index notation to access the value of a singleton scalar object. This
+feature helps you to avoid scripting errors that occur when a command that
+expects a collection gets fewer than two items.
 
 The following example shows that a variable that contains no objects has a
 **Count** and **Length** of 0.