Skip to content

Commit aa8947c

Browse files
sdwheelersdwheeler
committed
Fix typos and expand description of behavior
1 parent 49e015e commit aa8947c

4 files changed

Lines changed: 152 additions & 96 deletions

File tree

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

Lines changed: 38 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -585,51 +585,65 @@ Wednesday, June 20, 2018 9:21:57 AM
585585

586586
> [!NOTE]
587587
> The `ForEach()` method wraps properties into a collection before enumeration.
588-
> This wrapping means that accessing the first element of the original
589-
> collection requires two indices `[0][0]`.
588+
> Using `ForEach()` normally returns all items in both array. However, if you
589+
> want to access elements of the wrapped collection, you need to use two
590+
> indices.
590591
591-
Consider the following example:
592+
Consider the following example where the object `$myObject` has a property with
593+
single value and a property containing an array of 11 integers.
592594

593595
```powershell
594-
$c = [pscustomobject]@{
595-
Value = @(0..10)
596-
}
597-
$d = [pscustomobject]@{
598-
Value = @(11..21)
596+
$myObject = [pscustomobject]@{
597+
singleValue = 'Hello'
598+
arrayValue = @(0..10)
599599
}
600600
```
601601

602-
As you can see, both `$c` and `$d` have a property named **Value** that
603-
contains an array of 11 integers. When you use the `ForEach()` method to access
604-
the **Value** property of both objects, the result is a collection of two
605-
arrays. To access the first element of the first array, you need to use two
606-
indices.
602+
When you use the `ForEach()` method to access a property of the object, the
603+
property is wrapped in a collection.
607604

608605
```powershell
609-
PS> ($c, $d).ForEach('Value').Count # 2-element collection
610-
2
611-
PS> ($c, $d).ForEach('Value')[0].Count # Each is an array with 11 elements
606+
PS> $myObject.ForEach('singleValue').GetType().Name
607+
Collection`1
608+
PS> $myObject.ForEach('singleValue')[0].GetType().Name
609+
String
610+
PS> $myObject.ForEach('singleValue') # Enumerate the collection object
611+
Hello
612+
```
613+
614+
To access the an element of the array, you need to use two indices.
615+
616+
```powershell
617+
PS> $myObject.ForEach('arrayValue').GetType().Name
618+
Collection`1
619+
# A single Collection item
620+
PS> $myObject.ForEach('arrayValue').Count
621+
1
622+
# First item in the collection is an array of 11 items
623+
PS> $myObject.ForEach('Value')[0].Count
612624
11
613-
PS> ($c, $d).ForEach('Value')[0][0] # First element of the first array
625+
# Access the first item in the array of 11 items
626+
PS> $myObject.ForEach('Value')[0][0]
614627
0
615-
PS> ($c, $d).ForEach('Value')[1][0] # First element of the second array
616-
11
617628
```
618629

619-
This is different that using the `ForEach()` method using a scriptblock to
630+
This is different than using the `ForEach()` method using with a scriptblock to
620631
access the **Value** property of each object.
621632

622633
```powershell
623-
PS> ($c, $d).ForEach({$_.Value}).Count # 22-element collection
624-
22
634+
PS> $myObject.ForEach({$_.Value}).Count # An array of 11 items
635+
11
625636
```
626637

638+
Use the scriptblock syntax to avoid the wrapping behavior when you want to
639+
access complex property types, such as arrays or nested objects.
640+
627641
#### ForEach(string methodName)
628642

629643
#### ForEach(string methodName, object[] arguments)
630644

631-
Lastly, `ForEach()` methods can be used to execute a method on every item in
632-
the collection.
645+
You can use the `ForEach()` method to execute an object's method on every item
646+
in the collection.
633647

634648
```powershell
635649
("one", "two", "three").ForEach("ToUpper")

‎reference/7.4/Microsoft.PowerShell.Core/About/about_Arrays.md‎

Lines changed: 38 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -585,51 +585,65 @@ Wednesday, June 20, 2018 9:21:57 AM
585585

586586
> [!NOTE]
587587
> The `ForEach()` method wraps properties into a collection before enumeration.
588-
> This wrapping means that accessing the first element of the original
589-
> collection requires two indices `[0][0]`.
588+
> Using `ForEach()` normally returns all items in both array. However, if you
589+
> want to access elements of the wrapped collection, you need to use two
590+
> indices.
590591
591-
Consider the following example:
592+
Consider the following example where the object `$myObject` has a property with
593+
single value and a property containing an array of 11 integers.
592594

593595
```powershell
594-
$c = [pscustomobject]@{
595-
Value = @(0..10)
596-
}
597-
$d = [pscustomobject]@{
598-
Value = @(11..21)
596+
$myObject = [pscustomobject]@{
597+
singleValue = 'Hello'
598+
arrayValue = @(0..10)
599599
}
600600
```
601601

602-
As you can see, both `$c` and `$d` have a property named **Value** that
603-
contains an array of 11 integers. When you use the `ForEach()` method to access
604-
the **Value** property of both objects, the result is a collection of two
605-
arrays. To access the first element of the first array, you need to use two
606-
indices.
602+
When you use the `ForEach()` method to access a property of the object, the
603+
property is wrapped in a collection.
607604

608605
```powershell
609-
PS> ($c, $d).ForEach('Value').Count # 2-element collection
610-
2
611-
PS> ($c, $d).ForEach('Value')[0].Count # Each is an array with 11 elements
606+
PS> $myObject.ForEach('singleValue').GetType().Name
607+
Collection`1
608+
PS> $myObject.ForEach('singleValue')[0].GetType().Name
609+
String
610+
PS> $myObject.ForEach('singleValue') # Enumerate the collection object
611+
Hello
612+
```
613+
614+
To access the an element of the array, you need to use two indices.
615+
616+
```powershell
617+
PS> $myObject.ForEach('arrayValue').GetType().Name
618+
Collection`1
619+
# A single Collection item
620+
PS> $myObject.ForEach('arrayValue').Count
621+
1
622+
# First item in the collection is an array of 11 items
623+
PS> $myObject.ForEach('Value')[0].Count
612624
11
613-
PS> ($c, $d).ForEach('Value')[0][0] # First element of the first array
625+
# Access the first item in the array of 11 items
626+
PS> $myObject.ForEach('Value')[0][0]
614627
0
615-
PS> ($c, $d).ForEach('Value')[1][0] # First element of the second array
616-
11
617628
```
618629

619-
This is different that using the `ForEach()` method using a scriptblock to
630+
This is different than using the `ForEach()` method using with a scriptblock to
620631
access the **Value** property of each object.
621632

622633
```powershell
623-
PS> ($c, $d).ForEach({$_.Value}).Count # 22-element collection
624-
22
634+
PS> $myObject.ForEach({$_.Value}).Count # An array of 11 items
635+
11
625636
```
626637

638+
Use the scriptblock syntax to avoid the wrapping behavior when you want to
639+
access complex property types, such as arrays or nested objects.
640+
627641
#### ForEach(string methodName)
628642

629643
#### ForEach(string methodName, object[] arguments)
630644

631-
Lastly, `ForEach()` methods can be used to execute a method on every item in
632-
the collection.
645+
You can use the `ForEach()` method to execute an object's method on every item
646+
in the collection.
633647

634648
```powershell
635649
("one", "two", "three").ForEach("ToUpper")

‎reference/7.5/Microsoft.PowerShell.Core/About/about_Arrays.md‎

Lines changed: 38 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -585,51 +585,65 @@ Wednesday, June 20, 2018 9:21:57 AM
585585

586586
> [!NOTE]
587587
> The `ForEach()` method wraps properties into a collection before enumeration.
588-
> This wrapping means that accessing the first element of the original
589-
> collection requires two indices `[0][0]`.
588+
> Using `ForEach()` normally returns all items in both array. However, if you
589+
> want to access elements of the wrapped collection, you need to use two
590+
> indices.
590591
591-
Consider the following example:
592+
Consider the following example where the object `$myObject` has a property with
593+
single value and a property containing an array of 11 integers.
592594

593595
```powershell
594-
$c = [pscustomobject]@{
595-
Value = @(0..10)
596-
}
597-
$d = [pscustomobject]@{
598-
Value = @(11..21)
596+
$myObject = [pscustomobject]@{
597+
singleValue = 'Hello'
598+
arrayValue = @(0..10)
599599
}
600600
```
601601

602-
As you can see, both `$c` and `$d` have a property named **Value** that
603-
contains an array of 11 integers. When you use the `ForEach()` method to access
604-
the **Value** property of both objects, the result is a collection of two
605-
arrays. To access the first element of the first array, you need to use two
606-
indices.
602+
When you use the `ForEach()` method to access a property of the object, the
603+
property is wrapped in a collection.
607604

608605
```powershell
609-
PS> ($c, $d).ForEach('Value').Count # 2-element collection
610-
2
611-
PS> ($c, $d).ForEach('Value')[0].Count # Each is an array with 11 elements
606+
PS> $myObject.ForEach('singleValue').GetType().Name
607+
Collection`1
608+
PS> $myObject.ForEach('singleValue')[0].GetType().Name
609+
String
610+
PS> $myObject.ForEach('singleValue') # Enumerate the collection object
611+
Hello
612+
```
613+
614+
To access the an element of the array, you need to use two indices.
615+
616+
```powershell
617+
PS> $myObject.ForEach('arrayValue').GetType().Name
618+
Collection`1
619+
# A single Collection item
620+
PS> $myObject.ForEach('arrayValue').Count
621+
1
622+
# First item in the collection is an array of 11 items
623+
PS> $myObject.ForEach('Value')[0].Count
612624
11
613-
PS> ($c, $d).ForEach('Value')[0][0] # First element of the first array
625+
# Access the first item in the array of 11 items
626+
PS> $myObject.ForEach('Value')[0][0]
614627
0
615-
PS> ($c, $d).ForEach('Value')[1][0] # First element of the second array
616-
11
617628
```
618629

619-
This is different that using the `ForEach()` method using a scriptblock to
630+
This is different than using the `ForEach()` method using with a scriptblock to
620631
access the **Value** property of each object.
621632

622633
```powershell
623-
PS> ($c, $d).ForEach({$_.Value}).Count # 22-element collection
624-
22
634+
PS> $myObject.ForEach({$_.Value}).Count # An array of 11 items
635+
11
625636
```
626637

638+
Use the scriptblock syntax to avoid the wrapping behavior when you want to
639+
access complex property types, such as arrays or nested objects.
640+
627641
#### ForEach(string methodName)
628642

629643
#### ForEach(string methodName, object[] arguments)
630644

631-
Lastly, `ForEach()` methods can be used to execute a method on every item in
632-
the collection.
645+
You can use the `ForEach()` method to execute an object's method on every item
646+
in the collection.
633647

634648
```powershell
635649
("one", "two", "three").ForEach("ToUpper")

‎reference/7.6/Microsoft.PowerShell.Core/About/about_Arrays.md‎

Lines changed: 38 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -592,51 +592,65 @@ Wednesday, June 20, 2018 9:21:57 AM
592592

593593
> [!NOTE]
594594
> The `ForEach()` method wraps properties into a collection before enumeration.
595-
> This wrapping means that accessing the first element of the original
596-
> collection requires two indices `[0][0]`.
595+
> Using `ForEach()` normally returns all items in both array. However, if you
596+
> want to access elements of the wrapped collection, you need to use two
597+
> indices.
597598
598-
Consider the following example:
599+
Consider the following example where the object `$myObject` has a property with
600+
single value and a property containing an array of 11 integers.
599601

600602
```powershell
601-
$c = [pscustomobject]@{
602-
Value = @(0..10)
603-
}
604-
$d = [pscustomobject]@{
605-
Value = @(11..21)
603+
$myObject = [pscustomobject]@{
604+
singleValue = 'Hello'
605+
arrayValue = @(0..10)
606606
}
607607
```
608608

609-
As you can see, both `$c` and `$d` have a property named **Value** that
610-
contains an array of 11 integers. When you use the `ForEach()` method to access
611-
the **Value** property of both objects, the result is a collection of two
612-
arrays. To access the first element of the first array, you need to use two
613-
indices.
609+
When you use the `ForEach()` method to access a property of the object, the
610+
property is wrapped in a collection.
614611

615612
```powershell
616-
PS> ($c, $d).ForEach('Value').Count # 2-element collection
617-
2
618-
PS> ($c, $d).ForEach('Value')[0].Count # Each is an array with 11 elements
613+
PS> $myObject.ForEach('singleValue').GetType().Name
614+
Collection`1
615+
PS> $myObject.ForEach('singleValue')[0].GetType().Name
616+
String
617+
PS> $myObject.ForEach('singleValue') # Enumerate the collection object
618+
Hello
619+
```
620+
621+
To access the an element of the array, you need to use two indices.
622+
623+
```powershell
624+
PS> $myObject.ForEach('arrayValue').GetType().Name
625+
Collection`1
626+
# A single Collection item
627+
PS> $myObject.ForEach('arrayValue').Count
628+
1
629+
# First item in the collection is an array of 11 items
630+
PS> $myObject.ForEach('Value')[0].Count
619631
11
620-
PS> ($c, $d).ForEach('Value')[0][0] # First element of the first array
632+
# Access the first item in the array of 11 items
633+
PS> $myObject.ForEach('Value')[0][0]
621634
0
622-
PS> ($c, $d).ForEach('Value')[1][0] # First element of the second array
623-
11
624635
```
625636

626-
This is different that using the `ForEach()` method using a scriptblock to
637+
This is different than using the `ForEach()` method using with a scriptblock to
627638
access the **Value** property of each object.
628639

629640
```powershell
630-
PS> ($c, $d).ForEach({$_.Value}).Count # 22-element collection
631-
22
641+
PS> $myObject.ForEach({$_.Value}).Count # An array of 11 items
642+
11
632643
```
633644

645+
Use the scriptblock syntax to avoid the wrapping behavior when you want to
646+
access complex property types, such as arrays or nested objects.
647+
634648
#### ForEach(string methodName)
635649

636650
#### ForEach(string methodName, object[] arguments)
637651

638-
Lastly, `ForEach()` methods can be used to execute a method on every item in
639-
the collection.
652+
You can use the `ForEach()` method to execute an object's method on every item
653+
in the collection.
640654

641655
```powershell
642656
("one", "two", "three").ForEach("ToUpper")

0 commit comments

Comments
 (0)